Toidicode.com

Toidicode.com

BASIC TO ADVANCE

Bài 14: Cấu hình với ConfigModule trong NestJS

Tiếp tục với series, ở bài trước TaskFlow API vẫn đọc key thẳng từ process.env, còn timeout 5000 thì viết cứng trong main.ts. Bài này mình sẽ giới thiệu với mọi người về cấu hình với ConfigModule trong NestJS để gom toàn bộ cấu hình về một chỗ và kiểm tra nó ngay khi khởi động.

1. Vì sao cần ConfigModule?

Mỗi môi trường (local, production) cần cấu hình khác nhau: port, key, thông tin database... Cách làm phổ biến là để cấu hình trong biến môi trường, còn ở local thì ghi chúng vào file .env cho tiện.

Package @nestjs/config (dùng dotenv bên dưới) đọc file .env, cung cấp ConfigService để inject vào bất kỳ đâu, kiểm tra (validate) biến môi trường và chia cấu hình theo nhóm. Các bạn cài đặt:

npm install @nestjs/config

2. File .env và ConfigModule.forRoot().

Các bạn tạo file .env ở thư mục gốc project, dùng lại key đã tạo ở Bài 12:

- .env

PORT=3000
API_KEY=<key đã tạo ở Bài 12>
REQUEST_TIMEOUT=5000

Chú ý: File .env chứa key thật nên không được commit, lỡ đẩy lên Git thì ai xem được repo cũng có key (xoá commit sau cũng không mất khỏi lịch sử). Project tạo bằng nest new đã có sẵn dòng .env trong .gitignore, các bạn kiểm tra lại và thêm vào nếu chưa có. Thay vào đó mình commit file .env.example cùng các biến nhưng để trống giá trị bí mật (API_KEY=), người khác clone về chỉ cần copy thành .env rồi điền.

Tiếp theo import ConfigModule vào AppModule:

- src/app.module.ts (đoạn trích)

import { ConfigModule } from '@nestjs/config';

@Module({
    imports: [
        ConfigModule.forRoot({ isGlobal: true }),
        ProjectsModule,
        TasksModule,
    ],
    // ...
})

Trong đó:

  • forRoot(): đọc file .env ở thư mục chạy lệnh (thư mục gốc project), gộp với các biến có sẵn trong process.env và đăng ký ConfigService.
  • isGlobal: true: biến nó thành global module (Bài 4), các feature module dùng ConfigService mà không cần import lại.

Lưu ý: Biến đã có sẵn trong môi trường được ưu tiên hơn .env, nên chạy API_KEY=khac npm run start:dev như Bài 12 thì key là khac. Production thường đặt biến môi trường thật và không có file .env.

3. Đọc cấu hình bằng ConfigService.

ConfigService là provider nên các bạn inject qua constructor như service khác. Sửa ApiKeyGuard đọc key qua nó:

- src/common/guards/api-key.guard.ts (đoạn trích, import ConfigService từ @nestjs/config)

constructor(
    private readonly reflector: Reflector,
    private readonly configService: ConfigService,
) {}

// trong canActivate(), thay cho process.env.API_KEY
const expected = this.configService.get<string>('API_KEY');

main.ts nằm ngoài mọi module nên lấy ConfigService bằng app.get():

- src/main.ts (đoạn trích, thay hai dòng cuối của bootstrap())

import { ConfigService } from '@nestjs/config';

// ...
    const config = app.get(ConfigService);
    app.useGlobalInterceptors(
        new TimeoutInterceptor(config.get<number>('REQUEST_TIMEOUT', 5000)),
    );
    await app.listen(config.get<number>('PORT', 3000));

Tham số thứ hai của get() là giá trị mặc định khi biến không tồn tại; cần bắt buộc thì dùng getOrThrow(). Chạy thử (K chứa header key như Bài 13):

curl http://localhost:3000/api/v1/projects/1 -H "$K"
# {"statusCode":500,"errorCode":"INTERNAL_SERVER_ERROR","message":"Internal server error","path":"/api/v1/projects/1","timestamp":"2026-11-15T07:16:22.264Z"}

# Terminal chạy ứng dụng:
# TypeError: No timeout provided.
#     at timeout (.../rxjs/dist/cjs/internal/operators/timeout.js:23:15)

Lỗi vì get<number>() chỉ là gợi ý kiểu cho TypeScript: giá trị đọc từ .env luôn là chuỗi '5000', và timeout('5000') của RxJS báo lỗi. Phần sau sẽ sửa chuyện này.

4. Validate biến môi trường.

Thiếu hay sai biến môi trường thì ứng dụng nên dừng ngay lúc khởi động thay vì lỗi khi có request. Option validationSchema nhận schema theo Standard Schema (Bài 8), mình dùng lại Zod đã cài:

- src/config/env.validation.ts

import { z } from 'zod';

export const envSchema = z.object({
    PORT: z.coerce.number().int().min(1).max(65535).default(3000),
    API_KEY: z.string().min(32, 'API_KEY phải dài ít nhất 32 ký tự'),
    REQUEST_TIMEOUT: z.coerce.number().int().positive().default(5000),
});

