Shokupan 🍞

A delightful, type-safe web framework for Bun

Built for Developer Experience Shokupan is designed to make building APIs delightful again. With zero-config defaults, instant startup times, and full type safety out of the box, you can focus on building your product, not configuring your framework.

[!CAUTION] Shokupan is still in alpha and is not guaranteed to be stable. Please use with caution. We will be adding more features and APIs in the future. Please file an issue if you find any bugs or have suggestions for improvement.

📚 Full documentation available at https://shokupan.dev

✨ Features

• 🎯 TypeScript First - End-to-end type safety with decorators and generics. No manual types needed.
• 🛠️ Zero Config - Works effectively out of the box. No complex setup or boilerplate.
• 🚀 Built for Bun - Native Bun performance with instant startup.
• 🔍 Debug Dashboard - Visual inspector for your routes, middleware, and request flow.
• 📝 Auto OpenAPI - Generate OpenAPI specs automatically from routes.
• 🔌 Rich Plugin System - CORS, Sessions, Auth, Validation, Rate Limiting, and more.
• 🌐 Flexible Routing - Express-style routes or decorator-based controllers.
• 🔀 Express Compatible - Works with Express middleware patterns.
• 📊 Built-in Telemetry - OpenTelemetry instrumentation out of the box.
• 🔐 OAuth2 Support - GitHub, Google, Microsoft, Apple, Auth0, Okta.
• ✅ Multi-validator Support - Zod, Ajv, TypeBox, Valibot.
• 📚 OpenAPI Docs - Beautiful OpenAPI documentation with Scalar.
• ⏩ Short shift - Very simple migration from Express or NestJS to Shokupan.

🚀 Quick Start

Bun and TypeScript are recommended for Shokupan, though it also supports Node.js and standard JavaScript.

import { Shokupan, ScalarPlugin } from 'shokupan';
const app = new Shokupan();

app.get('/', (ctx) => ({ message: 'Hello, World!' }));
app.get('/hello', (ctx) => "world");

app.mount('/scalar', new ScalarPlugin({
    enableStaticAnalysis: true
}));

app.listen();

That's it! Your server is running at http://localhost:3000 🎉

💡 Core Concepts

Shokupan provides a familiar yet modern API.

• Routing: Express-style routing (app.get, app.post) with a clean, intuitive API.
• Controllers: Decorator-based controllers (@Controller, @Get) for structured applications.
• Middleware: Koa-style async middleware for request processing and flow control.
• Context: A rich ctx object containing request, response, parameters, and shared state.
• Static Files: Serve static assets with ease.
• WebSockets: Native WebSocket handling and HTTP Bridge feature.

🔌 Plugins

Shokupan has a rich ecosystem of plugins.

| Plugin | Description | | :--- | :--- | | Dashboard | Visual dashboard for debugging and analysis. | | Error View | Beautiful, interactive error pages for development. | | CORS | Configure Cross-Origin Resource Sharing. | | Compression | Enable response compression (gzip, deflate, etc.). | | Rate Limiting | Protect your API from abuse. | | Security Headers | Add essential security headers (CSP, HSTS, etc.). | | Sessions | Session management with connect-style store support. | | Authentication | Built-in OAuth2 support (GitHub, Google, etc.). | | Validation | Validate requests with Zod, Ajv, TypeBox, or Valibot. | | Scalar (OpenAPI) | Beautiful, interactive API documentation. | | API Explorer | Built-in interactive documentation for your API. | | AsyncAPI | Generate and view documentation for WebSocket APIs. | | Cluster | Utilize multiple CPU cores for better performance. | | GraphQL | Support for Apollo Server and GraphQL Yoga. | | HTTP Server | Use standard Node.js HTTP/HTTPS servers. | | MCP Server | Expose your API as tools to LLMs. | | Socket.IO | Easy integration with Socket.IO. | | Proxy | Create reverse proxies. | | OpenAPI Validator | Validate requests against OpenAPI specs. | | Idempotency | Ensure safe retries for non-idempotent operations. |

🚀 Advanced Features

• Dependency Injection: Built-in container for managing dependencies.
• OpenAPI Generation: Auto-generate specs from your code.
• Sub-Requests: Make internal requests without HTTP overhead.
• OpenTelemetry: Built-in distributed tracing.
• Type Augmentation: Extend global types for type-safety.

📚 Guides & Reference

• Migration Guides: Detailed guides for migrating from Express, Koa, or NestJS.
• Testing: How to test your Shokupan application.
• Deployment: Deploying to Bun, Docker, and more.
• CLI Reference: Documentation for the Shokupan CLI.
• API Reference: Complete API documentation.
• Roadmap: Future plans and features.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Publish the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📝 License

MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Inspired by Express, Koa, NestJS, and Elysia
• Built for the amazing Bun runtime
• Powered by Arctic for OAuth2 support
• Tests and Benchmarks created with Antigravity

Made with ❤️ by the Shokupan team