Dự án TypeScript

Generator dự án TypeScript có thể được sử dụng để tạo một thư viện hoặc ứng dụng TypeScript hiện đại được cấu hình với các phương pháp hay nhất như ECMAScript Modules (ESM), project references của TypeScript, Vitest để chạy tests và Biome để linting và định dạng.

Cách Sử Dụng

Tạo một Dự Án TypeScript

Bạn có thể tạo một dự án TypeScript mới theo hai cách:

VSCode

1. Cài đặt Nx Console VSCode Plugin nếu bạn chưa cài đặt
2. Mở Nx Console trong VSCode
3. Nhấp Generate (UI) trong phần "Common Nx Commands"
4. Tìm kiếm @aws/nx-plugin - ts#project
5. Điền các tham số bắt buộc
6. Nhấp 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

Bạn cũng có thể thực hiện chạy thử để xem những tệp nào sẽ bị thay đổi

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

Tùy Chọn

Tham số	Kiểu	Mặc định	Mô tả
name Bắt buộc	string	-	Tên dự án TypeScript
directory	string	packages	Thư mục cha nơi thư viện được đặt.
subDirectory	string	-	Thư mục con nơi thư viện được đặt. Mặc định đây là tên thư viện.
preferInstallDependencies	boolean	true	Có nên ưu tiên cài đặt các dependencies sau khi generator chạy hay không. Đặt thành false để hoãn việc cài đặt khi chạy nhiều generator liên tiếp (việc cài đặt vẫn sẽ chạy nếu cần thiết để các generator tiếp theo có thể tính toán Nx project graph); cài đặt một lần vào cuối.

Kết Quả từ Generator

Generator sẽ tạo cấu trúc dự án sau trong thư mục <directory>/<name>:

• Thư mụcsrc Mã nguồn TypeScript

  • index.ts
• package.json Manifest dự án định nghĩa tên package và dependencies của dự án
• project.json Cấu hình dự án và các build targets
• tsconfig.json Cấu hình TypeScript cơ bản cho dự án này (kế thừa từ tsconfig.base.json ở workspace root)
• tsconfig.lib.json Cấu hình TypeScript cho thư viện của bạn (mã nguồn runtime hoặc đóng gói)
• tsconfig.spec.json Cấu hình TypeScript cho các tests
• vitest.config.mts Cấu hình cho Vitest

package.json của dự án

package.json của dự án bắt đầu tối thiểu. Khi bạn thêm các runtime dependencies, chúng được khai báo ở đây (các công cụ build/test dùng chung vẫn ở workspace root) — bạn có thể tìm hiểu thêm bên dưới.

Bạn cũng sẽ nhận thấy một số thay đổi đối với các file sau trong workspace root của bạn:

• nx.json Cấu hình Nx được cập nhật để cấu hình @nx/js/typescript plugin cho dự án của bạn
• tsconfig.base.json một alias TypeScript được thiết lập cho dự án của bạn để nó có thể được import bởi các dự án khác trong workspace
• tsconfig.json một project reference TypeScript được thêm vào cho dự án của bạn

Viết Mã Nguồn TypeScript

Thêm mã TypeScript của bạn vào thư mục src.

Cú Pháp Import ESM

Vì dự án TypeScript của bạn là một ES Module, hãy chắc chắn viết các câu lệnh import với cú pháp ESM chính xác, tham chiếu rõ ràng đến phần mở rộng file:

index.ts

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

Tham chiếu TypeScript

Mặc dù chúng ta đang sử dụng TypeScript, và sayHello được định nghĩa trong hello.ts, chúng ta sử dụng phần mở rộng file .js trong import. Bạn có thể đọc thêm về điều này tại đây.

Export cho Các Dự Án TypeScript Khác

Entry point cho dự án TypeScript của bạn là src/index.ts. Bạn có thể thêm exports ở đây cho bất cứ thứ gì bạn muốn các dự án khác có thể import:

src/index.ts

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

Import Mã Thư Viện của Bạn trong Các Dự Án Khác

TypeScript aliases cho dự án của bạn được cấu hình trong tsconfig.base.json của workspace, cho phép bạn tham chiếu dự án TypeScript của mình từ các dự án TypeScript khác:

packages/my-other-project/src/index.ts

import { sayHello } from '@my-scope/my-library';

Khi bạn thêm một câu lệnh import cho một dự án mới trong workspace lần đầu tiên, bạn có thể sẽ thấy lỗi trong IDE tương tự như bên dưới:

Lỗi import

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)

Điều này là do một project reference chưa được thiết lập, và dự án được import chưa được khai báo làm workspace dependency trong package.json của dự án của bạn.

Workspace của bạn được cấu hình với các sync generators quản lý cả hai cho bạn, vì vậy bạn không cần cấu hình chúng thủ công. Chỉ cần chạy lệnh sau và Nx sẽ thêm cấu hình cần thiết:

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!

