https://github.com/rhinolabs/boilr
Convention-based framework for building type-safe Fastify APIs with file-based routing
https://github.com/rhinolabs/boilr
api fastify file-routing framework typescript zero-config
Last synced: 6 months ago
JSON representation
Convention-based framework for building type-safe Fastify APIs with file-based routing
- Host: GitHub
- URL: https://github.com/rhinolabs/boilr
- Owner: rhinolabs
- License: mit
- Created: 2025-05-20T16:53:01.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2025-06-01T05:16:54.000Z (10 months ago)
- Last Synced: 2025-06-14T08:51:41.908Z (10 months ago)
- Topics: api, fastify, file-routing, framework, typescript, zero-config
- Language: TypeScript
- Homepage:
- Size: 224 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# @rhinolabs/boilr
A convention-based web framework built on top of Fastify, designed to streamline API development through standardized patterns and built-in features. Developed by Rhinolabs Agency, it follows a "batteries included" philosophy while maintaining the performance benefits of the underlying Fastify engine.
## Monorepo Structure
This project is structured as a monorepo using pnpm workspaces:
- **`packages/boilr`** - Core framework package (`@rhinolabs/boilr`)
The main Boilr framework that provides convention-based routing, configuration, and plugin management around Fastify.
- **`packages/cli`** - Command-line interface (`@rhinolabs/boilr-cli`)
Tools for creating new projects, development server with hot-reload, building, and running Boilr applications.
- **`packages/typescript-example`** - Example application
A complete Todo CRUD API demonstrating Boilr's key features including type-safe validation and automatic documentation.
## Overview
Boilr simplifies building TypeScript APIs with Fastify by providing:
- **Convention-based file routing** with Next.js-style patterns
- **Integrated schema validation** using Zod with automatic type inference
- **Automatic OpenAPI documentation** generation from Zod schemas with error response schemas
- **Built-in error handling** with comprehensive exception classes and automatic HTTP status codes
- **Preconfigured security and performance optimizations** (CORS, Helmet, Rate limiting)
- **Developer-friendly tooling** for rapid development and deployment
- **TypeScript support** with full type inference and safety
## Getting Started
The fastest way to start using Boilr is with the CLI:
```bash
# Install the CLI globally
npm install -g @rhinolabs/boilr-cli
# Create a new project
boilr new my-api-project
# Move to the project directory
cd my-api-project
# Install dependencies
npm install
# Start development server with hot-reload
npm run dev
```
For more detailed instructions, check the documentation for each package:
- [`@rhinolabs/boilr`](./packages/boilr/README.md) - Core framework with routing and validation
- [`@rhinolabs/boilr-cli`](./packages/cli/README.md) - Command-line development tools
- [Example Application](./packages/typescript-example/README.md) - Complete Todo API sample
## Key Features
### 📁 Convention-Based File Routing
Routes are automatically created based on your file structure following Next.js conventions:
```
routes/
├── api/
│ ├── users/
│ │ ├── [id].ts → GET/PUT/DELETE /api/users/:id
│ │ └── index.ts → GET/POST /api/users
│ └── index.ts → GET /api
├── (admin)/ → Group routes without affecting URL structure
│ └── settings.ts → GET /settings
└── [...catchAll].ts → Wildcard route handling
```
### 🔍 Type-Safe Schema Validation
Define schemas and handlers with full TypeScript type safety using Zod:
```typescript
// routes/api/users/[id].ts
import { z } from 'zod';
import { type GetHandler, defineSchema, NotFoundException } from '@rhinolabs/boilr';
export const schema = defineSchema({
get: {
params: z.object({
id: z.string().transform(val => parseInt(val, 10))
}),
response: {
200: z.object({
id: z.number(),
name: z.string(),
email: z.string().email()
})
}
}
});
export const get: GetHandler = async (request) => {
const { id } = request.params; // Automatically typed as number
const user = await getUserById(id);
if (!user) {
throw new NotFoundException(`User with id ${id} not found`);
}
return user; // Return type automatically validated
};
```
### 🚨 Error Handling
Built-in HTTP exception classes with automatic error formatting and validation:
```typescript
import { NotFoundException, ValidationException } from '@rhinolabs/boilr';
// Throw structured HTTP exceptions
throw new NotFoundException('User not found');
// Handle validation errors automatically
throw new ValidationException('Invalid data', validationErrors);
```
### 🔐 Authentication System
Flexible multi-method authentication with automatic token extraction:
```typescript
// Configure authentication methods
const app = createApp({
auth: {
methods: [
{
name: 'jwt',
type: 'bearer', // Auto-extracts Bearer token
validator: async (request, token) => {
const user = await verifyJwtToken(token);
return { user };
}
}
]
}
});
// Apply to routes selectively
export const schema = defineSchema({
get: {
auth: ['jwt'], // or auth: true, or auth: false
response: { 200: UserSchema }
}
});
```
### 📚 Automatic API Documentation
Your OpenAPI/Swagger documentation is automatically generated from your Zod schemas, including automatic error response schemas:
```typescript
// server.ts
import { createApp } from '@rhinolabs/boilr';
const app = createApp({
server: {
port: 3000
},
plugins: {
swagger: {
info: {
title: 'My API',
description: 'API built with Boilr',
version: '1.0.0'
}
}
}
});
app.start(); // Documentation available at /docs
```
### 🛠️ Developer Experience
Powerful CLI tools for seamless development workflow:
```bash
# Create a new project with TypeScript template
boilr new my-api-project
# Start development server with hot-reload
boilr dev
# Build optimized production bundle
boilr build
# Start production server
boilr start
```
## Architecture
The framework leverages modern TypeScript features and provides:
- **Modular plugin system** - Extend functionality through Fastify's plugin ecosystem
- **Convention over configuration** - Sensible defaults with customization options
- **Performance focused** - Built on Fastify's high-performance foundation
- **Developer friendly** - Hot-reload, automatic documentation, type safety
## Development
```bash
# Clone the repository
git clone https://github.com/rhinolabs/boilr.git
cd boilr
# Install dependencies
pnpm install
# Build all packages
pnpm build
# Run development mode (watch all packages)
pnpm dev
```
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## License
MIT