@tndhuy/create-app 1.0.0

package/templates/mongo/Dockerfile

@@ -0,0 +1,64 @@
+# =========================
+# 1) Dependencies
+# =========================
+FROM node:22-alpine AS deps
+
+RUN apk upgrade --no-cache \
+  && addgroup -g 1001 -S appgroup \
+  && adduser -S appuser -u 1001 -G appgroup
+
+WORKDIR /app
+RUN chown appuser:appgroup /app
+
+COPY --chown=appuser:appgroup package*.json ./
+COPY --chown=appuser:appgroup prisma ./prisma/
+COPY --chown=appuser:appgroup prisma.config.ts ./
+
+USER appuser
+
+RUN npm ci --fetch-timeout=600000 --fetch-retries=5
+
+
+# =========================
+# 2) Builder
+# =========================
+FROM deps AS builder
+
+COPY --chown=appuser:appgroup . .
+
+RUN npx prisma generate && npm run build
+
+
+# =========================
+# 3) Runner (Production)
+# =========================
+FROM node:22-alpine AS runner
+
+RUN apk upgrade --no-cache \
+  && apk add --no-cache curl \
+  && addgroup -g 1001 -S appgroup \
+  && adduser -S appuser -u 1001 -G appgroup
+
+WORKDIR /app
+
+COPY --from=builder --chown=appuser:appgroup /app/package*.json ./
+COPY --from=builder --chown=appuser:appgroup /app/prisma ./prisma
+COPY --from=builder --chown=appuser:appgroup /app/prisma.config.ts ./prisma.config.ts
+
+RUN npm ci --omit=dev --fetch-timeout=600000 --fetch-retries=5 && npm cache clean --force
+
+COPY --from=builder --chown=appuser:appgroup /app/dist ./dist
+
+RUN mkdir -p logs && chown appuser:appgroup logs
+
+ENV NODE_ENV=production \
+    PORT=3000
+
+USER appuser
+
+EXPOSE 3000
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+  CMD curl -f http://localhost:3000/health || exit 1
+
+CMD ["node", "dist/src/main"]

package/templates/mongo/docker-compose.yml

@@ -0,0 +1,35 @@
+services:
+  mongodb:
+    image: mongo:latest
+    container_name: nestjs-template-mongodb
+    restart: unless-stopped
+    ports:
+      - "27017:27017"
+    environment:
+      MONGO_INITDB_DATABASE: template_db
+    volumes:
+      - mongodb_data:/data/db
+    healthcheck:
+      test: ["CMD", "mongosh", "--quiet", "--eval", "db.adminCommand('ping').ok"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+
+  redis:
+    image: redis:latest
+    container_name: nestjs-template-redis
+    restart: unless-stopped
+    ports:
+      - "6379:6379"
+    command: ["redis-server", "--appendonly", "yes"]
+    volumes:
+      - redis_data:/data
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+
+volumes:
+  mongodb_data:
+  redis_data:

package/templates/mongo/eslint.config.mjs

@@ -0,0 +1,35 @@
+// @ts-check
+import eslint from '@eslint/js';
+import eslintPluginPrettierRecommended from 'eslint-plugin-prettier/recommended';
+import globals from 'globals';
+import tseslint from 'typescript-eslint';
+
+export default tseslint.config(
+  {
+    ignores: ['eslint.config.mjs'],
+  },
+  eslint.configs.recommended,
+  ...tseslint.configs.recommendedTypeChecked,
+  eslintPluginPrettierRecommended,
+  {
+    languageOptions: {
+      globals: {
+        ...globals.node,
+        ...globals.jest,
+      },
+      sourceType: 'commonjs',
+      parserOptions: {
+        projectService: true,
+        tsconfigRootDir: import.meta.dirname,
+      },
+    },
+  },
+  {
+    rules: {
+      '@typescript-eslint/no-explicit-any': 'off',
+      '@typescript-eslint/no-floating-promises': 'warn',
+      '@typescript-eslint/no-unsafe-argument': 'warn',
+      "prettier/prettier": ["error", { endOfLine: "auto" }],
+    },
+  },
+);

package/templates/mongo/nest-cli.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json.schemastore.org/nest-cli",
+  "collection": "@nestjs/schematics",
+  "sourceRoot": "src",
+  "compilerOptions": {
+    "deleteOutDir": true
+  }
+}