TypeScript sync generator của Nx thêm project reference, và generator ts#sync của plugin khai báo dự án được import trong package.json của dự án của bạn (workspace:* khi package manager hỗ trợ workspace protocol, * trên npm và yarn classic), vì vậy package manager liên kết dự án cục bộ khi cài đặt. Sau đó, lỗi trong IDE của bạn sẽ biến mất và bạn đã sẵn sàng sử dụng thư viện của mình.

Phím tắt build

Bạn cũng có thể chỉ cần build dự án — các sync generators chạy trước và bạn sẽ được nhắc áp dụng bất kỳ thay đổi nào còn tồn đọng:

 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

Chọn Yes để cho phép Nx đồng bộ workspace của bạn.

Giữ Đồng Bộ Path Aliases

Nếu bạn thêm các entries compilerOptions.paths tùy chỉnh trong tsconfig.json của một dự án, TypeScript sẽ ngừng kế thừa các aliases workspace được định nghĩa trong tsconfig.base.json. Generator ẩn ts#sync chạy trước compile target (được cấu hình trong nx.json) để sao chép bất kỳ base aliases còn thiếu nào vào các files tsconfig.json, tsconfig.lib.json và tsconfig.app.json đã khai báo paths. Để tắt tính năng này, hãy xóa @aws/nx-plugin:ts#sync khỏi targetDefaults.compile.syncGenerators trong nx.json.

Dependencies

Mỗi dự án TypeScript khai báo các runtime dependencies của bên thứ ba trong package.json riêng của nó. Các công cụ build và test dùng chung giữa các dự án được định nghĩa trong package.json root.

Để thêm một runtime dependency vào một dự án, hãy cài đặt nó vào dự án đó:

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

Bạn cũng có thể chạy lệnh add/install thông thường của package manager từ trong thư mục của dự án.

Để thêm một công cụ dev dùng chung, hãy cài đặt nó ở workspace root:

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

Ghi chú

Quy tắc lint noUndeclaredDependencies của Biome đảm bảo rằng mã nguồn của một dự án chỉ import các packages được khai báo trong package.json riêng của nó. Các file cấu hình, build scripts và tests được miễn trừ, vì vậy các công cụ dùng chung có thể ở lại root.

Catalogs

Đối với các package managers hỗ trợ catalogs (pnpm, yarn và bun), các generators ghi lại mỗi phiên bản trong catalog và tham chiếu nó bằng protocol catalog: (ví dụ "zod": "catalog:"), vì vậy catalog là nguồn duy nhất về phiên bản bất kể dự án nào khai báo dependency. Điều này giúp bạn tuân theo single version policy, tránh xung đột kiểu và nhiều bản sao của các packages trong deployment bundles.

Khi bạn tự thêm một dependency mới, hãy giữ nó trong catalog:

pnpm

Workspace đặt catalogMode: strict, vì vậy pnpm add ghi lại phiên bản trong catalog và tham chiếu nó tự động — không cần bước bổ sung.

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

yarn

Protocol catalog: của yarn chỉ tham chiếu một entry catalog hiện có — nó không thể tạo một entry mới — vì vậy hãy ghi lại phiên bản trước.

1. Thêm phiên bản dưới catalog trong .yarnrc.yml:

   .yarnrc.yml

   catalog:
     some-npm-package: ^1.0.0

2. Tham chiếu nó từ dự án:

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

bun

Protocol catalog: của bun chỉ tham chiếu một entry catalog hiện có — nó không thể tạo một entry mới — vì vậy hãy ghi lại phiên bản trước.

1. Thêm phiên bản dưới catalog trong package.json root:

   package.json

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

2. Tham chiếu nó từ dự án:

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

Căn chỉnh phiên bản trên npm

npm không có tính năng catalog, vì vậy các phiên bản được khai báo trực tiếp trong mỗi package.json. Để giữ chúng nhất quán giữa các dự án, chúng tôi khuyên dùng syncpack (npx syncpack lint).

Tắt catalogs

Catalogs được bật theo mặc định. Để tắt chúng, hãy tạo workspace của bạn với --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

Hoặc đặt nó trong aws-nx-plugin.config.mts bất cứ lúc nào:

aws-nx-plugin.config.mts

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

Khi catalogs bị tắt, các generators ghi phiên bản dependency trực tiếp vào package.json của mỗi dự án, và việc giữ các phiên bản căn chỉnh giữa các dự án là trách nhiệm của bạn.

Khai báo tất cả dependencies ở root

Nếu bạn muốn khai báo mọi dependency chỉ trong package.json root (không có khai báo dependency cho từng dự án), hãy tắt quy tắc lint trong biome.json của workspace:

biome.json

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

Các dự án resolve các packages được cài đặt ở root tại thời điểm build, vì vậy mọi thứ vẫn build được — bạn từ bỏ việc các manifest của từng dự án là một bản ghi chính xác về các dependencies của mỗi dự án (điều này quan trọng nếu sau này bạn publish một dự án hoặc tách repo).

Mã Runtime