- src/app.module.ts (đoạn trích)

import { envSchema } from './config/env.validation.js';

// ...
        ConfigModule.forRoot({
            isGlobal: true,
            validationSchema: envSchema,
        }),

Trong đó:

  • z.coerce.number(): đổi chuỗi thành số. ConfigService trả về giá trị sau khi schema xử lý, nên REQUEST_TIMEOUT giờ là số 5000 và request ở phần 3 trả về {"data":{"id":1,...}} bình thường.
  • default(): giá trị khi không khai báo biến. API_KEY không có default nên là bắt buộc, và phải đủ dài.
  • Các biến không khai báo trong schema (PATH, HOME...) không gây lỗi.
API_KEY=abc PORT=abc npm run start:dev
# [Nest] 1023  - 11/15/2026, 7:20:07 AM   ERROR [ExceptionHandler] Error: Config validation error: PORT: Invalid input: expected number, received NaN
# API_KEY: API_KEY phải dài ít nhất 32 ký tự

Ứng dụng không khởi động và liệt kê tất cả biến sai cùng lúc. Xoá API_KEY khỏi .env thì nhận API_KEY: Invalid input: expected string, received undefined.

Lưu ý: Joi vẫn dùng được với validationSchema nhưng cần Joi v18 trở lên (bản có Standard Schema). Ngoài ra có option validate nhận một hàm tự viết, VD dùng class-validator.

5. Namespace config với registerAs.

Gọi get('API_KEY') rải rác khắp nơi thì dễ gõ sai tên và không có kiểu. registerAs() gom cấu hình thành từng nhóm (namespace) có kiểu rõ ràng:

- src/config/app.config.ts

import { registerAs } from '@nestjs/config';

// Namespace 'app': process.env đã được validate (và có giá trị mặc định) ở envSchema
export default registerAs('app', () => ({
    port: Number(process.env.PORT),
    requestTimeout: Number(process.env.REQUEST_TIMEOUT),
}));

- src/config/auth.config.ts

import { registerAs } from '@nestjs/config';

export default registerAs('auth', () => ({
    apiKey: process.env.API_KEY ?? '',
}));

Hàm factory chạy sau bước validate, lúc này process.env đã có cả giá trị mặc định nhưng vẫn là chuỗi, nên mình đổi sang số bằng Number(). Nạp hai file bằng option load:

- src/app.module.ts (đoạn trích)

import appConfig from './config/app.config.js';
import authConfig from './config/auth.config.js';

// ...
        ConfigModule.forRoot({
            isGlobal: true,
            validationSchema: envSchema,
            load: [appConfig, authConfig],
        }),

Giờ configService.get('app.port') đã chạy được, nhưng tốt hơn là inject thẳng cả namespace bằng token KEY (Bài 6), ConfigType lấy kiểu từ giá trị factory trả về:

- src/common/guards/api-key.guard.ts (đoạn trích, thêm Inject vào import từ @nestjs/common, bỏ import ConfigService)

import type { ConfigType } from '@nestjs/config';
import authConfig from '../../config/auth.config.js';

// ...
    constructor(
        private readonly reflector: Reflector,
        @Inject(authConfig.KEY)
        private readonly auth: ConfigType<typeof authConfig>,
    ) {}

    // trong canActivate()
    const expected = this.auth.apiKey;

- src/main.ts (đoạn trích, thay đoạn ở phần 3)

import type { ConfigType } from '@nestjs/config';
import appConfig from './config/app.config.js';

// ...
    const config = app.get<ConfigType<typeof appConfig>>(appConfig.KEY);
    app.useGlobalInterceptors(new TimeoutInterceptor(config.requestTimeout));
    await app.listen(config.port);

Gõ config. là editor gợi ý port, requestTimeout với kiểu number. Chạy PORT=4000 npm run start:dev thì API chạy ở cổng 4000. Bài 15 sẽ thêm cấu hình database, Bài 20 thêm JWT theo đúng cách này.

Lưu ý: Test e2e cũng nạp AppModule nên cần .env (hoặc biến API_KEY), thiếu thì npm run test:e2e báo Config validation error.

6. Lời kết.

Như vậy mình đã giới thiệu với mọi người về cấu hình với ConfigModule trong NestJS: file .env và không commit nó, ConfigService, validate biến môi trường bằng Zod và namespace config với registerAs(). Dữ liệu TaskFlow API vẫn nằm trong bộ nhớ, khởi động lại là mất, nên bài sau mình sẽ giới thiệu về kết nối database với Prisma trong NestJS, chạy PostgreSQL bằng Docker và thêm cấu hình database theo cách vừa học.

Đăng ký nhận tin.

Chúng tôi chỉ gửi tối đa 2 lần trên 1 tháng. Tuyên bố không spam mail!

Vũ Thanh Tài

About author
The best way to learn is to share
Xem tất cả bài đăng

0 Comments

Bài viết chưa có ai bình luận, hãy là người đầu tiên đi bạn!

Bình luận

Captcha