package/templates/mongo/package.json

@@ -0,0 +1,105 @@
+{
+  "name": "nestjs-backend-template",
+  "version": "0.0.1",
+  "description": "",
+  "author": "",
+  "private": true,
+  "license": "UNLICENSED",
+  "scripts": {
+    "build": "nest build",
+    "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"",
+    "start": "nest start",
+    "start:dev": "nest start --watch",
+    "start:debug": "nest start --debug --watch",
+    "start:prod": "node dist/src/main",
+    "db:generate": "prisma generate",
+    "db:sync": "prisma db push",
+    "db:sync:force": "prisma db push --accept-data-loss",
+    "db:push": "prisma db push",
+    "db:pull": "prisma db pull",
+    "db:validate": "prisma validate",
+    "db:format": "prisma format",
+    "db:studio": "prisma studio",
+    "lint": "eslint \"{src,apps,libs,test}/**/*.ts\" --fix",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:cov": "jest --coverage",
+    "test:debug": "node --inspect-brk -r tsconfig-paths/register -r ts-node/register node_modules/.bin/jest --runInBand",
+    "test:e2e": "jest --config ./test/jest-e2e.json"
+  },
+  "dependencies": {
+    "@nestjs/common": "^11.0.1",
+    "@nestjs/config": "^4.0.3",
+    "@nestjs/core": "^11.0.1",
+    "@nestjs/cqrs": "^11.0.3",
+    "@nestjs/mongoose": "^11.0.4",
+    "@nestjs/platform-express": "^11.0.1",
+    "@nestjs/swagger": "^11.2.6",
+    "@nestjs/terminus": "^11.1.1",
+    "@nestjs/throttler": "^6.5.0",
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/auto-instrumentations-node": "^0.72.0",
+    "@opentelemetry/exporter-prometheus": "^0.214.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.214.0",
+    "@opentelemetry/resources": "^2.6.1",
+    "@opentelemetry/sdk-node": "^0.214.0",
+    "@opentelemetry/sdk-trace-base": "^2.6.1",
+    "@prisma/client": "^7.5.0",
+    "@scalar/nestjs-api-reference": "^1.1.5",
+    "class-transformer": "^0.5.1",
+    "class-validator": "^0.15.1",
+    "cockatiel": "^3.2.1",
+    "express-basic-auth": "^1.2.1",
+    "ioredis": "^5.10.1",
+    "mongoose": "^9.4.1",
+    "nestjs-pino": "^4.6.1",
+    "pino-http": "^11.0.0",
+    "pino-pretty": "^13.1.3",
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.1"
+  },
+  "devDependencies": {
+    "@eslint/eslintrc": "^3.2.0",
+    "@eslint/js": "^9.18.0",
+    "@nestjs/cli": "^11.0.0",
+    "@nestjs/schematics": "^11.0.0",
+    "@nestjs/testing": "^11.0.1",
+    "@types/express": "^5.0.0",
+    "@types/ioredis": "^5.0.0",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^22.10.7",
+    "@types/supertest": "^6.0.2",
+    "eslint": "^9.18.0",
+    "eslint-config-prettier": "^10.0.1",
+    "eslint-plugin-prettier": "^5.2.2",
+    "globals": "^16.0.0",
+    "jest": "^30.0.0",
+    "prettier": "^3.4.2",
+    "prisma": "^7.5.0",
+    "source-map-support": "^0.5.21",
+    "supertest": "^7.0.0",
+    "ts-jest": "^29.2.5",
+    "ts-loader": "^9.5.2",
+    "ts-node": "^10.9.2",
+    "tsconfig-paths": "^4.2.0",
+    "typescript": "^5.7.3",
+    "typescript-eslint": "^8.20.0"
+  },
+  "jest": {
+    "moduleFileExtensions": [
+      "js",
+      "json",
+      "ts"
+    ],
+    "rootDir": "src",
+    "testRegex": ".*\\.spec\\.ts$",
+    "transform": {
+      "^.+\\.(t|j)s$": "ts-jest"
+    },
+    "collectCoverageFrom": [
+      "**/*.(t|j)s"
+    ],
+    "coverageDirectory": "../coverage",
+    "testEnvironment": "node"
+  }
+}

