Quickstart

Create your first project

This guide walks you through creating a complete Node.js API with Express, PostgreSQL, and Drizzle ORM, including JWT authentication.

Run the CLI

Open your terminal and run:

npm create node-blueprint

The CLI will start and display a welcome message.

Enter project name

When prompted, enter your project name:

◆  What is the name of your project?
│  my-blog-api

The CLI creates a directory with this name in your current location. If the directory already exists, you’ll be asked whether to overwrite it.

Select framework

Choose your preferred Node.js framework:

◆  Which Node.js framework would you like to use?
│  ● Express

Currently, Express is the primary option with Fastify support in development.

Select database

Choose your database:

◆  Which database would you like to use?
│  ○ MongoDB
│  ○ MySQL  
│  ● PostgreSQL

Use arrow keys to navigate and press Enter to select.

Select ORM

Choose your ORM based on the database you selected:

◆  Which ORM/ODM would you like to use?
│  ● Drizzle
│  ○ Prisma

If you selected MongoDB, Mongoose is automatically selected as it’s the recommended ODM for MongoDB.

Configure authentication

Choose whether to include authentication:

◆  Would you like to include one of the following authentication?
│  ● Basic JWT authentication
│  ○ None

JWT auth includes login, register, token refresh, and password hashing with bcrypt.

Add optional features

Select additional features (use Space to select, Enter to continue):

◆  What additional features would you like to include?
│  ◻ Include Docker setup

Docker setup includes a Dockerfile and docker-compose.yml with your selected database pre-configured.

Wait for generation

The CLI creates your project structure, generates files, and installs dependencies:

✔ Creating project files...
✔ Package.json created
✔ Installing dependencies...
✔ Git initialized

This typically takes 30-60 seconds depending on your internet speed.

What was generated?

After successful creation, you’ll see a success message with next steps:

┌  🎉 Project created successfully!
│
│  Next steps:
│  1. cd my-blog-api
│  2. npm run dev
│
│  Your app is available at:
│  The server is available on port 8000
│
│  Database commands:
│  - Generate migration: npm run db:generate
│  - Apply migration: npm run db:migrate
│
│  Thank you for using node-blueprint. If you find it useful,
│  please give it a star on GitHub!
│  https://github.com/yogendrarana/node-blueprint
└

Project structure

Your generated project includes:

my-blog-api/
├── src/
│   ├── config/          # Configuration files (database, CORS, logger)
│   ├── controllers/     # Request handlers
│   ├── db/             # Database schema and migrations (Drizzle)
│   │   ├── schema/
│   │   │   ├── user-schema.ts
│   │   │   └── token-schema.ts
│   │   ├── index.ts
│   │   ├── schema.ts
│   │   └── seed.ts
│   ├── enums/          # TypeScript enums
│   ├── middlewares/    # Express middleware (CORS, error handling, helmet)
│   ├── routes/         # Route definitions
│   ├── services/       # Business logic
│   ├── types/          # TypeScript type definitions
│   ├── utils/          # Utility functions
│   ├── validations/    # Request validation schemas
│   ├── views/          # EJS templates
│   ├── app.ts          # Express app configuration
│   ├── router.ts       # Main router
│   └── server.ts       # Server entry point
├── .env                # Environment variables
├── .gitignore
├── drizzle.config.ts   # Drizzle ORM configuration
├── package.json
├── README.md
└── tsconfig.json

If you selected Docker, you’ll also see Dockerfile, docker-compose.yml, and .dockerignore files in the root directory.

Configure your environment

Before running the app, set up your environment variables:

Open the .env file

cd my-blog-api

The .env file is already created with sensible defaults.

Update database connection

Edit the database URL to match your setup:

DATABASE_URL="postgresql://postgres:password@localhost:5432/mydb"

Configure JWT secrets (if using auth)

Update the JWT secrets (important for production):

JWT_ACCESS_SECRET="your-access-secret-here"
JWT_REFRESH_SECRET="your-refresh-secret-here"

Never commit real secrets to version control. The generated .gitignore already excludes .env files.

Set the port (optional)

The default port is 8000, but you can change it:

PORT=3000

Set up the database

Generated projects include database schema and migration tools:

Drizzle ORM
Prisma ORM
Mongoose ODM

Ensure database exists

Create your database if it doesn’t exist:

PostgreSQL

createdb mydb

Or connect to PostgreSQL and run:

CREATE DATABASE mydb;

Generate migration

Generate the migration files from your schema:

npm run db:generate

This creates migration files in src/db/migrations/ based on your schema definitions in src/db/schema/.

Apply migration

Run the migration to create tables:

npm run db:migrate

Your database now has the users and tokens tables (if you selected JWT auth).

Seed data (optional)

The project includes a seed file at src/db/seed.ts. Customize it and run:

npm run db:seed

Ensure database exists

Create your database if it doesn’t exist (same as Drizzle instructions).

Generate migration

Generate and apply migrations:

npx prisma migrate dev

This creates the migration and applies it to your database.

