Backend API Template

A modern, production-ready Node.js API template built with TypeScript, Fastify, and best practices.

🚀 Quick Start

# Clone the template
git clone <your-repo-url>
cd be-core

# Install dependencies
npm install

# Setup environment
cp .env_template .env

# Start development server
npm run dev

The API will be available at http://localhost:3000

✨ Features

• ⚡ Fastify - Fast and efficient web framework
• 🔷 TypeScript - Type safety and better developer experience
• 🛡️ Environment validation - Runtime config validation with Zod
• 🧪 Testing - Vitest with coverage reporting
• 🔧 Code quality - ESLint + Prettier + Husky pre-commit hooks
• 🐳 Docker - Multi-stage production builds with health checks
• 📊 Health monitoring - Built-in health check endpoints
• 🚨 Error handling - Comprehensive error handling middleware
• 📝 Hot reload - Development server with auto-restart

🛠️ Available Scripts

Script	Description
npm run dev	Start development server with hot reload
npm test	Run test suite
npm run test:watch	Run tests in watch mode
npm run build	Build for production
npm start	Start production server
npm run lint	Lint code with ESLint
npm run lint:fix	Fix linting issues automatically
npm run format	Format code with Prettier
npm run type-check	Run TypeScript type checking

🔌 API Endpoints

Method	Endpoint	Description
GET	/	Root endpoint with basic info
GET	/api/v1/	API version 1 root
GET	/api/v1/health	Health check with system info
GET	/api/v1/example	Example users endpoint

Example Responses

Health Check (GET /api/v1/health)

{
  "status": "ok",
  "timestamp": "2025-08-08T12:00:00.000Z",
  "uptime": 42.5,
  "version": "v1"
}

Not Found (GET /nonexistent)

{
  "error": "Not Found",
  "message": "Route GET:/nonexistent not found",
  "statusCode": 404,
  "timestamp": "2025-08-08T12:00:00.000Z"
}

🔧 Environment Configuration

Copy .env.example to .env and configure:

NODE_ENV=development          # Environment: development, test, staging, production
PORT=3000                    # Server port
HOST=localhost               # Server host
LOG_LEVEL=info              # Log level: fatal, error, warn, info, debug, trace

🐳 Docker Support

Development

# Run with hot reload and volume mounting
docker-compose --profile dev up --build

Production

# Build and run production container
docker-compose up --build

# Or run manually
docker build -t be-core .
docker run -p 3000:3000 be-core

📁 Project Structure

src/
├── config/              # Configuration files
│   └── env.ts          # Environment validation
├── plugins/            # Fastify plugins
│   ├── error-handler.ts # Global error handling
│   └── not-found.ts    # 404 handler
├── routes/             # API routes
│   └── v1.ts          # API v1 routes
├── __tests__/         # Test files
│   └── server.test.ts # Server tests
├── app.ts             # App factory
└── server.ts          # Server entry point

.vscode/               # VS Code configuration
├── extensions.json    # Recommended extensions
├── launch.json       # Debug configurations
├── settings.json     # Workspace settings
└── tasks.json        # Build tasks

.husky/               # Git hooks
├── pre-commit       # Runs on commit
└── pre-push         # Runs on push

🧪 Testing

The template includes a comprehensive test setup with Vitest:

# Run tests once
npm test

# Run tests in watch mode
npm run test:watch

# Run with coverage
npm run test:coverage

Tests are located in src/__tests__/ and use Fastify's built-in inject() method for fast, reliable testing.

🔍 Code Quality

The project enforces code quality through:

• ESLint - Code linting with TypeScript rules
• Prettier - Code formatting
• Husky - Git hooks for pre-commit and pre-push validation
• TypeScript - Type checking

Pre-commit hook runs:

• Prettier formatting
• ESLint fixes

Pre-push hook runs:

• Type checking
• Test suite
• Production build

🚀 Deployment

Production Build

npm run build
npm start

Docker Deployment

docker build -t your-api .
docker run -p 3000:3000 your-api

Environment Variables for Production

Ensure these are set in your production environment:

• NODE_ENV=production
• PORT=3000 (or your preferred port)
• HOST=0.0.0.0 (for Docker)
• LOG_LEVEL=info

🙏 Acknowledgments

Built with:

• Fastify - Fast web framework
• TypeScript - Type safety
• Zod - Schema validation
• Vitest - Testing framework
• ESLint & Prettier - Code quality