跳转到内容
@aws/nx-plugin
Blog

TypeScript 项目

TypeScript 项目生成器可用于创建配置了最佳实践的现代化 TypeScript 库或应用，这些最佳实践包括 ECMAScript 模块 (ESM)、TypeScript 项目引用、用于运行测试的 Vitest 以及用于静态分析的 ESLint。

使用方式

生成 TypeScript 项目

您可以通过两种方式生成新的 TypeScript 项目：

  1. 安装 Nx Console VSCode Plugin 如果您尚未安装
  2. 在VSCode中打开Nx控制台
  3. 点击 Generate (UI) 在"Common Nx Commands"部分
  4. 搜索 @aws/nx-plugin - ts#project
  5. 填写必需参数
    • 点击 Generate

    选项配置

    参数 类型 默认值 描述
    name 必需 string - TypeScript project name
    directory string packages Parent directory where the library is placed.
    subDirectory string - The sub directory the lib is placed in. By default this is the library name.

    生成器输出

    生成器将在 <directory>/<name> 目录中创建以下项目结构：

    • 文件夹src TypeScript 源代码
      • index.ts
    • project.json 项目配置和构建目标
    • tsconfig.json 本项目的基础 TypeScript 配置（继承工作区根目录的 tsconfig.base.json）
    • tsconfig.lib.json 库的 TypeScript 配置（运行时或打包源码）
    • tsconfig.spec.json 测试的 TypeScript 配置
    • vite.config.ts Vitest 配置
    • eslint.config.mjs ESLint 配置

    您还会发现工作区根目录的以下文件发生了变化：

    • nx.json Nx 配置更新，为您的项目配置 @nx/js/typescript 插件
    • tsconfig.base.json 为您的项目设置了 TypeScript 别名，以便工作区其他项目可以导入
    • tsconfig.json 为您的项目添加了 TypeScript 项目引用

    编写 TypeScript 源代码

    在 src 目录中添加您的 TypeScript 代码。

    ESM 导入语法

    由于您的 TypeScript 项目是 ES 模块，请确保使用正确的 ESM 语法编写导入语句，显式引用文件扩展名：

    index.ts
    import { sayHello } from './hello.js';

    为其他 TypeScript 项目导出

    TypeScript 项目的入口点是 src/index.ts。您可以在此处添加希望其他项目能够导入的导出：

    src/index.ts
    export { sayHello } from './hello.js';
    export * from './algorithms/index.js';

    在其他项目中导入库代码

    工作区 tsconfig.base.json 中配置了项目的 TypeScript 别名，允许您从其他 TypeScript 项目引用本 TypeScript 项目：

    packages/my-other-project/src/index.ts
    import { sayHello } from ':my-scope/my-library';

    当您首次在工作区中为某个新项目添加导入语句时，IDE 中可能会看到类似以下错误：

    导入错误
    Terminal window
    File '/path/to/my/workspace/packages/my-library/src/index.ts' is not under 'rootDir' '/path/to/my/workspace/packages/my-consumer'. 'rootDir' is expected to contain all source files.
      File is ECMAScript module because '/path/to/my/workspace/package.json' has field "type" with value "module" ts(6059)
    File '/path/to/my/workspace/packages/my-library/src/index.ts' is not listed within the file list of project '/path/to/my/workspace/packages/my-consumer/tsconfig.lib.json'. Projects must list all files or use an 'include' pattern.
      File is ECMAScript module because '/path/to/my/workspace/package.json' has field "type" with value "module" ts(6307)

    这是因为尚未设置项目引用。

    TypeScript 项目默认配置了 Nx TypeSync 生成器，您无需手动配置项目引用。只需运行以下命令，Nx 将自动添加所需配置：

    Terminal window
    pnpm nx sync

    此后 IDE 中的错误应会消失，您即可正常使用库。

    依赖管理

    您会注意到 TypeScript 项目没有 package.json 文件，这对于习惯传统 TypeScript monorepo 的用户可能有些意外。

    要为 monorepo 中的任何 TypeScript 包添加依赖，只需将依赖添加到工作区根目录的 package.json。您可以通过包管理器的命令行操作：

    Terminal window
    pnpm add -w some-npm-package

    此后该依赖即可供工作区中所有 TypeScript 项目使用。

    运行时代码

    当您将 TypeScript 项目作为运行时代码使用时（例如作为 AWS Lambda 函数的处理程序），建议使用 esbuild 等工具进行打包，因其支持摇树优化以确保仅包含实际引用的依赖。

    您可以通过在 project.json 文件中添加如下构建目标实现：

    {
      ...
      "targets": {
        ...
        "bundle": {
          "cache": true,
          "executor": "nx:run-commands",
          "outputs": ["{workspaceRoot}/dist/packages/my-library/bundle"],
          "options": {
            "command": "esbuild packages/my-library/src/index.ts --bundle --outfile=dist/packages/my-library/bundle/index.js --platform=node --format=cjs"
          }
        },
      },
    }

    发布到 NPM

    若要将 TypeScript 项目发布到 NPM，必须为其创建 package.json 文件。

    该文件需声明项目引用的依赖。由于构建时项目会解析通过工作区根目录 package.json 安装的依赖，建议配置 Nx 依赖检查 ESLint 插件 以确保发布的 package.json 包含项目中使用的所有依赖。

    构建

    TypeScript 项目配置了 build 构建目标（定义于 project.json），可通过以下命令运行：

    Terminal window
    pnpm nx run <project-name>:build

    其中 <project-name> 是项目的全限定名称。

    build 目标将执行编译、代码检查及测试。

    构建输出位于工作区根目录的 dist 文件夹中，具体路径为 dist/packages/<my-library>/tsc

    测试

    项目使用 Vitest 进行测试。

    编写测试

    测试文件应使用 .spec.ts 或 .test.ts 扩展名，与源码文件共同存放在 src 目录。

    例如：

    • 文件夹src
      • hello.ts 库源码
      • hello.spec.ts 测试文件

    Vitest 提供类似 Jest 的测试语法，支持 describe、it、test 和 expect 等工具函数。

    hello.spec.ts
    import { sayHello } from './hello.js';
    

    describe('sayHello', () => {
    

      it('should greet the caller', () => {
        expect(sayHello('Darth Vader')).toBe('Hello, Darth Vader!');
      });
    

    });

    有关测试编写技巧及依赖模拟等功能的详细信息，请参考 Vitest 文档

    运行测试

    测试将作为项目 build 目标的一部分自动运行，您也可以通过 test 目标单独运行：

    Terminal window
    pnpm nx run <project-name>:test

    使用 -t 标志可运行单个测试或测试套件：

    Terminal window
    pnpm nx run <project-name>:test -t 'sayHello'

    代码检查

    TypeScript 项目使用 ESLint 进行代码检查，配合 Prettier 进行代码格式化。

    建议在工作区根目录的 eslint.config.mjs 文件中配置 ESLint，这样修改会应用于工作区所有 TypeScript 项目，确保一致性。

    同理，您可以在根目录的 .prettierrc 文件中配置 Prettier。

    运行检查器

    要检查项目的代码规范，可运行 lint 目标：

    Terminal window
    pnpm nx run <project-name>:lint

    修复检查问题

    大多数代码规范和格式问题可自动修复。通过添加 --configuration=fix 参数可让 ESLint 自动修复问题：

    Terminal window
    pnpm nx run <project-name>:lint --configuration=fix

    若要修复工作区所有包的检查问题，可运行：

    Terminal window
    pnpm nx run-many --target lint --all --configuration=fix