TypeScript 项目

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

项目的入口点是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';

注意

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 TypeScript同步生成器，您无需手动配置项目引用。只需运行以下命令，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中的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函数处理程序）时，建议使用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作为打包入口点，意味着该文件导出的代码及其依赖将被包含在包中。

提示

如需构建AWS Lambda函数，可查看ts#lambda-function生成器，该生成器已配置打包并生成基础设施，添加可观测性和类型安全。

发布到NPM

如需将TypeScript项目发布到NPM，必须创建package.json文件。

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

构建

项目配置了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目标将编译、lint和测试项目。

构建输出位于工作区根目录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

要修复工作区所有包的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