package/templates/mongo/src/app.module.ts

@@ -0,0 +1,59 @@
+import { MiddlewareConsumer, Module, NestModule } from '@nestjs/common';
+import { APP_GUARD } from '@nestjs/core';
+import { ThrottlerModule, ThrottlerGuard } from '@nestjs/throttler';
+import { LoggerModule } from 'nestjs-pino';
+import { AppConfigModule } from './infrastructure/config/config.module';
+import { MongoDBModule } from './infrastructure/database/mongodb.module';
+import { CacheModule } from './infrastructure/cache/redis.module';
+import { HealthModule } from './infrastructure/health/health.module';
+import { ExampleModule } from './modules/example/example.module';
+import { CorrelationIdMiddleware } from './common/middleware/correlation-id.middleware';
+
+@Module({
+  imports: [
+    AppConfigModule,
+    MongoDBModule,
+    CacheModule,
+    HealthModule,
+    ExampleModule,
+    LoggerModule.forRoot({
+      pinoHttp: {
+        level: process.env.NODE_ENV !== 'production' ? 'debug' : 'info',
+        genReqId: (req) => req.headers['x-correlation-id'] as string,
+        transport:
+          process.env.NODE_ENV !== 'production'
+            ? {
+                target: 'pino-pretty',
+                options: {
+                  colorize: true,
+                  translateTime: 'SYS:yyyy-mm-dd HH:MM:ss',
+                  ignore: 'pid,hostname',
+                },
+              }
+            : undefined,
+        serializers: {
+          req: (req: { method: string; url: string }) => ({
+            method: req.method,
+            url: req.url,
+          }),
+          res: (res: { statusCode: number }) => ({
+            statusCode: res.statusCode,
+          }),
+        },
+      },
+    }),
+    ThrottlerModule.forRoot([
+      {
+        ttl: parseInt(process.env.THROTTLE_TTL ?? '60', 10) * 1000,
+        limit: parseInt(process.env.THROTTLE_LIMIT ?? '100', 10),
+      },
+    ]),
+  ],
+  controllers: [],
+  providers: [{ provide: APP_GUARD, useClass: ThrottlerGuard }],
+})
+export class AppModule implements NestModule {
+  configure(consumer: MiddlewareConsumer) {
+    consumer.apply(CorrelationIdMiddleware).forRoutes('*');
+  }
+}

package/templates/mongo/src/common/decorators/public-api.decorator.ts

@@ -0,0 +1,9 @@
+import { SetMetadata } from '@nestjs/common';
+
+export const PUBLIC_API_KEY = 'public_api';
+/**
+ * Decorator to mark an endpoint as Public API.
+ * This will trigger the TransformInterceptor to wrap the response in { success: true, data: T }.
+ * Without this decorator, the response remains raw.
+ */
+export const PublicApi = () => SetMetadata(PUBLIC_API_KEY, true);

package/templates/mongo/src/common/decorators/raw-response.decorator.ts

@@ -0,0 +1,4 @@
+import { SetMetadata } from '@nestjs/common';
+import { RAW_RESPONSE_KEY } from '../interceptors/transform.interceptor';
+
+export const RawResponse = () => SetMetadata(RAW_RESPONSE_KEY, true);

package/templates/mongo/src/common/filters/http-exception.filter.spec.ts

