TypeScript 项目

TypeScript项目生成器可用于创建配置了最佳实践的现代化TypeScript库或应用，包括ECMAScript Modules (ESM)、TypeScript项目引用、用于运行测试的Vitest以及用于代码检查和格式化的Biome。

用法

生成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 项目名称
directory	string	packages	库所放置的父目录。
subDirectory	string	-	库所放置的子目录。默认情况下，这是库的名称。
preferInstallDependencies	boolean	true	是否在生成器运行后优先安装依赖项。设置为 false 可在批量运行多个生成器时延迟安装（如果后续生成器需要计算 Nx 项目图，仍会运行安装）；在最后统一安装一次。

生成器输出

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

• 文件夹src TypeScript 源代码

  • index.ts
• package.json 定义项目包名和依赖的项目清单
• project.json 项目配置和构建目标
• tsconfig.json 此项目的基础 TypeScript 配置（继承工作区根目录的 tsconfig.base.json）
• tsconfig.lib.json 库的 TypeScript 配置（运行时或打包源码）
• tsconfig.spec.json 测试的 TypeScript 配置
• vitest.config.mts Vitest 配置

项目 package.json

项目的 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引用

虽然我们使用TypeScript且sayHello定义在hello.ts中，但导入时使用.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可能会显示类似以下错误：

导入错误

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)

这是因为尚未设置项目引用，并且导入的项目尚未在您项目的 package.json 中声明为工作区依赖。

您的工作区配置了同步生成器，可以为您管理这两者，因此您无需手动配置它们。只需运行以下命令，Nx 将添加所需的配置：

pnpm

pnpm nx sync

yarn

yarn nx sync

npm

npx nx sync

bun

bunx nx sync

 NX   The workspace is out of sync

