docker-compose up -d

No native build steps (pod install, Android linking) apply - this is a pure Node.js project.

Project setup

1. Copy the source/ directory contents into the root of your project (or a subdirectory, adjusting paths accordingly).

2. Configure tsconfig.json. The existing file targets ES6 and outputs to dist/. Merge with your own or replace it:

{
  "compilerOptions": {
    "target": "ES6",
    "module": "commonjs",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": false,
    "esModuleInterop": true,
    "resolveJsonModule": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

3. Create a .env file in the project root. At minimum supply:

APP_NAME=MyApp
APP_URL=http://localhost:3000
APP_PORT=3000

DB_HOST=localhost
DB_PORT=27017
DB_NAME=myapp

SESSION_SECRET=your-session-secret
JWT_SECRET=your-jwt-secret

REDIS_HOST=127.0.0.1
REDIS_PORT=6379

LOG_DAYS=10
QUEUE_MONITOR_PORT=5500

4. Add scripts to your package.json:

{
  "scripts": {
    "build": "tsc",
    "start": "node dist/index.js",
    "dev": "nodemon"
  }
}

5. Start in development mode:

npm run dev

6. Build and run for production:

npm run build && npm start

Public API

App

import App from './src/providers/App';

App.clearConsole(): void
App.loadConfiguration(): void
App.loadQueue(): void
App.loadWorker(): void

App is the central bootstrap provider. Call App.loadConfiguration() to initialise dotenv and locals before any other provider. App.loadQueue() starts the Kue dashboard if enabled in .env. App.loadWorker() is scheduled with a delay after full boot (see src/index.ts).

NativeEvent

import NativeEvent from './src/exception/NativeEvent';

NativeEvent.process(): void
NativeEvent.cluster(cluster: any): void

NativeEvent attaches handlers to Node.js process and cluster lifecycle events (uncaught exceptions, worker exits, disconnects). Call NativeEvent.process() once in the master process before forking, and NativeEvent.cluster(cluster) after forking to handle worker restarts automatically.

IRequest / IResponse / INext

import { IRequest, IResponse, INext } from './src/interfaces/vendors';

Vendor-typed wrappers around Express's Request, Response, and NextFunction. Use these as parameter types in all controller and middleware functions to keep TypeScript strict across the codebase and allow attaching custom properties (e.g., req.user) without casting.

Working examples

Scenario - Bootstrap the server with clustering

This replicates the exact boot sequence from src/index.ts, adapted for your entry file.

import * as os from 'os';
import * as cluster from 'cluster';

import App from './src/providers/App';
import NativeEvent from './src/exception/NativeEvent';

if (cluster.isMaster) {
  NativeEvent.process();
  App.clearConsole();
  App.loadConfiguration();

  const CPUS: any = os.cpus();
  CPUS.forEach(() => cluster.fork());

  NativeEvent.cluster(cluster);
  App.loadQueue();

  setTimeout(() => App.loadWorker(), 1000 * 60);
} else {
  // Worker: boot Express, connect DB, mount routes
  App.loadConfiguration();
  // import and call your Express provider here
}

Scenario - Writing a typed controller using vendor interfaces

Use IRequest, IResponse, and INext to author a controller that is fully typed without casting.

import { IRequest, IResponse, INext } from './src/interfaces/vendors';

class HomeController {
  public static index(req: IRequest, res: IResponse, next: INext): void {
    try {
      return res.status(200).json({
        message: 'Welcome',
        user: req.user ?? null,
      });
    } catch (err) {
      return next(err);
    }
  }
}

export default HomeController;

Register it in src/routes/Api.ts or src/routes/Web.ts using the Express router.

Scenario - Attaching a custom middleware with vendor types

Demonstrate writing a middleware (equivalent to those in src/middlewares/) that uses the shared interface types.

import { IRequest, IResponse, INext } from './src/interfaces/vendors';

export function requestTimestamp(
  req: IRequest,
  res: IResponse,
  next: INext
): void {
  (req as any).timestamp = Date.now();
  console.log(`[${new Date().toISOString()}] ${req.method} ${req.url}`);
  return next();
}

Register this in src/middlewares/Kernel.ts alongside the existing middleware chain by importing and calling app.use(requestTimestamp).

File walkthrough

• src/index.ts - Application entry point; handles master/worker cluster split and boot sequence.
• src/providers/App.ts - Central app orchestrator: console clear, config load, queue/worker boot.
• src/providers/Express.ts - Creates and configures the Express application instance.
• src/providers/Database.ts - Mongoose connection setup using .env DB config.
• src/providers/Locals.ts - Binds dotenv values and app-wide locals to the Express app.
• src/providers/Passport.ts - Initialises Passport.js and mounts strategies.
• src/providers/Routes.ts - Mounts src/routes/Web.ts and src/routes/Api.ts on the app.
• src/providers/Queue.ts - Kue queue setup and job definitions.
• src/providers/Cache.ts - memory-cache wrapper for in-process caching.
• src/routes/Api.ts - API route definitions, JWT middleware applied.
• src/routes/Web.ts - Web route definitions, CSRF middleware applied.
• src/controllers/Home.ts - Web home page controller.
• src/controllers/Account.ts - Web account management controller.
• src/controllers/Auth/Login.ts - Web login controller (Passport local strategy).
• src/controllers/Auth/Logout.ts - Session destroy / logout controller.
• src/controllers/Auth/Register.ts - Web registration controller.
• src/controllers/Auth/Social.ts - OAuth social login controller.
• src/controllers/Api/Home.ts - API home endpoint controller.
• src/controllers/Api/Auth/Login.ts - API login, returns JWT.
• src/controllers/Api/Auth/Register.ts - API user registration.
• src/controllers/Api/Auth/RefreshToken.ts - API JWT refresh endpoint.
• src/exception/Handler.ts - Express error handler middleware (400/500 responses).
• src/exception/NativeEvent.ts - Node.js process and cluster event handlers.
• src/interfaces/vendors/IRequest.ts - Extended Express Request type.
• src/interfaces/vendors/IResponse.ts - Extended Express Response type.
• src/interfaces/vendors/INext.ts - Express NextFunction alias.
• src/interfaces/vendors/index.ts - Barrel export for all vendor interfaces.
• src/interfaces/models/user.ts - TypeScript interface for the User document.
• src/middlewares/Kernel.ts - Assembles and mounts all middleware in order.
• src/middlewares/CORS.ts - Configures cors package options.
• src/middlewares/CsrfToken.ts - Lusca CSRF token middleware.
• src/middlewares/Http.ts - Body parser and compression setup.
• src/middlewares/Log.ts - Winston-based request logging middleware.
• src/middlewares/Statics.ts - Serves public/ as static files.
• src/middlewares/StatusMonitor.ts - Mounts express-status-monitor.
• src/middlewares/Views.ts - Configures PUG as the view engine.
• src/models/ - Mongoose model definitions (e.g., User.ts).
• src/services/strategies/ - Passport strategy implementations (Local, Google, Twitter).

Common pitfalls and fixes

• Redis not running causes Kue to crash on startup - Run docker-compose up -d or set QUEUE_ENABLED=false in .env before boot.
• bcrypt-nodejs has no maintained types - Install @types/bcrypt-nodejs explicitly; if you hit build errors, replace with bcryptjs + @types/bcryptjs and update imports in src/models/User.ts.
• cluster import type mismatch in TypeScript 4+ - Use import cluster = require('cluster') or add "esModuleInterop": true in tsconfig.json.
• express-jwt v7+ changed its API - The boilerplate was written for v5/v6. Pin "express-jwt": "^6.1.2" in package.json to avoid UnauthorizedError handler breakage.
• Session secret missing causes silent CSRF failures - Ensure SESSION_SECRET is set in .env; lusca will not throw but CSRF validation will always fail.
• tslint is deprecated - If your project uses ESLint, remove tslint.json and install eslint + @typescript-eslint/parser; the source code itself is unaffected.

Vibe-coding prompt template

I have purchased an AVCP block called "Express TypeScript Node.js Boilerplate"
(upstream package: user@example.com). The source files are in
the `source/` directory of my project. There is a USAGE.md file alongside it
that documents the real exports, file structure, and setup steps.

Please help me integrate this boilerplate into my existing project step by step:

1. Read USAGE.md and source/src/index.ts to understand the boot sequence.
2. Copy or merge the source/ contents into my project, resolving any file
   conflicts with my existing code.
3. Update my tsconfig.json to match the settings in USAGE.md.
4. Create a .env file with all required variables listed in USAGE.md.
5. Wire up the providers (App, Express, Database, Routes, Passport) so the
   server starts correctly.
6. Show me how to add a new typed API controller using IRequest, IResponse,
   and INext from source/src/interfaces/vendors/index.ts.
7. Confirm that clustering (master/worker split in source/src/index.ts) is
   preserved in the final entry point.

Use only the real exports documented in USAGE.md. Do not invent new modules.

License and credit

The source is released under the license found in source/LICENSE and source/LICENSE.md. The upstream project is node-server-with-typescript by Faiz A. Farooqui (faiz@geekyants.com), published as npm package user@example.com.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

전체 설치 가이드와 연동 프롬프트는 구매 후 열람할 수 있습니다.

Ts.ED TypeScript Node.js Backend Framework

Automation, Utilities & Developer Tools

무료