☰ Mục lục series
Tài liệu NestJS tiếng Việt
  1. Nhập môn (Overview)
    1. Giới thiệu
    2. First steps
    3. Controllers
    4. Providers
    5. Modules
    6. Middleware
    7. Exception filters
    8. Pipes
    9. Guards
    10. Interceptors
    11. Custom decorators
  2. Nền tảng (Fundamentals)
    1. Custom providers
    2. Asynchronous providers
    3. Dynamic modules
    4. Injection scopes
    5. Circular dependency
    6. Module reference
    7. Lazy-loading modules
    8. Execution context
    9. Lifecycle events
    10. Discovery service
    11. Platform agnosticism
    12. Testing
  3. Kỹ thuật (Techniques)
    1. Configuration
    2. Database (SQL)
    3. MongoDB
    4. Validation
    5. Caching
    6. Serialization
    7. Versioning
    8. Task scheduling
    9. Queues
    10. Logging
    11. Cookies
    12. Events
    13. Compression
    14. File upload
    15. Streaming files
    16. HTTP module
    17. Session
    18. MVC
    19. Performance (Fastify)
    20. Server-Sent Events
  4. Bảo mật (Security)
    1. Authentication
    2. Authorization
    3. Encryption & Hashing
    4. Helmet
    5. CORS
    6. CSRF
    7. Rate limiting
    8. Vòng đời request
  5. OpenAPI (Swagger)
    1. Introduction
    2. Types and parameters
    3. Operations
    4. Security
    5. Mapped types
    6. Decorators
    7. CLI plugin
    8. Other features
  6. Recipes
    1. REPL
    2. CRUD generator
    3. SWC (fast compiler)
    4. Passport (auth)
    5. Hot reload
    6. MikroORM
    7. Router module
    8. Health checks (Terminus)
    9. CQRS
    10. Prisma
    11. Serve static
    12. Commander
    13. Async local storage
  7. WebSockets
    1. Gateways
    2. Exception filters
    3. Pipes
    4. Guards
    5. Interceptors
    6. Adapters
  8. Microservices
    1. Overview
    2. Redis
    3. MQTT
    4. NATS
    5. RabbitMQ
    6. Kafka
    7. gRPC
    8. Custom transporters
    9. Exception filters
    10. Pipes
    11. Pre-request hooks
    12. Guards
    13. Interceptors
  9. GraphQL
    1. Quick start
    2. Resolvers
    3. Mutations
    4. Subscriptions
    5. Scalars
    6. Directives
    7. Interfaces
    8. Unions and enums
    9. Field middleware
    10. Mapped types
    11. Plugins
    12. Complexity
    13. Extensions
    14. CLI plugin
    15. Generating SDL
    16. Sharing models
    17. Other features
    18. Federation
  10. CLI & triển khai
    1. CLI overview
    2. Workspaces
    3. Libraries
    4. Usage
    5. Scripts
    6. Deployment
    7. Standalone apps
  11. FAQ
    1. Serverless
    2. HTTP adapter
    3. Keep-Alive connections
    4. Global path prefix
    5. Raw body
    6. Hybrid application
    7. HTTPS & multiple servers
    8. Common errors
  12. Phụ lục
    1. Bảng thuật ngữ
CLI & triển khai

CLI command reference (Tra cứu lệnh CLI)

Bản dịch từ docs.nestjs.com/cli/usages

nest new

Tạo một Nest project mới (chế độ standard).

$ nest new <name> [options]
$ nest n <name> [options]

Description (Mô tả)

Tạo và khởi tạo một Nest project mới. Hỏi bạn chọn module system (ESM hoặc CommonJS) và package manager.

Gợi ý Chọn ESM sẽ scaffold một project ưu tiên ESM, dùng Vitest để test; chọn CommonJS sẽ scaffold theo layout truyền thống, dùng Jest. Cả hai biến thể đều dùng oxlint để lint.

