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
• 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

Không cần package.json

Lưu ý rằng không có file package.json nào được tạo cho dự án này! Bạn có thể tìm hiểu lý do 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';

Bí danh dự án

Aliases cho các dự án TypeScript của bạn bắt đầu bằng : thay vì @ truyền thống, vì điều này tránh khả năng xung đột tên giữa các packages cục bộ trong workspace của bạn và các packages từ xa trong NPM.

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.

Các dự án TypeScript được cấu hình với Nx TypeScript Sync generator ngay từ đầu, giúp bạn không cần phải cấu hình project reference 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

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 và bạn sẽ được nhắc với thông báo như:

[@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

Chọn Yes để cho phép Nx cập nhật các project references 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

Bạn sẽ nhận thấy rằng dự án TypeScript của bạn không có file package.json, điều này có thể bất ngờ nếu bạn quen với các monorepos TypeScript truyền thống.

Để thêm một dependency cho bất kỳ package TypeScript nào trong monorepo của bạn, chỉ cần thêm dependency vào package.json ở root của workspace. Bạn có thể thực hiện điều này qua command line cho package manager của bạn:

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

Dependency sau đó có sẵn cho bất kỳ dự án TypeScript nào trong workspace của bạn sử dụng.

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.

Publish lên NPM

Nếu bạn đang publish dự án TypeScript của mình lên NPM, bạn phải tạo một file package.json cho nó.

File này phải khai báo các dependencies mà dự án của bạn tham chiếu. Vì tại thời điểm build, dự án của bạn sẽ resolve các dependencies được cài đặt qua package.json ở workspace root, quy tắc noUndeclaredDependencies của Biome sẽ cảnh báo nếu dự án của bạn import một package không được liệt kê trong package.json của nó.

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