Node.js Fastify Prisma Starter

Production-ready Node.js Fastify Prisma starter for building scalable REST APIs with TypeScript, PostgreSQL, and modern development practices. A clean architecture Fastify Prisma boilerplate with JWT authentication, Docker support, and comprehensive documentation.

Why this Fastify Prisma starter?

This Node.js Fastify Prisma starter template provides everything you need to build production-ready REST APIs quickly. Built with Fastify (high-performance web framework), Prisma ORM (type-safe database access), and TypeScript for a robust development experience.

🚀 Features

This Fastify Prisma TypeScript starter includes:

• 🔧 Tech Stack: Node.js, Fastify, TypeScript, PostgreSQL, Prisma ORM
• 🔐 Authentication: JWT-based authentication with refresh tokens (Fastify Prisma authentication starter)
• 👥 User Management: Complete user CRUD with role-based access control
• 📁 File Upload: Cloudinary integration for media management
• 📧 Email Service: Nodemailer integration for email functionality
• 🛡️ Security: Helmet, CORS, rate limiting, input validation
• 📊 Database: PostgreSQL with Prisma ORM for type-safe operations
• 🧪 Testing: Jest setup with coverage reporting
• 📝 Code Quality: ESLint, Prettier, Husky for code standards
• 🐳 Docker: Dockerized Fastify Prisma starter with docker-compose
• 📚 Documentation: Comprehensive documentation and API reference
• 🔄 CI/CD Ready: GitHub Actions workflow templates
• ⚡ Module Generation: Automated module creation and renaming scripts

📋 Prerequisites

• Node.js (v16 or higher)
• npm or yarn package manager
• PostgreSQL database
• Git

⚡ Getting Started with Node.js Fastify Prisma Boilerplate

1. Clone the Repository

git clone https://github.com/ibnabdullah1/nodejs-fastify-prisma-starter.git
cd nodejs-fastify-prisma-starter

2. Install Dependencies

npm install

3. Environment Setup

# Copy environment template
cp env.example .env

# Edit .env with your configuration
nano .env

4. Database Setup

# Generate Prisma client
npm run db:generate

# Run database migrations
npm run migrate

# (Optional) Seed the database
npm run db:seed

5. Start Development Server

npm run dev

Your server will be running at http://localhost:5000

🛠️ Available Scripts

Development

• npm run dev - Start development server with hot reload
• npm run build - Build the project for production
• npm run start - Start production server

Database

• npm run migrate - Run database migrations
• npm run migrate:deploy - Deploy migrations to production
• npm run migrate:reset - Reset database
• npm run db:studio - Open Prisma Studio
• npm run db:generate - Generate Prisma client
• npm run db:seed - Seed database with sample data

Code Quality

• npm run lint - Run ESLint
• npm run lint:fix - Fix ESLint errors
• npm run format - Format code with Prettier
• npm run type-check - Run TypeScript type checking

Module Scripts

• npm run create-module <name> - Create a new module with complete structure
• npm run rename-module <old> <new> - Rename an existing module and update all references

Testing

• npm test - Run tests
• npm run test:watch - Run tests in watch mode
• npm run test:coverage - Run tests with coverage

Docker

• npm run docker:build - Build Docker image
• npm run docker:run - Run Docker container
• npm run docker:compose - Start with docker-compose

📁 Project Structure

src/
├── controllers/         # Request handlers
├── services/           # Business logic
├── models/             # Data models
├── middleware/         # fastify middleware
├── utils/              # Utility functions
├── types/              # TypeScript type definitions
├── constants/          # Application constants
├── validators/         # Request validation schemas
├── database/           # Database configuration
├── routes/             # Route definitions
├── config/             # Configuration files
├── scripts/            # Utility scripts
├── templates/          # Email templates
├── tests/              # Test files
├── app.ts              # fastify app configuration
└── server.ts           # Server entry point

🔧 Configuration

Environment Variables

See env.example for all available environment variables:

• Database: PostgreSQL connection string
• JWT: Authentication secrets and expiration times
• Email: SMTP configuration for email sending
• Cloudinary: File upload and storage
• Security: CORS, rate limiting, and other security settings

Database Schema

The template includes the following models:

• User: User authentication and profile management
• Media: File upload and metadata storage

🛠️ Module Generation

This Fastify Prisma starter template for Node.js includes powerful scripts to quickly generate and manage modules with clean architecture patterns.

Create a New Module

Generate a complete module structure with all necessary files:

npm run create-module <module-name>

# Examples:
npm run create-module product
npm run create-module order
npm run create-module category

Generated Files:

• module.routes.ts - Fastify plugin routes with authentication
• module.controller.ts - Request handlers (FastifyRequest/FastifyReply)
• module.service.ts - Business logic with Prisma
• module.interface.ts - TypeScript interfaces
• module.validation.ts - Zod validation schemas
• module.constant.ts - Module constants

After creating a module:

1. Register routes in src/app/routes/index.ts:

import { ProductRoutes } from "../modules/product/product.routes";

const router = async (fastify: FastifyInstance) => {
  fastify.register(ProductRoutes, { prefix: "/product" });
};

2. Update Prisma schema (prisma/schema.prisma):

model Product {
  id        Int      @id @default(autoincrement())
  name      String
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
}

3. Run migrations:

npm run migrate

Rename a Module

Rename an existing module and update all references:

npm run rename-module <old-name> <new-name>

# Examples:
npm run rename-module product item
npm run rename-module order purchase

What it does:

• Renames the module directory
• Updates all file contents (lowercase and capitalized names)
• Renames files if they contain the module name
• Updates all references throughout the codebase

Important: After renaming, manually update:

• Route registrations in src/app/routes/index.ts
• Prisma schema if needed
• Any other external references

🚀 Deployment

Docker Deployment

# Build and start with docker-compose
npm run docker:compose

# Or build and run manually
npm run docker:build
npm run docker:run

Manual Deployment

1. Build the application:

   npm run build

2. Set up production environment:

   cp env.example .env
   # Configure production environment variables

3. Run database migrations:

   npm run migrate:deploy

4. Start the application:

   npm start

📚 Documentation

Comprehensive documentation is available in the DOCS/ directory:

• Quick Start Guide - Get started in 5 minutes
• API Documentation - Complete API reference
• Project Structure - Detailed project organization
• Deployment Guide - Production deployment
• Troubleshooting - Common issues and solutions

🧪 Testing

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

🔍 Code Quality

The project includes:

• ESLint for code linting
• Prettier for code formatting
• Husky for git hooks
• lint-staged for pre-commit checks

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

See Contributing Guide for detailed information.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

• Documentation: Check the DOCS/ directory
• Issues: Create an issue on GitHub
• Discussions: Use GitHub Discussions for questions

🙏 Acknowledgments

• Fastify - Web framework
• Prisma - Database ORM
• TypeScript - Type safety
• PostgreSQL - Database

---

Happy Coding! 🎉