Ghi chú người dịch oxlint là linter viết bằng Rust, được quảng bá là nhanh hơn ESLint đáng kể vì không chạy trên Node runtime. Việc Nest chuyển sang dùng oxlint mặc định cho project mới không có nghĩa ESLint bị “khai tử” — bạn vẫn có thể tự cấu hình lại ESLint nếu team đã có sẵn rule-set riêng.

  • Tạo một thư mục với <name> đã cho
  • Điền vào thư mục đó các file cấu hình
  • Tạo các thư mục con cho mã nguồn (/src) và test end-to-end (/test)
  • Điền vào các thư mục con đó các file mặc định cho thành phần ứng dụng và test

Arguments (Tham số)

Argument Description (Mô tả)
<name> Tên của project mới

Options (Tùy chọn)

Option Description (Mô tả)
--directory [directory] Chỉ định thư mục đích.
--dry-run Báo cáo các thay đổi sẽ được thực hiện, nhưng không thay đổi hệ thống file.
Alias: -d
--skip-git Bỏ qua việc khởi tạo git repository.
Alias: -g
--skip-install Bỏ qua việc cài đặt package.
Alias: -s
--skip-tests Không sinh file test cho project mới.
Alias: -t
--package-manager [package-manager] Chỉ định package manager. Dùng npm, yarn, pnpm, hoặc bun. Package manager phải được cài đặt global.
Alias: -p
--language [language] Chỉ định ngôn ngữ lập trình (TS hoặc JS).
Alias: -l
--collection [collectionName] Chỉ định collection schematics. Dùng tên package của npm package đã cài đặt chứa schematic.
Alias: -c
--strict Khởi động project với các cờ compiler TypeScript sau được bật: strictNullChecks, noImplicitAny, strictBindCallApply, forceConsistentCasingInFileNames, noFallthroughCasesInSwitch
--format Định dạng file được sinh ra bằng Prettier.
--observe / --no-observe Tự động cấu hình observability với @nestjs/observe, hoặc bỏ qua hoàn toàn câu hỏi này.

nest generate

Sinh và/hoặc chỉnh sửa file dựa trên một schematic

$ nest generate <schematic> <name> [options]
$ nest g <schematic> <name> [options]

Arguments (Tham số)

Argument Description (Mô tả)
<schematic> schematic hoặc collection:schematic cần sinh. Xem bảng bên dưới để biết các schematic có sẵn.
<name> Tên của component được sinh ra.

Schematics

Name Alias Description (Mô tả)
app Sinh một application mới bên trong monorepo (chuyển sang monorepo nếu đang là cấu trúc standard).
library lib Sinh một library mới bên trong monorepo (chuyển sang monorepo nếu đang là cấu trúc standard).
class cl Sinh một class mới.
controller co Sinh khai báo controller.
decorator d Sinh một custom decorator. Kể từ v12, decorator được sinh ra dùng cú pháp Reflector.createDecorator() được khuyến nghị.
filter f Sinh khai báo filter.
gateway ga Sinh khai báo gateway.
guard gu Sinh khai báo guard.
interface itf Sinh một interface.
interceptor itc Sinh khai báo interceptor.
middleware mi Sinh khai báo middleware.
module mo Sinh khai báo module.
pipe pi Sinh khai báo pipe.
provider pr Sinh khai báo provider.
resolver r Sinh khai báo resolver.
resource res Sinh một CRUD resource mới. Xem CRUD (resource) generator để biết thêm chi tiết. (Chỉ dành cho TS)
service s Sinh khai báo service.

Options (Tùy chọn)

Option Description (Mô tả)
--dry-run Báo cáo các thay đổi sẽ được thực hiện, nhưng không thay đổi hệ thống file.
Alias: -d
--project [project] Project mà thành phần này sẽ được thêm vào.
Alias: -p
--flat Không sinh thư mục riêng cho thành phần.
--no-flat Sinh thư mục riêng cho thành phần.
--collection [collectionName] Chỉ định collection schematics. Dùng tên package của npm package đã cài đặt chứa schematic.
Alias: -c
--spec Bắt buộc sinh file spec (mặc định)
--no-spec Tắt sinh file spec
--spec-file-suffix [suffix] Dùng hậu tố (suffix) tùy chỉnh cho file spec.
--skip-import Bỏ qua việc import thành phần được sinh ra vào module gần nhất.
--format Định dạng file được sinh ra bằng Prettier.