@@ -0,0 +1,95 @@
+import { HttpException } from '@nestjs/common';
+import { AppException } from '../../shared/exceptions/app.exception';
+import { ErrorCodes } from '../../shared/exceptions/error-codes';
+import { HttpExceptionFilter } from './http-exception.filter';
+
+function createMockHost(jsonMock: jest.Mock) {
+  const statusMock = jest.fn().mockReturnValue({ json: jsonMock });
+  const response = { status: statusMock };
+  const request = { method: 'GET', url: '/test' };
+  return {
+    switchToHttp: () => ({
+      getResponse: () => response,
+      getRequest: () => request,
+    }),
+  } as any;
+}
+
+describe('HttpExceptionFilter', () => {
+  let filter: HttpExceptionFilter;
+  let jsonMock: jest.Mock;
+
+  beforeEach(() => {
+    filter = new HttpExceptionFilter();
+    jsonMock = jest.fn();
+  });
+
+  it('should format AppException(NOT_FOUND) to correct error shape', () => {
+    const exception = new AppException({
+      code: ErrorCodes.NOT_FOUND,
+      message: 'Item not found',
+      statusCode: 404,
+    });
+    const host = createMockHost(jsonMock);
+
+    filter.catch(exception, host);
+
+    expect(jsonMock).toHaveBeenCalledWith({
+      success: false,
+      error: {
+        code: 'NOT_FOUND',
+        message: 'Item not found',
+        statusCode: 404,
+        details: null,
+      },
+    });
+  });
+
+  it('should include details array from AppException', () => {
+    const details = [{ field: 'email', constraints: { isEmail: 'must be email' } }];
+    const exception = new AppException({
+      code: ErrorCodes.VALIDATION_FAILED,
+      message: 'Validation failed',
+      statusCode: 400,
+      details,
+    });
+    const host = createMockHost(jsonMock);
+
+    filter.catch(exception, host);
+
+    expect(jsonMock).toHaveBeenCalledWith({
+      success: false,
+      error: {
+        code: 'VALIDATION_FAILED',
+        message: 'Validation failed',
+        statusCode: 400,
+        details,
+      },
+    });
+  });
+
+  it('should handle generic HttpException(403) with FORBIDDEN code', () => {
+    const exception = new HttpException('Forbidden', 403);
+    const host = createMockHost(jsonMock);
+
+    filter.catch(exception, host);
+
+    const call = jsonMock.mock.calls[0][0];
+    expect(call.success).toBe(false);
+    expect(call.error.statusCode).toBe(403);
+    expect(call.error.code).toBe('FORBIDDEN');
+    expect(call.error.details).toBeNull();
+  });
+
+  it('should handle generic HttpException(500) with INTERNAL_SERVER_ERROR code', () => {
+    const exception = new HttpException('Internal Server Error', 500);
+    const host = createMockHost(jsonMock);
+
+    filter.catch(exception, host);
+
+    const call = jsonMock.mock.calls[0][0];
+    expect(call.success).toBe(false);
+    expect(call.error.statusCode).toBe(500);
+    expect(call.error.code).toBe('INTERNAL_SERVER_ERROR');
+  });
+});

package/templates/mongo/src/common/filters/http-exception.filter.ts

@@ -0,0 +1,43 @@
+import {
+  ArgumentsHost,
+  Catch,
+  ExceptionFilter,
+  HttpException,
+  HttpStatus,
+} from '@nestjs/common';
+import { Request, Response } from 'express';
+import { LoggerService } from '../../shared/logger/logger.service';
+
+@Catch(HttpException)
+export class HttpExceptionFilter implements ExceptionFilter {
+  constructor(private readonly logger: LoggerService) {}
+
+  catch(exception: HttpException, host: ArgumentsHost): void {
+    const ctx = host.switchToHttp();
+    const response = ctx.getResponse<Response>();
+    const request = ctx.getRequest<Request>();
+
+    const statusCode = exception.getStatus();
+    const res = exception.getResponse() as any;
+    
+    const code = res.error || HttpStatus[statusCode] || 'INTERNAL_ERROR';
+    const message = res.message || exception.message;
+
+    this.logger.error(
+      `[${request.method}] ${request.url} - ${statusCode} ${code}: ${message}`,
+      exception.stack,
+    );
+
+    // Standardized Error Response
+    response.status(statusCode).json({
+      success: false,
+      error: {
+        code,
+        message,
+        statusCode,
+        timestamp: new Date().toISOString(),
+        path: request.url,
+      },
+    });
+  }
+}

