SuperAPI AI 工具集

ts-runtime-node

编程与开发

查看项目

更新于 10-26 16:22

技能介绍

该技能聚焦于在Node.js上原生运行TypeScript,不引入构建步骤的场景,属于编程与开发类的知识型技能。

用途:帮助开发者在无打包器的前提下,用node直接执行.ts/.mts/.cts文件;判断何时原生类型剥离已够用、何时必须改用完整加载器tsx;搭建ESM-only的Node项目、使用--watch模式和node:test;以及将脚本、CLI或钩子从ts-node迁移到Node内置支持。

主要能力与规则:原生类型剥离采用“仅擦除”方式,Node把类型替换为空白,不进行任何类型检查,因此需另行运行tsc --noEmit保证类型安全;tsconfig.json在运行时被忽略,paths、降级和JS目标lowering均不生效;不可擦除语法(enum、含运行时代码的namespace、参数属性、import别名)会抛出ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX;类型导入必须使用import type或verbatimModuleSyntax,否则值导入类型会在运行时崩溃;导入必须带扩展名(如./file.ts),且原生剥离不支持.tsx。

使用方式:文档给出项目结构模板,包括package.json声明"type":"module"、tsconfig.json启用noEmit/erasableSyntaxOnly/verbatimModuleSyntax、src/index.ts入口、test/unit.test.ts测试;参考指南分为概念类(type-stripping.md、tsx-when-needed.md、node24-features.md)与模板类(node-esm-setup.md)。同时规定强制代理工作流:实施前并行调用三个代理分别探索代码库、核对最新Node LTS与类型剥离行为、查询Node Modules类型与CLI标志文档;实施后运行验证代理。

适用场景:直接运行TypeScript源码、选择原生剥离或tsx、ESM项目搭建、watch与测试、ts-node迁移。

限制与边界:Bun运行时与bun test属于ts-runtime-bun;tsconfig细节属于ts-config;Lint/格式化属于ts-lint-format;Next.js、Astro等自带转译管线的框架运行时不适用;浏览器/打包产物应使用打包技能;不要在node_modules中发布.ts文件,Node拒绝剥离;不要依赖原生剥离处理装饰器(TC39 Stage 3,未转换)。文中未提供的具体版本要求、安装命令与性能数据暂未说明。