nest build

Compile một application hoặc workspace thành một thư mục output.

Ngoài ra, lệnh build còn chịu trách nhiệm:

  • ánh xạ đường dẫn (nếu dùng path alias) thông qua tsconfig-paths
  • gắn thêm decorator OpenAPI cho DTO (nếu CLI plugin @nestjs/swagger được bật)
  • gắn thêm decorator GraphQL cho DTO (nếu CLI plugin @nestjs/graphql được bật)
$ nest build <name> [options]

Arguments (Tham số)

Argument Description (Mô tả)
<name> Tên của project cần build.

Options (Tùy chọn)

Option Description (Mô tả)
--path [path] Đường dẫn đến file tsconfig.
Alias -p
--config [path] Đường dẫn đến file cấu hình nest-cli.
Alias -c
--watch Chạy ở chế độ watch (live-reload).
Nếu bạn dùng tsc để compile, bạn có thể gõ rs để khởi động lại ứng dụng (khi tùy chọn manualRestart được đặt là true).
Alias -w
--builder [name] Chỉ định builder dùng để compile (tsc, swc, hoặc rspack).
Alias -b
--webpack Cờ cũ (deprecated) cho việc compile dựa trên webpack. Nên dùng --builder rspack hoặc một builder tường minh khác.
--webpackPath Đường dẫn cũ (deprecated) đến file cấu hình webpack. Nên dùng cấu hình được hỗ trợ bởi builder bạn đã chọn.
--rspackPath [path] Đường dẫn đến file cấu hình Rspack.
--tsc Ép buộc dùng tsc để compile.
--watchAssets Theo dõi (watch) các file không phải TS (asset như .graphql v.v.). Xem Assets để biết thêm chi tiết.
--type-check Bật type checking (khi dùng SWC).
--no-type-check Tắt type checking (khi dùng SWC).
--emit-declarations Xuất file khai báo (.d.ts) khi dùng builder SWC.
--all Build tất cả project trong monorepo.
--parallel [concurrency] Build các project song song (dùng cùng với --all). Truyền một số nguyên dương để giới hạn số lượng đồng thời, hoặc bỏ trống để không giới hạn.
--silent Ẩn bớt các log biên dịch mang tính thông tin.
--preserveWatchOutput Giữ lại output console cũ ở chế độ watch thay vì xóa màn hình. (Chỉ áp dụng cho chế độ watch của tsc)

nest start

Compile và chạy một application (hoặc project mặc định trong một workspace).

$ nest start <name> [options]

Arguments (Tham số)

Argument Description (Mô tả)
<name> Tên của project cần chạy.

Options (Tùy chọn)