package/templates/mongo/src/common/filters/rpc-exception.filter.ts

@@ -0,0 +1,18 @@
+// RPC Exception Filter — placeholder for microservice completeness.
+// Requires @nestjs/microservices to be installed.
+// When @nestjs/microservices is added, uncomment the implementation below.
+
+/*
+import { ArgumentsHost, Catch, ExceptionFilter } from '@nestjs/common';
+import { RpcException } from '@nestjs/microservices';
+import { throwError } from 'rxjs';
+
+@Catch(RpcException)
+export class RpcExceptionFilter implements ExceptionFilter {
+  catch(exception: RpcException, _host: ArgumentsHost) {
+    return throwError(() => exception.getError());
+  }
+}
+*/
+
+export {};

package/templates/mongo/src/common/index.ts

@@ -0,0 +1,5 @@
+export * from './filters/http-exception.filter';
+export * from './interceptors/transform.interceptor';
+export * from './interceptors/timeout.interceptor';
+export * from './decorators/raw-response.decorator';
+export * from './middleware/correlation-id.middleware';

package/templates/mongo/src/common/interceptors/timeout.interceptor.ts

@@ -0,0 +1,32 @@
+import { CallHandler, ExecutionContext, Injectable, NestInterceptor } from '@nestjs/common';
+import { Observable, throwError, TimeoutError } from 'rxjs';
+import { catchError, timeout } from 'rxjs/operators';
+import { AppException } from '../../shared/exceptions/app.exception';
+
+const DEFAULT_TIMEOUT_MS = 30000;
+
+@Injectable()
+export class TimeoutInterceptor implements NestInterceptor {
+  intercept(_context: ExecutionContext, next: CallHandler): Observable<unknown> {
+    const timeoutMs = process.env.REQUEST_TIMEOUT
+      ? parseInt(process.env.REQUEST_TIMEOUT, 10)
+      : DEFAULT_TIMEOUT_MS;
+
+    return next.handle().pipe(
+      timeout(timeoutMs),
+      catchError((err) => {
+        if (err instanceof TimeoutError) {
+          return throwError(
+            () =>
+              new AppException({
+                code: 'REQUEST_TIMEOUT',
+                message: 'Request timeout',
+                statusCode: 408,
+              }),
+          );
+        }
+        return throwError(() => err);
+      }),
+    );
+  }
+}

package/templates/mongo/src/common/interceptors/transform.interceptor.spec.ts

@@ -0,0 +1,52 @@
+import { Reflector } from '@nestjs/core';
+import { of } from 'rxjs';
+import { RAW_RESPONSE_KEY, TransformInterceptor } from './transform.interceptor';
+
+function createMockContext(isRaw: boolean) {
+  const reflector = new Reflector();
+  jest.spyOn(reflector, 'getAllAndOverride').mockReturnValue(isRaw);
+  const context = {
+    getHandler: () => jest.fn(),
+    getClass: () => jest.fn(),
+  } as any;
+  return { reflector, context };
+}
+
+describe('TransformInterceptor', () => {
+  it('should wrap controller return value in { success: true, data }', (done) => {
+    const { reflector, context } = createMockContext(false);
+    const interceptor = new TransformInterceptor(reflector);
+    const next = { handle: () => of({ id: '1', name: 'test' }) };
+
+    interceptor.intercept(context, next).subscribe((result) => {
+      expect(result).toEqual({ success: true, data: { id: '1', name: 'test' } });
+      done();
+    });
+  });
+
+  it('should NOT wrap when @RawResponse() is used', (done) => {
+    const { reflector, context } = createMockContext(true);
+    const interceptor = new TransformInterceptor(reflector);
+    const next = { handle: () => of({ status: 'ok' }) };
+
+    interceptor.intercept(context, next).subscribe((result) => {
+      expect(result).toEqual({ status: 'ok' });
+      done();
+    });
+  });
+
+  it('should wrap null return value in { success: true, data: null }', (done) => {
+    const { reflector, context } = createMockContext(false);
+    const interceptor = new TransformInterceptor(reflector);
+    const next = { handle: () => of(null) };
+
+    interceptor.intercept(context, next).subscribe((result) => {
+      expect(result).toEqual({ success: true, data: null });
+      done();
+    });
+  });
+
+  it('should use RAW_RESPONSE_KEY constant', () => {
+    expect(RAW_RESPONSE_KEY).toBe('raw_response');
+  });
+});

