https://github.com/jmrl23/fastify-template
A robust and user-friendly template for building Fastify applications. It comes with all the essentials to kickstart your project. Additionally, it's highly flexible, allowing you to effortlessly incorporate your own features and enhancements.
https://github.com/jmrl23/fastify-template
api backend fastify fastify-template fastifyjs http javascript nodejs production-ready restful template typescript web
Last synced: about 2 months ago
JSON representation
A robust and user-friendly template for building Fastify applications. It comes with all the essentials to kickstart your project. Additionally, it's highly flexible, allowing you to effortlessly incorporate your own features and enhancements.
- Host: GitHub
- URL: https://github.com/jmrl23/fastify-template
- Owner: jmrl23
- License: mit
- Created: 2024-01-03T17:51:51.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2025-03-19T14:27:05.000Z (over 1 year ago)
- Last Synced: 2025-03-19T14:35:07.596Z (over 1 year ago)
- Topics: api, backend, fastify, fastify-template, fastifyjs, http, javascript, nodejs, production-ready, restful, template, typescript, web
- Language: TypeScript
- Homepage:
- Size: 173 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Fastify Template
[](https://raw.githubusercontent.com/jmrl23/fastify-template/refs/heads/main/LICENSE)
[](https://github.com/jmrl23/fastify-template)
[](https://github.com/prettier/prettier)
[](https://codecov.io/gh/jmrl23/fastify-template)
A scalable backend template featuring modular architecture, automatic route loading, type-safe validation, and interactive API documentation.
## Overview
This template provides a maintainable backend structure with a focus on developer experience and scalability. Key features include:
- **Modular Architecture**: Organize code by feature domains (`src/modules`) for better separation of concerns.
- **Automatic Route Loading**: Files ending in `.route.ts` (or `.route.js`) are automatically loaded and registered as routes based on the file structure.
- **Zod Validation**: First-class support for Zod schemas to validate requests and responses, automatically generating JSON schemas for Fastify.
- **Swagger/OpenAPI**: Interactive API documentation is automatically generated.
- **Type-Safe Config**: Environment variables are strictly typed and validated using `env-var`.
- **Docker Ready**: Includes production-optimized Dockerfile and docker-ignore settings.
---
## Folder Structure
```text
.
├── public/ # Publicly served static assets
├── src/
│ ├── common/ # Shared utilities (logger, helpers)
│ ├── modules/ # Domain-specific modules (e.g., todos)
│ │ └── todos/ # Example module structure
│ ├── plugins/ # Global plugins (routes, swagger)
│ ├── bootstrap.ts # Global plugin registrations
│ ├── init.ts # Pre-startup initialization
│ ├── server.ts # Fastify instance and server configuration
│ └── main.ts # Application entry point
├── Dockerfile # Production Docker setup
├── package.json # Dependencies and scripts
└── tsconfig.json # TypeScript configuration
```
---
## Getting Started
### 1. Clone the repository
```bash
git clone https://github.com/jmrl23/fastify-template.git
cd fastify-template
```
### 2. Install dependencies
```bash
yarn install
```
### 3. Run in development
```bash
yarn run start:dev
```
- Starts the server with `tsx watch` for hot-reloading.
- Swagger UI available at `http://localhost:3001/documentation` (if PORT is 3001).
### 4. Build and run
```bash
yarn run build
yarn run start
```
---
## Environment Variables
Configuration is managed in `src/common/env.ts`. Define these in a `.env` file:
| Variable | Description | Default |
| :---------------- | :----------------------------------------------------- | :------------ |
| `NODE_ENV` | Environment mode (`development`, `test`, `production`) | `development` |
| `PORT` | Port to listen on | `3001` |
| `TRUST_PROXY` | Comma-separated list of trust proxies | `loopback` |
| `CORS_ORIGIN` | Comma-separated list of allowed origins | `undefined` |
| `SWAGGER_SERVERS` | Comma-separated list of urls | `undefined` |
---
## Scripts
| Script | Description |
| :-------------------- | :-------------------------------------------------------------- |
| `yarn run start` | Start server. |
| `yarn run start:dev` | Start server in development mode with watch mode and inspector. |
| `yarn run start:prod` | Start server in production mode (`NODE_ENV=production`). |
| `yarn run build` | Compile TypeScript to JavaScript. |
| `yarn run test` | Run tests using Jest. |
| `yarn run format` | Format code with Prettier. |
| `yarn run lint` | Lint code with ESLint. |
---
## Architecture Highlights
### Automatic Route Loading
Routes are defined in `*.route.ts` (or `*.route.js`) files within `src/modules`. The `src/plugins/routes.ts` plugin automatically discovers these files. The URL path is derived from the file path relative to `src/modules`.
Example: `src/modules/todos/todos.route.ts` -> `/todos`
### Validation with Zod
Schemas are defined using Zod as `*.schema.ts`. These are used in route definitions to validate `body`, `querystring`, and `params`, and to type the request handlers.
---
## Docker
Build and run the container:
```bash
docker build -t fastify-app .
docker run -p 3001:3001 --env-file .env fastify-app
```
---
## License
This project is licensed under the [**MIT License**](./LICENSE).