burger-api

<div align="center"> <a href="https://burger-api.com"> <img src="https://github.com/user-attachments/assets/0d9b376e-1d89-479a-aa7f-e7ee3c6b2342" alt="BurgerAPI"/> </a> </div> [![Under Development](https://img.shields.io/badge/under%20development-red.svg)](https://github.com/isfhan/burger-api) [![License](https://img.shields.io/badge/license-MIT-blue.svg)](./packages/burger-api/LICENSE) [![Bun](https://img.shields.io/badge/Bun-1.2.20-black?logo=bun)](https://bun.sh) [![Version](https://img.shields.io/badge/version-0.9.7-green.svg)](https://github.com/isfhan/burger-api/releases) **burger-api** is a modern, open source API framework built on [Bun.js](https://bun.sh). It combines the simplicity of file-based routing with powerful features like built-in middleware, Zod-based schema validation, and automatic OpenAPI generation. Designed for high performance and ease-of-use, burger-api leverages Bun's native modules to deliver blazing-fast API responses while keeping your codebase clean and maintainable. **This project is under active development and should not be used in production yet.** ## 📚 Table of Contents - [Overview](#-overview) - [CLI Tool](#-cli-tool) - [Changelog](#-changelog) - [What's Coming Next](#-whats-coming-next) - [Contributing](#-contributing) - [License](#-license) ## 📖 Documentation For detailed documentation and examples, visit the [BurgerAPI official docs](https://burger-api.com/). ## 🚀 Overview burger-api is built to offer a robust developer experience through: - ⚡ **Bun-Native Performance:** Leverages Bun's high-performance HTTP server. - 📁 **File-Based Routing:** Automatically registers API routes from your file structure using a clear naming convention. - 🔄 **Middleware Architecture:** Supports both global and route-specific middleware. Simple, powerful middleware system with three return types: - `Response` - Stop here, send this response - `Function` - Transform the final response after handler runs - `undefined` - Continue to next middleware - ✅ **Type-Safe Validation:** Utilizes Zod for request validation, ensuring full type safety and automatic error reporting. - 📚 **Automatic OpenAPI Generation:** Generates a complete OpenAPI 3.0 specification directly from your routes and Zod schemas. - 🔍 **Swagger UI Integration:** Out-of-the-box Swagger UI endpoint for interactive API documentation. ## 🛠️ CLI Tool (Newly Added) burger-api comes with a powerful CLI tool that makes it easy to scaffold new projects and manage middleware. Install it globally to get started: ### Installation **Option 1: Bun Global Installation (Recommended if you have Bun installed)** ````bash # Global installation bun add -g @burger-api/cli ```` **Or use with bunx (No Installation Needed):** ````bash bunx @burger-api/cli create my-project ```` **Option 2: Standalone Executable (Alternative Installation Method)** **macOS, Linux, WSL:** ```bash curl -fsSL https://burger-api.com/install.sh | bash ``` **Windows PowerShell:** ```powershell irm https://burger-api.com/install.ps1 | iex ``` **Option 3: Manual Download (Alternative Installation Method)** 1. Download the executable for your platform from [GitHub Releases](https://github.com/isfhan/burger-api/releases/latest) 2. Add to PATH 3. Make executable (Linux/macOS): `chmod +x burger-api` **Verify Installation (To Check if the CLI is Installed Correctly)** ```bash burger-api --version ``` **Package Details:** - **npm package:** [`@burger-api/cli`](https://www.npmjs.com/package/@burger-api/cli) - **Requires:** Bun >=1.3.0 ### Quick Start ```bash # Create a new burger-api project burger-api create my-api # Navigate to your project cd my-api # Start development server bun run dev ``` ### Installing Middleware The CLI makes it easy to add production-ready middleware to your project. Browse available middleware and install them with a single command: ```bash # List all available middleware burger-api list # Add middleware to your project burger-api add cors logger rate-limiter ``` **Popular Middleware Available:** - **`cors`** - Cross-Origin Resource Sharing for handling cross-origin requests - **`logger`** - Request/response logging with detailed information - **`rate-limiter`** - Request rate limiting to prevent API abuse - **`jwt-auth`** - JWT authentication for securing your API endpoints - **`api-key-auth`** - API key authentication for server-to-server communication - **`compression`** - Response compression (gzip/deflate) to reduce bandwidth - **`security-headers`** - Security HTTP headers to protect against common attacks - **`cache`** - HTTP caching headers for improved performance - **`timeout`** - Request timeout to prevent long-running requests - **`body-size-limiter`** - Request body size limits to prevent large payload attacks After installing middleware, the CLI will show you exactly how to use it in your project. For more information, visit the [CLI documentation](../../packages/cli/README.md). ## 📣 Changelog ### Latest Version: 0.9.7 (May 16, 2026) - 🚀 Production builds work better and use the same route rules as development. - 📦 You can pass route lists into the server so production does not scan files. - 🧪 Example tests and test scripts are improved; run framework and CLI tests from the repo root. ### Previous Version: 0.7.0 (November 13, 2025) - ⚡ **Major Performance Improvements:** - middleware execution with specialized fast paths - AOT compilation with pre-computed middleware arrays - Zero runtime allocations (pre-allocated arrays) - Manual loop unrolling for 2-middleware case - Reduced code from ~110 to ~80 lines - 🎯 **Simplified Middleware System:** - Clearer return types: Response, Function, or undefined - Removed complex "around" middleware pattern - Dedicated fast paths for 0, 1, and 2 middlewares - Better JIT optimization - 📦 **Monorepo Structure:** - Converted to Bun workspace monorepo - Core framework in `packages/burger-api` - CLI tool in `packages/cli` (under development) - Ecosystem middleware at root level - 🔧 **Developer Experience:** - 100% backward compatible - Clearer documentation - Easier to understand codebase ### Previous Version: 0.5.2 (November 9, 2025) - 🔧 **Internal Improvements:** - Refactored wildcard parameter extraction logic into reusable utility functions - Added test suites and README files for all example projects ### Previous Version: 0.5.0 (November 1, 2025) - 🌟 **Feature:** Auto-injected OPTIONS handler for CORS preflight: - Automatically injects an OPTIONS handler for CORS preflight when needed - Only injects if the route defines any preflight-triggering methods and lacks an OPTIONS handler - Injects a minimal OPTIONS handler that returns a 204 No Content response - Works for all HTTP methods that trigger CORS preflight (POST, PUT, DELETE, PATCH) - Does not inject if the route already has an OPTIONS handler - 🌟 **Feature:** Improved response handling in middleware (after middlewares): - After middlewares now run even if the current middleware already returned a response - After middlewares run in reverse order to make changing the response easier and to help with CORS - 🐛 **Bug Fix:** Fixed TypeScript type resolution for package consumers: - Users now get full IntelliSense, autocomplete, and type safety out of the box ### Previous Version: 0.4.0 (October 21, 2025) - 🌟 **Feature:** Wildcard Routes: - Added wildcard routes using `[...]` folder name - matches any path after it - Create routes that handle multiple path segments automatically - Access all matched path parts through `wildcardParams` in your request - Routes are matched in order: exact paths first, then dynamic routes (like `[id]`), then wildcards last - Works inside dynamic routes too (example: `/api/users/[userId]/[...]`) - View wildcard routes in OpenAPI docs and Swagger UI ### Previous Version: 0.3.0 (August 15, 2025) - 🌟 **Feature:** Updated Zod to version 4: - Updated Zod version from 3.x to 4.x - Updated built-in request validation middleware to use Zod 4 - Updated and better request validation middleware error handling - Removed Zod-to-json-schema dependency and use Zod 4 directly For a complete list of changes, please check the [Changelog](./packages/burger-api/CHANGELOG.md) file. ## 🎯 What's Coming Next? We're actively enhancing burger-api with powerful new features Stay tuned for updates as we continue to build and improve burger-api! We're committed to making it the best API framework for Bun.js. ## 🤝 Contributing We welcome contributions from the community! If you have suggestions or improvements, please open an issue or submit a pull request. Let's build something amazing together. ## 📄 License This project is licensed under the MIT License - see the [LICENSE](./packages/burger-api/LICENSE) file for details. The MIT License is a permissive license that is short and to the point. It lets people do anything they want with your code as long as they provide attribution back to you and don't hold you liable.