package/templates/mongo/src/common/interceptors/transform.interceptor.ts

@@ -0,0 +1,25 @@
+import { CallHandler, ExecutionContext, Injectable, NestInterceptor } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { Observable } from 'rxjs';
+import { map } from 'rxjs/operators';
+import { PUBLIC_API_KEY } from '../decorators/public-api.decorator';
+
+@Injectable()
+export class TransformInterceptor<T> implements NestInterceptor<T, unknown> {
+  constructor(private readonly reflector: Reflector) {}
+
+  intercept(context: ExecutionContext, next: CallHandler): Observable<unknown> {
+    const isPublic = this.reflector.getAllAndOverride<boolean>(PUBLIC_API_KEY, [
+      context.getHandler(),
+      context.getClass(),
+    ]);
+
+    // Internal first: If not explicitly marked as Public API, return RAW data
+    if (!isPublic) {
+      return next.handle();
+    }
+
+    // Public API: Wrap response in a standardized success object
+    return next.handle().pipe(map((data) => ({ success: true, data })));
+  }
+}

package/templates/mongo/src/common/middleware/correlation-id.middleware.spec.ts

@@ -0,0 +1,69 @@
+import { CORRELATION_ID_HEADER, CorrelationIdMiddleware } from './correlation-id.middleware';
+
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+function createMockReq(headers: Record<string, string> = {}): any {
+  return { headers: { ...headers } };
+}
+
+function createMockRes(): any {
+  const headers: Record<string, string> = {};
+  return {
+    setHeader: (name: string, value: string) => {
+      headers[name] = value;
+    },
+    _headers: headers,
+  };
+}
+
+describe('CorrelationIdMiddleware', () => {
+  let middleware: CorrelationIdMiddleware;
+
+  beforeEach(() => {
+    middleware = new CorrelationIdMiddleware();
+  });
+
+  it('should generate UUID v4 when X-Correlation-ID header is absent', () => {
+    const req = createMockReq();
+    const res = createMockRes();
+    const next = jest.fn();
+
+    middleware.use(req, res, next);
+
+    const correlationId = req.headers[CORRELATION_ID_HEADER.toLowerCase()];
+    expect(correlationId).toMatch(UUID_PATTERN);
+    expect(next).toHaveBeenCalled();
+  });
+
+  it('should preserve existing X-Correlation-ID header', () => {
+    const req = createMockReq({ 'x-correlation-id': 'abc-123' });
+    const res = createMockRes();
+    const next = jest.fn();
+
+    middleware.use(req, res, next);
+
+    expect(req.headers['x-correlation-id']).toBe('abc-123');
+    expect(res._headers[CORRELATION_ID_HEADER]).toBe('abc-123');
+  });
+
+  it('should always set X-Correlation-ID on the response header', () => {
+    const req = createMockReq();
+    const res = createMockRes();
+    const next = jest.fn();
+
+    middleware.use(req, res, next);
+
+    expect(res._headers[CORRELATION_ID_HEADER]).toBeDefined();
+    expect(res._headers[CORRELATION_ID_HEADER]).toMatch(UUID_PATTERN);
+  });
+
+  it('should call next()', () => {
+    const req = createMockReq();
+    const res = createMockRes();
+    const next = jest.fn();
+
+    middleware.use(req, res, next);
+
+    expect(next).toHaveBeenCalledTimes(1);
+  });
+});