Generate Prisma Client

Generate the Prisma Client (usually automatic, but run if needed):

npx prisma generate

Seed data (optional)

Customize prisma/seed.ts and run:

npx prisma db seed

Start MongoDB

Ensure MongoDB is running:

mongod

Or use Docker:

docker run -d -p 27017:27017 --name mongodb mongo:7

Seed data (optional)

MongoDB creates collections automatically. To seed data, customize src/models/seed.ts and run it:

npx tsx src/models/seed.ts

Run your application

Start the development server:

npm run dev

You should see:

[INFO] Server is running on port 8000
[INFO] Database connected successfully

The dev server uses tsx for hot-reloading. Changes to your TypeScript files automatically restart the server.

Test the API

Your application includes several pre-built endpoints:

Health check

Verify the server is running:

curl http://localhost:8000/api/health

Response:

{
  "status": "ok",
  "timestamp": "2026-03-03T12:34:56.789Z"
}

Authentication endpoints (if JWT auth enabled)

Register
Login
Refresh token

Create a new user:

curl -X POST http://localhost:8000/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "email": "[email protected]",
    "password": "SecurePassword123!"
  }'

Response:

{
  "success": true,
  "message": "User registered successfully",
  "data": {
    "user": {
      "id": "1",
      "name": "John Doe",
      "email": "[email protected]"
    },
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
  }
}

Authenticate an existing user:

curl -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "SecurePassword123!"
  }'

Response includes accessToken and refreshToken.

Get a new access token using your refresh token:

curl -X POST http://localhost:8000/api/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
  }'

User endpoints

Get all users (example endpoint):

curl http://localhost:8000/api/users

In production, you should add authentication middleware to protect sensitive endpoints. The generated code includes examples you can extend.

Explore the code

Now that your app is running, explore the generated code:

Routes

Check src/routes/ to see how endpoints are defined. Each route file maps HTTP methods to controller functions.

Controllers

Open src/controllers/ to see request handling logic. Controllers process requests and call services.

Database schema

For Drizzle: src/db/schema/
For Prisma: prisma/schema.prisma
For Mongoose: src/models/

Middleware

Review src/middlewares/ for CORS, error handling, and security (Helmet) configurations.

Next steps

Add new endpoints

Create new route files in src/routes/, controllers in src/controllers/, and wire them together in src/router.ts.

Extend the schema

Add new database models or modify existing ones in your schema files, then generate and run migrations.

Add validation

Use the patterns in src/validations/ to add request validation for your new endpoints.

Deploy

When ready, build for production:

npm run build
npm start

Or use the included Docker setup for containerized deployment.

The generated README.md in your project includes additional details about the specific stack you selected. Check it for more information!

Troubleshooting

Database connection errors

If you see connection errors:

Verify your database is running (check with psql, mysql, or mongosh)
Confirm the DATABASE_URL in .env matches your database credentials
Ensure the database exists (create it if needed)
Check firewall settings if using a remote database

Port already in use

If port 8000 is already taken:

Change the PORT in your .env file
Or find and kill the process using port 8000:

# Find the process
lsof -ti:8000

# Kill it
kill -9 $(lsof -ti:8000)

Migration errors

For Drizzle migration issues:

Check that drizzle.config.ts has the correct database URL
Ensure your database user has sufficient permissions
Try dropping and recreating your database (development only!)

For Prisma:

Delete the prisma/migrations/ folder
Run npx prisma migrate dev --name init to start fresh

TypeScript errors

If you see type errors:

Run npm install to ensure all dependencies are installed
For Prisma: Run npx prisma generate to update the Prisma Client
Restart your IDE’s TypeScript server
Check that tsconfig.json hasn’t been modified

What’s next?

You’ve successfully created and run your first Node Blueprint project! Here are some ideas for what to build:

Blog API: Add posts, comments, and categories
E-commerce backend: Products, carts, and orders
Task management: Projects, tasks, and team collaboration
Social network: Users, posts, likes, and follows

Happy coding!

Get Started

CLI Reference

Customization

Guides

Create your first project

What was generated?

Project structure

Configure your environment

Set up the database

Run your application

Test the API

Health check

Authentication endpoints (if JWT auth enabled)

User endpoints

Explore the code

Routes

Controllers

Database schema

Middleware

Next steps

Troubleshooting

What’s next?

Build docs developers (and LLMs) love

Get Started

CLI Reference

Customization

Guides

​Create your first project

​What was generated?

​Project structure

​Configure your environment

​Set up the database

​Run your application

​Test the API

​Health check

​Authentication endpoints (if JWT auth enabled)

​User endpoints

​Explore the code

Routes

Controllers

Database schema

Middleware

​Next steps

​Troubleshooting

​What’s next?

Build docs developers (and LLMs) love

Create your first project

What was generated?

Project structure

Configure your environment

Set up the database

Run your application

Test the API

Health check

Authentication endpoints (if JWT auth enabled)

User endpoints

Explore the code

Next steps

Troubleshooting

What’s next?