Skip to main content

​
Overview

Node Blueprint generates a well-organized project structure that follows modern Node.js best practices. The structure is designed to be scalable, maintainable, and follows separation of concerns principles.

​
Directory Structure

Here’s the complete directory structure generated by Node Blueprint: 
my-project/
├── src/
│   ├── config/          # Configuration files
│   ├── constants/       # Application constants
│   ├── controllers/     # Request handlers
│   ├── enums/           # TypeScript enums
│   ├── middlewares/     # Express middlewares
│   ├── models/          # Database models (Mongoose)
│   ├── db/              # Database setup (Drizzle)
│   ├── prisma/          # Prisma schema and client (Prisma)
│   ├── routes/          # Route definitions
│   ├── services/        # Business logic
│   ├── types/           # TypeScript type definitions
│   │   └── interfaces/  # TypeScript interfaces
│   ├── utils/           # Utility functions
│   ├── validations/     # Request validation schemas
│   ├── views/           # EJS templates
│   ├── app.ts           # Express app configuration
│   ├── server.ts        # Server entry point
│   └── router.ts        # Main router
├── scripts/             # Build and deployment scripts
├── .env                 # Environment variables
├── .gitignore           # Git ignore rules
├── tsconfig.json        # TypeScript configuration
├── package.json         # Project dependencies
└── README.md            # Project documentation
The exact structure varies based on your selected options (framework, ORM, authentication).

​
Core Directories

​
src/

The main source directory containing all application code.

​
src/config/

Configuration files for various aspects of your application:
  • env.ts - Environment variable configuration and validation
  • cors.ts - CORS policy configuration (Express)
  • logger.ts - Winston logger configuration (Express)
  • db.ts - Database connection setup (Mongoose)

​
src/controllers/

Request handlers that process incoming requests and return responses:
  • health-controller.ts - Health check endpoints
  • user-controller.ts - User-related request handlers
  • auth-controller.ts - Authentication endpoints (if JWT auth enabled)
Controllers should be thin and delegate business logic to services.

​
src/routes/

Route definitions that map URLs to controllers:
  • health-routes.ts - Health check routes
  • user-routes.ts - User management routes
  • auth-routes.ts - Authentication routes (if JWT auth enabled)

​
src/middlewares/

Express middleware functions:
  • cors-middleware.ts - CORS handling
  • error-middleware.ts - Global error handling
  • helmet-middleware.ts - Security headers

​
src/services/

Business logic and data access layer:
  • auth-services.ts - Authentication and authorization logic (if JWT auth enabled)
Services should contain reusable business logic that can be called from multiple controllers.

​
src/validations/

Request validation schemas:
  • auth-validations.ts - Authentication request validators (if JWT auth enabled)

​
src/enums/

TypeScript enumerations for type-safe constants:
  • role-enum.ts - User role definitions
  • token-enum.ts - Token type definitions (if JWT auth enabled)

​
Database-Specific Structure

​
Drizzle ORM

When using Drizzle, these files are generated: 
src/
├── db/
│   ├── schema/
│   │   ├── user-schema.ts    # User table schema
│   │   └── token-schema.ts   # Token table schema (with JWT)
│   ├── index.ts              # Database connection
│   ├── seed.ts               # Database seeding
│   └── schema.ts             # Schema exports
└── drizzle.config.ts         # Drizzle configuration

​
Prisma ORM

When using Prisma, these files are generated: 
prisma/
├── schema.prisma      # Prisma schema definition
├── prisma-client.ts   # Prisma client instance
└── seed.ts            # Database seeding

​
Mongoose ORM

When using Mongoose, these files are generated: 
src/
├── config/
│   └── db.ts              # MongoDB connection
└── models/
    ├── user-model.ts      # User model schema
    ├── token-model.ts     # Token model schema (with JWT)
    └── seed.ts            # Database seeding

​
Root Files

​
src/app.ts

The Express application setup file. This is where:
  • Middleware is configured
  • Routes are registered
  • Error handling is set up
  • View engine is configured

​
src/server.ts

The server entry point that:
  • Loads environment variables
  • Creates the HTTP server
  • Connects to the database
  • Starts listening on the configured port
  • Handles graceful shutdown

​
src/router.ts

The main router that aggregates all route modules.

​
Configuration Files

​
.env

Environment variables for different configurations: 
PORT=8000
NODE_ENV=development
DATABASE_URL=postgresql://user:password@localhost:5432/mydb
JWT_SECRET=your-secret-key
Never commit .env files to version control. Use .env.example for documentation.

​
tsconfig.json

TypeScript compiler configuration optimized for Node.js development.

​
.gitignore

Pre-configured to ignore:
  • node_modules/
  • .env files
  • Build output
  • Log files
  • IDE configurations

​
Docker Support

If Docker is enabled, these files are generated:
  • Dockerfile - Multi-stage Docker build configuration
  • docker-compose.yml - Docker Compose setup with database services
  • .dockerignore - Files to exclude from Docker context
The docker-compose.yml file includes pre-configured database services (PostgreSQL, MySQL, or MongoDB) based on your ORM selection.

​
Best Practices

  1. Keep related code together - Group files by feature when your project grows
  2. Use absolute imports - Configure path aliases in tsconfig.json for cleaner imports
  3. Separate concerns - Controllers handle HTTP, services handle business logic, models handle data
  4. Type everything - Leverage TypeScript’s type system for better code quality
  5. Environment-specific configs - Use .env files for different environments

​
Next Steps

Now that you understand the project structure, learn about the development workflow to start building your application.

Build docs developers (and LLMs) love

Get started for freeTalk to us