{"id":26891456,"url":"https://github.com/jmrl23/fastify-template","last_synced_at":"2026-05-06T13:10:08.180Z","repository":{"id":215388781,"uuid":"738644557","full_name":"jmrl23/fastify-template","owner":"jmrl23","description":"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.","archived":false,"fork":false,"pushed_at":"2025-03-19T14:27:05.000Z","size":177,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-19T14:35:07.596Z","etag":null,"topics":["api","backend","fastify","fastify-template","fastifyjs","http","javascript","nodejs","production-ready","restful","template","typescript","web"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jmrl23.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-01-03T17:51:51.000Z","updated_at":"2025-03-19T14:27:09.000Z","dependencies_parsed_at":"2024-03-15T08:35:44.864Z","dependency_job_id":"cabd7d3d-3de1-49eb-8332-1e9a93ead4d2","html_url":"https://github.com/jmrl23/fastify-template","commit_stats":null,"previous_names":["jmrl23/fastify-template"],"tags_count":0,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jmrl23%2Ffastify-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jmrl23%2Ffastify-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jmrl23%2Ffastify-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jmrl23%2Ffastify-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jmrl23","download_url":"https://codeload.github.com/jmrl23/fastify-template/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246553085,"owners_count":20795835,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","backend","fastify","fastify-template","fastifyjs","http","javascript","nodejs","production-ready","restful","template","typescript","web"],"created_at":"2025-03-31T22:34:04.844Z","updated_at":"2026-05-06T13:10:08.175Z","avatar_url":"https://github.com/jmrl23.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Fastify Template\n\n[![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](https://raw.githubusercontent.com/jmrl23/fastify-template/refs/heads/main/LICENSE)\n[![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)](https://github.com/jmrl23/fastify-template)\n[![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://github.com/prettier/prettier)\n[![codecov](https://codecov.io/gh/jmrl23/fastify-template/graph/badge.svg?token=8IAJGFPPC9)](https://codecov.io/gh/jmrl23/fastify-template)\n\nA scalable backend template featuring modular architecture, automatic route loading, type-safe validation, and interactive API documentation.\n\n## Overview\n\nThis template provides a maintainable backend structure with a focus on developer experience and scalability. Key features include:\n\n- **Modular Architecture**: Organize code by feature domains (`src/modules`) for better separation of concerns.\n- **Automatic Route Loading**: Files ending in `.route.ts` (or `.route.js`) are automatically loaded and registered as routes based on the file structure.\n- **Zod Validation**: First-class support for Zod schemas to validate requests and responses, automatically generating JSON schemas for Fastify.\n- **Swagger/OpenAPI**: Interactive API documentation is automatically generated.\n- **Type-Safe Config**: Environment variables are strictly typed and validated using `env-var`.\n- **Docker Ready**: Includes production-optimized Dockerfile and docker-ignore settings.\n\n---\n\n## Folder Structure\n\n```text\n.\n├── public/          # Publicly served static assets\n├── src/\n│   ├── common/      # Shared utilities (logger, helpers)\n│   ├── modules/     # Domain-specific modules (e.g., todos)\n│   │   └── todos/   # Example module structure\n│   ├── plugins/     # Global plugins (routes, swagger)\n│   ├── bootstrap.ts # Global plugin registrations\n│   ├── init.ts      # Pre-startup initialization\n│   ├── server.ts    # Fastify instance and server configuration\n│   └── main.ts      # Application entry point\n├── Dockerfile       # Production Docker setup\n├── package.json     # Dependencies and scripts\n└── tsconfig.json    # TypeScript configuration\n```\n\n---\n\n## Getting Started\n\n### 1. Clone the repository\n\n```bash\ngit clone https://github.com/jmrl23/fastify-template.git\ncd fastify-template\n```\n\n### 2. Install dependencies\n\n```bash\nyarn install\n```\n\n### 3. Run in development\n\n```bash\nyarn run start:dev\n```\n\n- Starts the server with `tsx watch` for hot-reloading.\n- Swagger UI available at `http://localhost:3001/documentation` (if PORT is 3001).\n\n### 4. Build and run\n\n```bash\nyarn run build\nyarn run start\n```\n\n---\n\n## Environment Variables\n\nConfiguration is managed in `src/common/env.ts`. Define these in a `.env` file:\n\n| Variable          | Description                                            | Default       |\n| :---------------- | :----------------------------------------------------- | :------------ |\n| `NODE_ENV`        | Environment mode (`development`, `test`, `production`) | `development` |\n| `PORT`            | Port to listen on                                      | `3001`        |\n| `TRUST_PROXY`     | Comma-separated list of trust proxies                  | `loopback`    |\n| `CORS_ORIGIN`     | Comma-separated list of allowed origins                | `undefined`   |\n| `SWAGGER_SERVERS` | Comma-separated list of urls                           | `undefined`   |\n\n---\n\n## Scripts\n\n| Script                | Description                                                     |\n| :-------------------- | :-------------------------------------------------------------- |\n| `yarn run start`      | Start server.                                                   |\n| `yarn run start:dev`  | Start server in development mode with watch mode and inspector. |\n| `yarn run start:prod` | Start server in production mode (`NODE_ENV=production`).        |\n| `yarn run build`      | Compile TypeScript to JavaScript.                               |\n| `yarn run test`       | Run tests using Jest.                                           |\n| `yarn run format`     | Format code with Prettier.                                      |\n| `yarn run lint`       | Lint code with ESLint.                                          |\n\n---\n\n## Architecture Highlights\n\n### Automatic Route Loading\n\nRoutes 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`.\n\nExample: `src/modules/todos/todos.route.ts` -\u003e `/todos`\n\n### Validation with Zod\n\nSchemas 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.\n\n---\n\n## Docker\n\nBuild and run the container:\n\n```bash\ndocker build -t fastify-app .\ndocker run -p 3001:3001 --env-file .env fastify-app\n```\n\n---\n\n## License\n\nThis project is licensed under the [**MIT License**](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjmrl23%2Ffastify-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjmrl23%2Ffastify-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjmrl23%2Ffastify-template/lists"}