Option Description (Mô tả)
--path [path] Đường dẫn đến file tsconfig.
Alias -p
--config [path] Đường dẫn đến file cấu hình nest-cli.
Alias -c
--watch Chạy ở chế độ watch (live-reload)
Alias -w
--builder [name] Chỉ định builder dùng để compile (tsc, swc, hoặc rspack).
Alias -b
--preserveWatchOutput Giữ lại output console cũ ở chế độ watch thay vì xóa màn hình. (Chỉ áp dụng cho chế độ watch của tsc)
--watchAssets Chạy ở chế độ watch (live-reload), theo dõi luôn các file không phải TS (asset). Xem Assets để biết thêm chi tiết.
--debug [hostport] Chạy ở chế độ debug (kèm cờ –inspect)
Alias -d
--webpack Cờ cũ (deprecated) cho việc compile dựa trên webpack. Nên dùng --builder rspack hoặc một builder tường minh khác.
--webpackPath Đường dẫn cũ (deprecated) đến file cấu hình webpack. Nên dùng cấu hình được hỗ trợ bởi builder bạn đã chọn.
--rspackPath [path] Đường dẫn đến file cấu hình Rspack.
--tsc Ép buộc dùng tsc để compile.
--type-check Bật type checking (khi dùng SWC).
--no-type-check Tắt type checking (khi dùng SWC).
--emit-declarations Xuất file khai báo (.d.ts) khi dùng builder SWC.
--silent Ẩn bớt các log biên dịch mang tính thông tin.
--exec [binary] Binary dùng để chạy (mặc định: node).
Alias -e
--no-shell Không spawn child process bên trong một shell (xem tài liệu phương thức child_process.spawn() của node).
--env-file Nạp biến môi trường từ một file tương ứng với thư mục hiện tại, giúp chúng khả dụng cho ứng dụng thông qua process.env.
-- [key=value] Tham số dòng lệnh có thể được tham chiếu thông qua process.argv.

nest add

Import một library đã được đóng gói dưới dạng nest library, chạy schematic cài đặt của nó.

$ nest add <name> [options]

Arguments (Tham số)

Argument Description (Mô tả)
<name> Tên của library cần import.

Options (Tùy chọn)

Option Description (Mô tả)
--dry-run Báo cáo các thay đổi sẽ được thực hiện, nhưng không thay đổi hệ thống file.
Alias: -d
--skip-install Bỏ qua việc cài đặt package.
Alias: -s
--project [project] Project mà library sẽ được thêm vào.
Alias: -p

nest upgrade

Nâng cấp một project hiện có lên phiên bản NestJS major mới nhất.

$ nest upgrade [options]
$ nest update [options]

Description (Mô tả)