Khi bạn sử dụng dự án TypeScript của mình làm mã runtime (ví dụ như handler cho một AWS Lambda function), được khuyến nghị là bạn sử dụng một công cụ như Rolldown để bundle dự án của bạn, vì điều này có thể tree-shake để đảm bảo rằng chỉ các dependencies mà dự án của bạn thực sự tham chiếu được bao gồm.

Bạn có thể đạt được điều này bằng cách thêm một target như sau vào file project.json của bạn:

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

Và thêm file rolldown.config.ts như sau:

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,
    },
  },
]);

Cấu hình đóng gói

Lưu ý rằng trong target trên, chúng ta đã chọn src/index.ts làm entrypoint cho bundle, có nghĩa là mã được export từ file này sẽ được bao gồm trong bundle, cùng với tất cả các dependencies của nó.

Hàm Lambda

Nếu bạn đang xây dựng một AWS Lambda function, hãy xem generator ts#lambda-function vì nó cấu hình bundling cho bạn, cũng như tạo infrastructure và thêm observability và type-safety.

Building

Dự án TypeScript của bạn được cấu hình với một build target (được định nghĩa trong project.json), bạn có thể chạy qua:

pnpm

pnpm nx build <project-name>

yarn

yarn nx build <project-name>

npm

npx nx build <project-name>

bun

bunx nx build <project-name>

Trong đó <project-name> là tên đầy đủ của dự án của bạn.

build target sẽ compile, lint và test dự án của bạn.

Kết quả build có thể được tìm thấy trong thư mục dist root trong workspace của bạn, bên trong một thư mục cho package và target của bạn, ví dụ dist/packages/<my-library>/tsc

Để build tất cả các dự án trong workspace của bạn, chạy:

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

Hoặc sử dụng lệnh rút gọn:

pnpm

pnpm build

yarn

yarn build

npm

npm run build

bun

bun build

Testing

Vitest được cấu hình để test dự án của bạn.

Viết Tests

Tests nên được viết trong các file .spec.ts hoặc .test.ts, đặt cùng vị trí trong thư mục src của dự án.

Ví dụ:

• Thư mụcsrc

  • hello.ts Mã nguồn thư viện
  • hello.spec.ts Tests cho hello.ts

Vitest cung cấp cú pháp giống Jest để định nghĩa tests, với các tiện ích như describe, it, test và expect.

hello.spec.ts

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

describe('sayHello', () => {

  it('should greet the caller', () => {
    expect(sayHello('Darth Vader')).toBe('Hello, Darth Vader!');
  });

});

Để biết thêm chi tiết về cách viết tests và các tính năng như mocking dependencies, tham khảo tài liệu Vitest

Chạy Tests

Tests sẽ chạy như một phần của build target cho dự án của bạn, nhưng bạn cũng có thể chạy chúng riêng biệt bằng cách chạy test target:

pnpm

pnpm nx test <project-name>

yarn

yarn nx test <project-name>

npm

npx nx test <project-name>

bun

bunx nx test <project-name>

Bạn có thể chạy một test riêng lẻ hoặc một suite tests bằng cách sử dụng flag -t của Vitest. Truyền nó sau dấu phân cách -- để Nx chuyển tiếp nó cho Vitest thay vì sử dụng nó như tùy chọn --target của chính nó:

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'

Tích hợp VSCode

Nếu bạn là người dùng VSCode, chúng tôi khuyên bạn nên cài đặt extension Vitest Runner for VSCode that actually works, cho phép bạn chạy, watch hoặc debug tests từ IDE của mình.

Linting

Các dự án TypeScript sử dụng Biome để linting và định dạng. Biome được cấu hình trong file biome.json ở workspace root — các thay đổi tại đây áp dụng cho tất cả các dự án TypeScript trong workspace của bạn và đảm bảo tính nhất quán.

Chạy Linter

Để gọi linter kiểm tra dự án của bạn, bạn có thể chạy lint target.

pnpm

pnpm nx lint <project-name>

yarn

yarn nx lint <project-name>

npm

npx nx lint <project-name>

bun

bunx nx lint <project-name>

Sửa Các Vấn Đề Lint

Phần lớn các vấn đề linting hoặc formatting có thể được sửa tự động bằng cách chạy với argument --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

Tương tự, nếu bạn muốn sửa tất cả các vấn đề lint trong tất cả các packages trong workspace của bạn, bạn có thể chạy:

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

Lệnh viết tắt

Lệnh này có một lệnh rút gọn từ root của workspace:

pnpm

pnpm lint

yarn

yarn lint

npm

npm run lint

bun

bun lint

Bỏ Qua Các Vấn Đề Lint

Để tránh các vấn đề linting làm chậm bạn trong quá trình phát triển (đặc biệt nếu bạn có các vấn đề không thể tự động sửa trong dự án của mình), bạn có thể chạy một build với cấu hình 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

Điều này bỏ qua hoàn toàn lint target trong quá trình build.

Lệnh viết tắt

Lệnh này có một lệnh rút gọn từ root của workspace:

pnpm

pnpm build:skip-lint

yarn

yarn build:skip-lint

npm

npm run build:skip-lint

bun

bun build:skip-lint