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

TypeScript 项目

TypeScript 项目生成器可用于创建配置了最佳实践的现代化 TypeScript 库或应用，包括 ECMAScript Modules (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 - Library 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 源代码

    将 TypeScript 代码添加至 src 目录。

    ESM 导入语法

    由于项目采用 ES 模块，需在导入语句中显式指定文件扩展名：

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

    为其他 TypeScript 项目导出

    项目入口点为 src/index.ts，可在此导出供其他项目使用的内容：

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

    在其他项目中导入库代码

    工作区 tsconfig.base.json 中配置了项目的 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 生成器配置，无需手动设置。运行以下命令添加必要配置：

    Terminal window
    pnpm nx sync

    完成后错误将消失，可正常使用库。

    依赖管理

    项目未包含 package.json 文件，与传统 TypeScript 单体仓库不同。

    要添加依赖，请将其加入工作区根目录的 package.json 中。可通过包管理器命令行操作：

    Terminal window
    pnpm add -w some-npm-package

    依赖将可供工作区所有 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

    若需发布到 NPM，必须创建 package.json。需声明所有依赖，建议配置 Nx 依赖检查 ESLint 插件确保依赖完整性。

    构建

    项目配置了 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 目标自动运行，也可单独执行：

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

    使用 -t 标志运行特定测试套件：

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

    代码检查

    项目使用 ESLint 进行代码检查，Prettier 进行格式化。建议在工作区根目录的 eslint.config.mjs 中配置 ESLint，以确保一致性。Prettier 配置于根目录 .prettierrc 文件。

    运行检查

    执行 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