[@nx/js:typescript-sync]: Some TypeScript configuration files are missing project references to the projects they depend on, contain stale project references, or have duplicate project references.
[@aws/nx-plugin:ts#sync]: Local project dependencies are out of sync. The following workspace dependencies will be declared:
packages/my-other-project/package.json:
- @my-scope/my-library: workspace:*

Syncing the workspace...
The workspace was synced successfully!

Nx 的 TypeScript 同步生成器添加项目引用，而插件的 ts#sync 生成器在您项目的 package.json 中声明导入的项目（在包管理器支持工作区协议的情况下为 workspace:*，在 npm 和 yarn classic 上为 *），以便包管理器在安装时链接本地项目。此后 IDE 错误应消失，即可正常使用库。

构建快捷方式

您也可以直接构建项目——同步生成器会先运行，并提示您应用任何未完成的更改：

 NX   The workspace is out of sync

...

? 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 同步您的工作区。

保持路径别名同步

如果您在项目的 tsconfig.json 中添加自定义的 compilerOptions.paths 条目，TypeScript 将停止继承 tsconfig.base.json 中定义的工作区别名。隐藏的 ts#sync 生成器会在 compile 目标之前运行（在 nx.json 中配置），将任何缺失的基础别名复制到已声明 paths 的 tsconfig.json、tsconfig.lib.json 和 tsconfig.app.json 文件中。要禁用此功能，请从 nx.json 的 targetDefaults.compile.syncGenerators 中移除 @aws/nx-plugin:ts#sync。

依赖管理

每个 TypeScript 项目在其自己的 package.json 中声明其第三方运行时依赖。跨项目共享的构建和测试工具在根 package.json 中定义。

要向项目添加运行时依赖，请将其安装到该项目中：

pnpm

pnpm add some-npm-package --filter my-library

yarn

yarn workspace @my-scope/my-library add some-npm-package

npm

npm install --legacy-peer-deps some-npm-package -w packages/my-library

bun

bun add some-npm-package --cwd packages/my-library

您也可以在项目目录中运行包管理器的普通 add/install 命令。

要添加共享的开发工具，请将其安装到工作区根目录：

pnpm

pnpm add -Dw some-dev-tool

yarn

yarn add -D some-dev-tool

npm

npm install --legacy-peer-deps -D some-dev-tool

bun

bun add -D some-dev-tool

注意

Biome 的 noUndeclaredDependencies lint 规则强制项目的源代码只能导入在其自己的 package.json 中声明的包。配置文件、构建脚本和测试被豁免，因此共享工具可以保留在根目录。

目录

对于支持目录的包管理器（pnpm、yarn 和 bun），生成器会在目录中记录每个版本，并使用 catalog: 协议引用它（例如 "zod": "catalog:"），因此无论哪个项目声明依赖，目录都是版本的唯一真实来源。这有助于您遵循单一版本策略，避免类型冲突和部署包中的多个包副本。

当您自己添加新依赖时，也要将其保留在目录中：

pnpm

工作区设置了 catalogMode: strict，因此 pnpm add 会在目录中记录版本并自动引用它——无需额外步骤。

pnpm add some-npm-package --filter my-library

yarn

yarn 的 catalog: 协议只能引用现有的目录条目——无法创建新条目——因此请先记录版本。

1. 在 .yarnrc.yml 的 catalog 下添加版本：

   .yarnrc.yml

   catalog:
     some-npm-package: ^1.0.0

2. 从项目中引用它：

   yarn workspace @my-scope/my-library add some-npm-package@catalog:

bun

bun 的 catalog: 协议只能引用现有的目录条目——无法创建新条目——因此请先记录版本。

1. 在根目录 package.json 的 catalog 下添加版本：

   package.json

   {
     "catalog": {
       "some-npm-package": "^1.0.0"
     }
   }

2. 从项目中引用它：

   bun add some-npm-package@catalog: --cwd packages/my-library

在 npm 上对齐版本

npm 没有目录功能，因此版本直接在每个 package.json 中声明。要在项目之间保持一致，我们推荐使用 syncpack（npx syncpack lint）。

选择退出目录

目录默认启用。要关闭它们，请使用 --catalog false 创建工作区：

pnpm

pnpm create @aws/nx-workspace my-project --catalog false

yarn

yarn create @aws/nx-workspace my-project --catalog false

npm

npm create @aws/nx-workspace -- my-project --catalog false

bun

bun create @aws/nx-workspace my-project --catalog false

或随时在 aws-nx-plugin.config.mts 中设置：

aws-nx-plugin.config.mts

export default {
  packageManager: {
    catalogs: false,
  },
} satisfies AwsNxPluginConfig;

禁用目录后，生成器会将依赖版本直接写入每个项目的 package.json，保持项目间版本一致是您的责任。

在根目录声明所有依赖

如果您更喜欢仅在根目录 package.json 中声明所有依赖（不进行每个项目的依赖声明），请在工作区 biome.json 中关闭 lint 规则：

biome.json

{
  "linter": {
    "rules": {
      "correctness": {
        "noUndeclaredDependencies": "off"
      }
    }
  }
}

项目在构建时解析根目录安装的包，因此一切仍然可以构建——您放弃了每个项目清单作为每个项目依赖的准确记录（如果您以后发布项目或拆分仓库，这很重要）。

运行时代码

当您将 TypeScript 项目用作运行时代码（例如作为 AWS Lambda 函数的处理程序）时，建议使用 Rolldown 等工具来打包项目，因为这可以进行 tree-shaking 以确保仅包含项目实际引用的依赖。

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

{
  ...
  "targets": {
    ...
    "bundle": {
      "cache": true,
      "executor": "nx:run-commands",
      "outputs": ["{workspaceRoot}/dist/packages/my-library/bundle"],
      "options": {
        "command": "rolldown -c rolldown.config.ts"
      }
    },
  },
}

并添加 rolldown.config.ts 文件如下：

rolldown.config.ts

import { defineConfig } from 'rolldown';

export default defineConfig([
  {
    input: 'src/index.ts',
    output: {
      file: '../../dist/packages/my-library/bundle/index.js',
      format: 'cjs',
      inlineDynamicImports: true,
    },
  },
]);

打包配置

请注意，在上述目标中，我们选择 src/index.ts 作为打包的入口点，这意味着从此文件导出的代码将包含在包中，以及其所有依赖。

Lambda 函数

如果您正在构建 AWS Lambda 函数，请查看 ts#lambda-function 生成器，因为它会为您配置打包，并生成基础设施和添加可观测性和类型安全。

构建

您的 TypeScript 项目配置了 build 目标（定义在 project.json 中），您可以通过以下方式运行：

pnpm

pnpm nx build <project-name>

yarn

yarn nx build <project-name>

npm

npx nx build <project-name>

bun

bunx nx build <project-name>

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

build 目标将编译、lint 和测试您的项目。

构建输出可以在工作区根目录的 dist 文件夹中找到，位于您的包和目标的目录中，例如 dist/packages/<my-library>/tsc

要构建工作区中所有项目，请运行：

pnpm

pnpm nx run-many --target build

yarn

yarn nx run-many --target build

npm

npx nx run-many --target build

bun

bunx nx run-many --target build

或使用简写命令：

pnpm

pnpm build

yarn

yarn build

npm

npm run build

bun

bun build

测试

Vitest 已配置用于测试您的项目。

编写测试

测试应写在 .spec.ts 或 .test.ts 文件中，与项目的 src 文件夹中的代码共置。

例如：

• 文件夹src

  • hello.ts 库源代码
  • hello.spec.ts hello.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 test <project-name>

yarn

yarn nx test <project-name>

npm

npx nx test <project-name>

bun

bunx nx test <project-name>

您可以使用 Vitest 的 -t 标志运行单个测试或测试套件。在 -- 分隔符之后传递它，以便 Nx 将其转发给 Vitest，而不是将其作为自己的 --target 选项使用：

pnpm

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

yarn

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

npm

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

bun

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

VSCode 集成

如果您是 VSCode 用户，我们建议安装 Vitest Runner for VSCode that actually works 扩展，它允许您从 IDE 运行、监视或调试测试。

代码检查

TypeScript 项目使用 Biome 进行代码检查和格式化。Biome 在工作区根目录的 biome.json 文件中配置——对此文件的更改将应用于工作区中的所有 TypeScript 项目并确保一致性。

运行检查器

要调用检查器来检查您的项目，您可以运行 lint 目标。

pnpm

pnpm nx lint <project-name>

yarn

yarn nx lint <project-name>

npm

npx nx lint <project-name>

bun

bunx nx lint <project-name>

修复 Lint 问题

大多数代码检查或格式化问题可以通过使用 --configuration=fix 参数运行来自动修复。

pnpm

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

yarn

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

npm

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

bun

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

同样，如果您想修复工作区中所有包的所有 lint 问题，可以运行：

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

简写命令

这有一个从工作区根目录运行的简写命令：

pnpm

pnpm lint

yarn

yarn lint

npm

npm run lint

bun

bun lint

跳过 Lint 问题

为了避免代码检查问题在开发过程中拖慢您的速度（特别是如果您的项目中有无法自动修复的问题），您可以使用 skip-lint 配置运行构建：

pnpm

pnpm nx run-many --target build --configuration=skip-lint

yarn

yarn nx run-many --target build --configuration=skip-lint

npm

npx nx run-many --target build --configuration=skip-lint

bun

bunx nx run-many --target build --configuration=skip-lint

这会在构建期间完全跳过lint目标。

简写命令

这有一个从工作区根目录运行的简写命令：

pnpm

pnpm build:skip-lint

yarn

yarn build:skip-lint

npm

npm run build:skip-lint

bun

bun build:skip-lint