Overview
This guide walks you through the typical development workflow for a Node Blueprint project, from initial setup to deployment.
Initial Setup
1. Create Your Project
First, create a new project using the CLI:
npx create-node-blueprint my-app
2. Install Dependencies
Navigate to your project and install dependencies:
Copy the example environment file and configure your settings:
Update the .env file with your database credentials and other configuration:
PORT=8000
NODE_ENV=development
DATABASE_URL=postgresql://user:password@localhost:5432/mydb
JWT_SECRET=your-secret-key-here
Generate a secure JWT secret using: openssl rand -base64 32
Database Setup
The workflow differs slightly based on your chosen ORM.
With Drizzle
# Generate migrations from schema
npm run db:generate
# Apply migrations to database
npm run db:migrate
# (Optional) Seed the database
npm run db:seed
With Prisma
# Generate Prisma client and apply migrations
npx prisma migrate dev --name init
# (Optional) Seed the database
npm run db:seed
With Mongoose
# No migrations needed - schemas sync automatically
# (Optional) Seed the database
npm run db:seed
Always run migrations/seeds after pulling changes that modify database schemas.
Development Server
Start Development Mode
Start the development server with hot-reloading:
This starts the server using tsx watch, which automatically restarts when you make changes.
Verify Server is Running
Test the health endpoint:
curl http://localhost:8000/api/health
{
"status": "ok",
"timestamp": "2026-03-03T10:30:00.000Z"
}
Making Changes
Adding a New Route
- Create a controller in
src/controllers/:
// src/controllers/product-controller.ts
import { Request, Response } from 'express';
export const getProducts = async (req: Request, res: Response) => {
try {
// Your logic here
res.json({ products: [] });
} catch (error) {
res.status(500).json({ error: 'Failed to fetch products' });
}
};
- Create a route in
src/routes/:
// src/routes/product-routes.ts
import { Router } from 'express';
import * as productController from '../controllers/product-controller.js';
const router = Router();
router.get('/products', productController.getProducts);
export default router;
- Register the route in
src/router.ts:
import productRoutes from './routes/product-routes.js';
router.use('/api', productRoutes);
Adding Database Models
With Drizzle
- Create schema in
src/db/schema/product-schema.ts
- Export from
src/db/schema.ts
- Run
npm run db:generate to create migration
- Run
npm run db:migrate to apply changes
With Prisma
- Update
prisma/schema.prisma
- Run
npx prisma migrate dev --name add_products
With Mongoose
- Create model in
src/models/product-model.ts
- Import and use in your controllers
Adding Middleware
Create middleware in src/middlewares/:
// src/middlewares/auth-middleware.ts
import { Request, Response, NextFunction } from 'express';
export const requireAuth = (req: Request, res: Response, next: NextFunction) => {
// Your authentication logic
next();
};
import { requireAuth } from '../middlewares/auth-middleware.js';
router.get('/products', requireAuth, productController.getProducts);
Testing Your Code
Manual Testing
Use tools like curl, Postman, or Thunder Client:
# Test GET request
curl http://localhost:8000/api/products
# Test POST request
curl -X POST http://localhost:8000/api/products \
-H "Content-Type: application/json" \
-d '{"name": "Product 1", "price": 99.99}'
Running Tests
If you’ve added tests:
Consider adding integration tests for your API endpoints using tools like Jest, Vitest, or Supertest.
Building for Production
Build the Project
Compile TypeScript to JavaScript:
This creates a dist/ directory with compiled code.
Test Production Build
Run the production build locally:
NODE_ENV=production npm start
Docker Workflow
If you enabled Docker support:
Development with Docker
# Start all services (app + database)
docker-compose up -d
# View logs
docker-compose logs -f
# Stop services
docker-compose down
Build Production Image
docker build -t my-app:latest .
Run Production Container
docker run -p 8000:8000 --env-file .env my-app:latest
The generated Dockerfile uses multi-stage builds for optimized image size.
Common Tasks
Updating Dependencies
# Check for updates
npm outdated
# Update packages
npm update
# Update to latest versions
npx npm-check-updates -u
npm install
Database Migrations
# Drizzle: Create new migration
npm run db:generate
# Prisma: Create new migration
npx prisma migrate dev --name migration_name
# Apply migrations in production
npm run db:migrate
Debugging
Use Node.js debugging:
node --inspect dist/server.js
{
"type": "node",
"request": "launch",
"name": "Debug App",
"program": "${workspaceFolder}/src/server.ts",
"runtimeArgs": ["--loader", "tsx"]
}
Git Workflow
Initial Commit
git init
git add .
git commit -m "Initial commit from Node Blueprint"
Feature Branch Workflow
# Create feature branch
git checkout -b feature/new-feature
# Make changes and commit
git add .
git commit -m "Add new feature"
# Merge to main
git checkout main
git merge feature/new-feature
Deployment
Deploy to VPS/Cloud
- Build the project:
npm run build
- Copy files to server
- Install production dependencies:
npm ci --production
- Set environment variables
- Run migrations:
npm run db:migrate
- Start with process manager:
pm2 start dist/server.js
Deploy with Docker
- Build image:
docker build -t my-app .
- Push to registry:
docker push registry/my-app
- Deploy on server:
docker pull registry/my-app && docker run ...
Consider using platforms like Railway, Render, or Fly.io for simplified deployment.
Next Steps
- Review best practices for production-ready code
- Explore the API reference for detailed documentation
- Join the community for support and discussions