TypeScript 项目

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

使用方式

生成 TypeScript 项目

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

VSCode

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

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#project

yarn

yarn nx g @aws/nx-plugin:ts#project

npm

npx nx g @aws/nx-plugin:ts#project

bun

bunx nx g @aws/nx-plugin:ts#project

您还可以执行试运行以查看哪些文件会被更改

pnpm

pnpm nx g @aws/nx-plugin:ts#project --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#project --dry-run

npm

npx nx g @aws/nx-plugin:ts#project --dry-run

bun

bunx nx g @aws/nx-plugin:ts#project --dry-run

选项配置

参数	类型	默认值	描述
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 配置

提示

注意本项目不会创建 package.json 文件！您可以在下方了解原因。

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

• 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，且 sayHello 定义在 hello.ts 中，但我们在导入时使用 .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';

注意

TypeScript 项目的别名以 : 开头而非传统的 @，这可以避免工作区本地包与 NPM 远程包之间的命名冲突。

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

导入错误

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 将自动添加所需配置：

pnpm

pnpm nx sync

yarn

yarn nx sync

npm

npx nx sync

bun

bunx nx sync

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

提示

您也可以直接构建项目，此时会看到如下提示：

[@nx/js:typescript-sync]: Some TypeScript configuration files are missing project references to the projects they depend on or contain outdated project references.

This will result in an error in CI.

? Would you like to sync the identified changes to get your workspace up to date?
Yes, sync the changes and run the tasks
No, run the tasks without syncing the changes

选择 Yes 允许 Nx 更新项目引用。

依赖管理

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

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

pnpm

pnpm add -w some-npm-package

yarn

yarn add some-npm-package

npm

npm install --legacy-peer-deps some-npm-package

bun

bun install 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"
      }
    },
  },
}

注意

注意上述构建目标中，我们选择 src/index.ts 作为打包入口文件，这意味着该文件导出的代码及其所有依赖都将包含在打包结果中。

发布到 NPM

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

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

构建

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

pnpm

pnpm nx run <project-name>:build

yarn

yarn nx run <project-name>:build

npm

npx nx run <project-name>:build

bun

bunx 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 目标单独运行：

pnpm

pnpm nx run <project-name>:test

yarn

yarn nx run <project-name>:test

npm

npx nx run <project-name>:test

bun

bunx nx run <project-name>:test

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

pnpm

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

yarn

yarn nx run <project-name>:test -t 'sayHello'

npm

npx nx run <project-name>:test -t 'sayHello'

bun

bunx nx run <project-name>:test -t 'sayHello'

提示

VSCode 用户建议安装 真正可用的 Vitest Runner 扩展，支持直接从 IDE 运行、监视或调试测试。

代码检查

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

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

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

运行检查器

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

pnpm

pnpm nx run <project-name>:lint

yarn

yarn nx run <project-name>:lint

npm

npx nx run <project-name>:lint

bun

bunx nx run <project-name>:lint

修复检查问题

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

pnpm

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

yarn

yarn nx run <project-name>:lint --configuration=fix

npm

npx nx run <project-name>:lint --configuration=fix

bun

bunx nx run <project-name>:lint --configuration=fix

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

pnpm

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

yarn

yarn nx run-many --target lint --all --configuration=fix

npm

npx nx run-many --target lint --all --configuration=fix

bun

bunx nx run-many --target lint --all --configuration=fix