TypeScript 项目

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

用法

生成 TypeScript 项目

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

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

VSCode

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

选项

参数	类型	默认值	描述
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 项目导出

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

src/index.ts

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

在其他项目中导入您的库代码

您的项目的 TypeScript 别名在工作区的 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 代码检查规则强制要求项目的源代码只能导入在其自己的 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 中关闭代码检查规则：

biome.json

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

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

运行时代码

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

您可以通过向 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',
      codeSplitting: false,
    },
  },
]);

打包配置

请注意，在上述目标中，我们选择 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 目标将编译、检查和测试您的项目。

构建输出可以在工作区的根 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>

修复代码检查问题

大多数代码检查或格式化问题可以通过使用 --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

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

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

跳过代码检查问题

为了避免代码检查问题在开发过程中拖慢您的速度（特别是如果您的项目中有无法自动修复的问题），您可以使用 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

这会在构建期间完全跳过代码检查目标。

简写命令

这在工作区根目录有一个简写命令：

pnpm

pnpm build:skip-lint

yarn

yarn build:skip-lint

npm

npm run build:skip-lint

bun

bun build:skip-lint