Node.js Boilerplate with Fastify, TypeScript, and Prisma

📖 Español

A modern Node.js boilerplate configured with Fastify, TypeScript, Prisma ORM, and PostgreSQL. Provides a solid foundation for building scalable and well-structured backend applications.

🚀 Tech Stack

• Fastify (v5.7.4) - Fast and efficient web framework
• TypeScript - Static typing for safety
• Prisma (v7.4.2) - Modern ORM for PostgreSQL
• PostgreSQL (v15) - Relational database
• Docker & Docker Compose - Containerization
• Swagger/OpenAPI - Automatic API documentation

📋 Prerequisites

Option 1: Local Development

• Node.js >= 20.x
• npm >= 10.x
• PostgreSQL >= 15.x

Option 2: Docker

• Docker
• Docker Compose

🔧 Installation

Option 1: Local Development

1. Clone the repository

git clone <your-repo>
cd node-boilerplate

2. Install dependencies

npm install

3. Configure environment variables

Create a .env file in the project root:

DATABASE_URL="postgresql://user:password@localhost:5432/appdb?schema=public"
PORT=3000
NODE_ENV=development

Example with default PostgreSQL:

DATABASE_URL="postgresql://postgres:postgres@localhost:5432/appdb?schema=public"
PORT=3000
NODE_ENV=development

4. Set up the database

# Generate Prisma client
npm run prisma:generate

# Run migrations
npm run prisma:migrate

5. Start the server

# Development mode (watch)
npm run dev

# Server will be available at http://localhost:3000

Option 2: Docker Compose

1. Clone the repository

git clone <your-repo>
cd node-boilerplate

2. Start the containers

docker-compose up -d

This will start:

• API at http://localhost:3000
• PostgreSQL at localhost:5432

3. Verify it's running

docker-compose ps

# View API logs
docker-compose logs -f api

# View database logs
docker-compose logs -f db

4. Stop the containers

docker-compose down

# With data volume
docker-compose down -v  # Removes the database

📁 Project Structure

node-boilerplate/
├── src/
│   ├── app.ts                 # Main Fastify configuration
│   ├── server.ts              # Server entry point
│   ├── config/
│   │   └── env.ts            # Environment variables config
│   ├── hooks/
│   │   └── error-handler.ts  # Global error handling
│   ├── modules/
│   │   └── user/             # User module
│   │       ├── user.controller.ts
│   │       ├── user.routes.ts
│   │       ├── user.service.ts
│   │       ├── user.repository.ts
│   │       ├── user.schema.ts
│   │       └── user.types.ts
│   ├── plugins/
│   │   ├── prisma.ts         # Prisma plugin
│   │   └── swagger.ts        # Swagger/OpenAPI config
│   ├── types/
│   │   └── fastify.d.ts      # Extended Fastify types
│   └── utils/
│       └── errors.ts         # Error utilities
├── prisma/
│   ├── schema.prisma         # Database schema
│   └── migrations/           # Migration history
├── docker-compose.yml        # Container orchestration
├── Dockerfile               # Docker image build
├── package.json            # Dependencies and scripts
├── tsconfig.json           # TypeScript configuration
└── .env                    # Environment variables (don't commit)

📝 Available Scripts

# Development
npm run dev              # Start server in watch mode

# Build
npm run build            # Compile TypeScript to JavaScript

# Production
npm start               # Run compiled application

# Prisma
npm run prisma:generate # Generate Prisma client
npm run prisma:migrate  # Run migrations (development)
npm run prisma:deploy   # Run migrations (production)

🗄️ Database

Current Schema

The project comes with a basic User model:

model User {
  id    String @id @default(uuid())
  email String @unique
  name  String
}

Adding New Migrations

After modifying prisma/schema.prisma:

npm run prisma:migrate

This will:

1. Detect changes in the schema
2. Create a new migration
3. Apply changes to the database

Access Prisma Studio

Visual interface for managing data:

npx prisma studio

Opens at http://localhost:5555

🌐 API Endpoints

Users

• GET /users - List all users
• GET /users/:id - Get a user
• POST /users - Create a user
• PUT /users/:id - Update a user
• DELETE /users/:id - Delete a user

Swagger Documentation

Interactive documentation available at:

http://localhost:3000/documentation

🚢 Deployment

Build for Production

npm run build
npm start

With Docker

# Manual build
docker build -t node-boilerplate .

# Run
docker run -p 3000:3000 \
  -e DATABASE_URL="postgresql://user:pass@host:5432/db?schema=public" \
  node-boilerplate

# Or with Docker Compose
docker-compose -f docker-compose.yml up -d

Production Environment Variables

Make sure to configure:

• DATABASE_URL - PostgreSQL connection
• PORT - Port (default: 3000)
• NODE_ENV - production

🔌 Extending the Project

Adding a New Module

1. Create folder in src/modules/<module-name>/

2. Create files:

   • <name>.types.ts - Types/Interfaces
   • <name>.schema.ts - Validation schemas (TypeBox)
   • <name>.repository.ts - Database access (Prisma)
   • <name>.service.ts - Business logic
   • <name>.controller.ts - HTTP handlers
   • <name>.routes.ts - Route definitions

3. Register in src/app.ts:

await app.register(myModuleRoutes, { prefix: "/my-route" })

🐛 Troubleshooting

PostgreSQL connection error

# Verify PostgreSQL is running
# If using Docker:
docker-compose ps

# If local, restart PostgreSQL and verify DATABASE_URL

Migration error

# Reset database (⚠️ Deletes data)
npx prisma migrate reset

# Or sync the schema
npx prisma db push

Port 3000 in use

Change in .env:

PORT=3001

📚 Resources

• Fastify Docs
• Prisma Docs
• TypeBox Docs
• PostgreSQL Docs

📄 License

ISC

---

Need help? Check the official project documentation or open an issue in the repository.