Chạy từ thư mục gốc của một project NestJS v11, nest upgrade cập nhật dependency của bạn lên v12 và tự động áp dụng phần cơ học (mechanical) của quá trình migration cho bạn:

  • Nâng mọi package @nestjs/* được nhận diện lên phiên bản major tương thích v12 (@nestjs/graphql, @nestjs/apollo, và @nestjs/mercurius được nâng lên v14), và báo cáo bất kỳ package @nestjs/* nào khác mà nó không nhận diện được để bạn tự xem xét
  • Di chuyển nest-cli.json ra khỏi các tùy chọn webpack / webpackConfigPath đã lỗi thời, chuyển sang dùng --builder rspack, đồng thời cập nhật các script tương ứng trong package.json
  • Đổi tên tùy chọn playground của GraphQL thành graphiql, chuyển subscription từ subscriptions-transport-ws sang graphql-ws, và thay các package tương ứng
  • Thay thế package nats cũ bằng @nats-io/transport-node / @nats-io/nats-core và viết lại các import nats
  • Chuyển các cấu hình riêng cho thư viện của @nestjs/config vào bên dưới validationOptions.libraryOptions, và nâng Joi lên v18 (bản phát hành đầu tiên triển khai Standard Schema)
  • Nâng Jest (cùng @types/jest / ts-jest) nếu có, và cảnh báo khi phiên bản Node.js của bạn quá cũ để require() các package v12 chỉ hỗ trợ ESM
  • Tùy chọn cài đặt và cấu hình @nestjs/observe - lệnh sẽ hỏi bạn, trừ khi bạn truyền --observe hoặc --no-observe
  • Quét mã nguồn của bạn và in ra các ghi chú về những hành vi đã thay đổi nhưng không thể tự động migrate được, chẳng hạn như thứ tự lifecycle hook, chữ ký (signature) pipe đã được tinh chỉnh lại, và các tham số logging có cấu trúc

Lệnh này kết thúc bằng việc cài đặt các dependency đã cập nhật (trừ khi --skip-install được truyền vào) và in ra một báo cáo về mọi thứ nó đã thay đổi, cảnh báo, và để lại cho bạn tự xử lý.

Cảnh báo nest upgrade chỉ nâng cấp dependency @nestjs/cli cục bộ. Hãy tự cập nhật CLI đã cài global bằng npm i -g @nestjs/cli@latest - và làm việc này trước khi chạy upgrade, vì bản thân lệnh này được đóng gói cùng với CLI.

Gợi ý Schematic này cố tình không migrate project của bạn sang ESM, Vitest, hay oxlint. Đó là các giá trị mặc định cho project v12 mới được tạo, nhưng các project hiện có có thể tự áp dụng chúng theo lịch trình riêng. Xem Migration guide để có bức tranh đầy đủ.

Ghi chú người dịch Nếu bạn từng dùng npm-check-updates hoặc tự tay sửa package.json rồi chạy npm install để nâng version, hãy để ý nest upgrade làm nhiều hơn thế: nó còn sửa cả mã nguồn (import, cấu hình nest-cli.json…) - giống một codemod hơn là một lệnh bump version thuần túy. Vì vậy nên commit code sạch trước khi chạy, và luôn review diff sau khi upgrade thay vì tin tưởng tuyệt đối.

Options (Tùy chọn)

Option Description (Mô tả)
--dry-run Báo cáo các thay đổi sẽ được thực hiện, nhưng không thay đổi hệ thống file.
Alias: -d
--skip-install Bỏ qua việc cài đặt package.
Alias: -s
--observe / --no-observe Cài đặt @nestjs/observe, hoặc bỏ qua hoàn toàn bước cài đặt này. Bỏ trống cả hai để được hỏi.
--tag [tag] Dùng một npm dist-tag (ví dụ next) thay vì các khoảng version mặc định.
Alias: -t
--collection [collectionName] Chỉ định collection schematics. Dùng tên package của npm package đã cài đặt chứa schematic.
Alias: -c

nest deploy

Deploy ứng dụng của bạn lên cloud, được cung cấp sức mạnh bởi Mau.

$ nest deploy [mau-options]

Description (Mô tả)

nest deploy là một lớp bọc mỏng quanh Mau CLI. Nó định vị binary Mau và chuyển tiếp mọi tham số bạn truyền thẳng đến mau deploy, vì vậy bất kỳ tùy chọn nào Mau hỗ trợ đều dùng được ở đây, không thay đổi.

Nếu Mau chưa được cài đặt trong project của bạn, lệnh sẽ đề nghị thêm @nestjs/mau như một dev dependency rồi tiếp tục. Trong môi trường không tương tác (ví dụ CI), lệnh sẽ thất bại thay vì hỏi, vì vậy hãy tự cài đặt trước:

$ npm install --save-dev @nestjs/mau

Vì Mau chiếm quyền điều khiển terminal ngay khi khởi động, output và mọi prompt nó hiển thị sẽ được chuyển tiếp trực tiếp đến bạn. Xem chương Deployment để biết Mau làm gì và cách cấu hình nó.

nest info

Hiển thị thông tin về các package nest đã cài đặt và các thông tin hệ thống hữu ích khác. Ví dụ:

$ nest info
 _   _             _      ___  _____  _____  _     _____
| \ | |           | |    |_  |/  ___|/  __ \| |   |_   _|
|  \| |  ___  ___ | |_     | |\ `--. | /  \/| |     | |
| . ` | / _ \/ __|| __|    | | `--. \| |    | |     | |
| |\  ||  __/\__ \| |_ /\__/ //\__/ /| \__/\| |_____| |_
\_| \_/ \___||___/ \__|\____/ \____/  \____/\_____/\___/

[System Information]
OS Version : macOS High Sierra
NodeJS Version : v20.18.0
[Nest Information]
microservices version : 10.0.0
websockets version : 10.0.0
testing version : 10.0.0
common version : 10.0.0
core version : 10.0.0

Nội dung gốc: NestJS Documentation © Kamil Myśliwiec, giấy phép MIT. Bản dịch và ghi chú: Lê Văn Dũng.