{"id":36965213,"url":"https://github.com/dangaogit/bun-server","last_synced_at":"2026-03-17T05:30:47.269Z","repository":{"id":328136457,"uuid":"1109708992","full_name":"dangaogit/bun-server","owner":"dangaogit","description":"A high-performance, decorator-driven DI web framework running on Bun Runtime.","archived":false,"fork":false,"pushed_at":"2026-02-28T03:27:50.000Z","size":1498,"stargazers_count":2,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-28T11:47:26.496Z","etag":null,"topics":["ai","ai-agents","aop","bun","bun-server","ddd","di-framework","framework","mirror-server","monorepo","nacos","node","server","typescript","web","web-server"],"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/dangaogit.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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-04T07:11:32.000Z","updated_at":"2026-02-28T03:27:13.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/dangaogit/bun-server","commit_stats":null,"previous_names":["dangaogit/bun-server"],"tags_count":26,"template":false,"template_full_name":null,"purl":"pkg:github/dangaogit/bun-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dangaogit%2Fbun-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dangaogit%2Fbun-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dangaogit%2Fbun-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dangaogit%2Fbun-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dangaogit","download_url":"https://codeload.github.com/dangaogit/bun-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dangaogit%2Fbun-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30286548,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-09T02:57:19.223Z","status":"ssl_error","status_checked_at":"2026-03-09T02:56:26.373Z","response_time":61,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["ai","ai-agents","aop","bun","bun-server","ddd","di-framework","framework","mirror-server","monorepo","nacos","node","server","typescript","web","web-server"],"created_at":"2026-01-13T19:55:19.029Z","updated_at":"2026-03-17T05:30:47.256Z","avatar_url":"https://github.com/dangaogit.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Bun Server\n\n\u003e Examples: `https://disb-examples-{example-name}.dangaogm.com`\n\n[![bun](https://img.shields.io/badge/Bun-1.3.10%2B-000?logo=bun\u0026logoColor=fff)](https://bun.sh/)\n[![typescript](https://img.shields.io/badge/TypeScript-5.x-3178C6?logo=typescript\u0026logoColor=fff)](https://www.typescriptlang.org/)\n[![license](https://img.shields.io/badge/license-MIT-blue)](#license)\n\n\u003e A high-performance, decorator-driven DI web framework running on Bun Runtime.\n\n- [Why Bun Server](#why-@dangao/bun-server)\n- [Features](#features)\n- [Architecture](#architecture)\n- [Getting Started](#getting-started)\n- [Examples \u0026 Extensions](#examples--extensions)\n- [Benchmark Suite](#benchmark-suite)\n- [Docs \u0026 Localization](#docs--localization)\n- [Roadmap](#roadmap)\n- [AI-Assisted Development](#ai-assisted-development)\n- [Engineering Guidelines](#engineering-guidelines)\n- [Contributing](#contributing)\n- [License](#license)\n- [Other Languages](#other-languages)\n\n## Why Bun Server\n\n- **Native Bun**: built on top of `Bun.serve`, embracing native TS, fast I/O and\n  the Bun package manager.\n- **Modern DX**: decorators, metadata and DI everywhere — controllers, services,\n  middleware, validation.\n- **Lightweight yet extensible**: modular DI + extension layer + logging\n  provider that scales from MVP to enterprise.\n- **Well-tested**: unit, integration, stress and benchmark suites ship with the\n  repo.\n- **AI-friendly**: source code and tests are included in the npm package,\n  enabling AI tools (like Cursor) to provide better code analysis, suggestions,\n  and understanding of the framework internals.\n\n## Features\n\n- 🚀 **Fast HTTP stack** powered by Bun with `Application`, `Router`, `Context`\n  and `ResponseBuilder` helpers.\n- 🧩 **Dependency injection container** with `@Injectable`, `@Inject`, module\n  metadata, lifecycle management and cached dependency plans.\n- 🗄️ **Database v2** with `db` proxy, route-level pool/session strategy,\n  multi-tenant manager and unified transactions.\n- 🧵 **Middleware pipeline** with global/class/method scopes plus built-ins\n  (logging, error, CORS, upload, static, ...).\n- ✅ **Input validation** via decorators and `ValidationError` integration.\n- 📡 **WebSocket gateways** with `@WebSocketGateway`, `@OnMessage`, etc.\n- 📚 **Docs \u0026 samples** including multi-language docs, benchmark scripts and\n  best practices.\n- 🧪 **Testing module** with `Test.createTestingModule()`, provider override,\n  and built-in HTTP test client.\n- 🔄 **Lifecycle hooks** — `OnModuleInit`, `OnModuleDestroy`,\n  `OnApplicationBootstrap`, `OnApplicationShutdown`.\n- ⚡ **Async module config** — `forRootAsync()` with factory injection on\n  ConfigModule, DatabaseModule, CacheModule and more.\n- 🔌 **Type-safe client generation** — extract route manifests and create\n  typed API clients from controller metadata.\n- 🎨 **Decorator composition** — `applyDecorators()` to merge multiple\n  decorators into one reusable decorator.\n- 📊 **Built-in dashboard** — `DashboardModule` provides a zero-dependency\n  monitoring web UI with system info, routes and health status.\n- 🐛 **Request replay / debug** — `DebugModule` records requests in a ring\n  buffer with a debug UI for inspection and replay.\n- 🖥️ **Zero-config cluster** — `ClusterManager` auto-spawns reusePort\n  workers matching CPU core count.\n\n## AI Modules (v2.0.0)\n\n9 official AI modules for building production-grade LLM applications. All providers use Bun's native `fetch()` — zero external SDK dependencies.\n\n| Module | Purpose |\n|--------|---------|\n| `AiModule` | LLM unified access (OpenAI, Claude, Gemini, Ollama) + Tool Calling + streaming |\n| `ConversationModule` | Multi-turn conversation memory (Memory/Redis/Database stores) |\n| `PromptModule` | Reusable prompt templates with `{{variable}}` interpolation and versioning |\n| `EmbeddingModule` | Text embedding generation (OpenAI, Ollama) |\n| `VectorStoreModule` | Vector similarity search (Memory, Pinecone, Qdrant) |\n| `RagModule` | Full RAG pipeline: ingest → chunk → embed → retrieve |\n| `McpModule` | MCP protocol server (JSON-RPC 2.0, SSE transport) |\n| `AiGuardModule` | PII detection, prompt injection detection, content moderation |\n\n```typescript\nimport { AiModule, OllamaProvider, AI_SERVICE_TOKEN, AiService } from '@dangao/bun-server';\n\nAiModule.forRoot({\n  providers: [{ name: 'ollama', provider: OllamaProvider, config: {}, default: true }],\n  fallback: true,\n});\n\n@Injectable()\nclass ChatService {\n  constructor(@Inject(AI_SERVICE_TOKEN) private ai: AiService) {}\n  chat(message: string) { return this.ai.complete({ messages: [{ role: 'user', content: message }] }); }\n}\n```\n\nSee [docs/ai.md](docs/ai.md) for the complete AI modules guide and [examples/05-ai/](examples/05-ai/) for working examples including the [AI Platform MVP Demo](examples/05-ai/ai-platform-mvp/).\n\n## Architecture\n\n### Request Lifecycle\n\nThe following diagram shows the complete request processing flow:\n\n```\nHTTP Request\n    ↓\n┌─────────────────────────────────────┐\n│         Middleware Pipeline         │  ← Global → Module → Controller → Method\n│  (Logger, CORS, RateLimit, etc.)    │\n└─────────────────────────────────────┘\n    ↓\n┌─────────────────────────────────────┐\n│         Security Filter             │  ← Authentication / Authorization\n│   (JWT, OAuth2, Role Check)         │\n└─────────────────────────────────────┘\n    ↓\n┌─────────────────────────────────────┐\n│         Router Matching             │  ← Path, Method, Params\n│   (Static → Dynamic → Wildcard)     │\n└─────────────────────────────────────┘\n    ↓\n┌─────────────────────────────────────┐\n│       Interceptors (Pre)            │  ← Global → Controller → Method\n│   (Cache, Log, Transform)           │\n└─────────────────────────────────────┘\n    ↓\n┌─────────────────────────────────────┐\n│       Parameter Binding             │  ← @Body, @Query, @Param, @Header\n│       + Validation                  │  ← @Validate, IsString, IsEmail...\n└─────────────────────────────────────┘\n    ↓\n┌─────────────────────────────────────┐\n│       Controller Method             │  ← Business Logic Execution\n│   (with DI injected services)       │\n└─────────────────────────────────────┘\n    ↓\n┌─────────────────────────────────────┐\n│       Interceptors (Post)           │  ← Method → Controller → Global\n│   (Response Transform)              │\n└─────────────────────────────────────┘\n    ↓\n┌─────────────────────────────────────┐\n│       Exception Filter              │  ← Exception Handling\n│   (HttpException, ValidationError)  │\n└─────────────────────────────────────┘\n    ↓\nHTTP Response\n```\n\n**Execution Order**: Middleware → Security → Router → Interceptors(Pre) →\nValidation → Handler → Interceptors(Post) → Exception Filter\n\n### Module System\n\n```\nApplication\n    │\n    ├── ModuleRegistry\n    │   │\n    │   ├── ConfigModule (Configuration)\n    │   ├── LoggerModule (Logging)\n    │   ├── SecurityModule (Authentication)\n    │   │   └── auth/ (JWT, OAuth2)\n    │   ├── SwaggerModule (API Docs)\n    │   ├── CacheModule (Caching)\n    │   ├── DatabaseModule (Database)\n    │   │   └── ORM (Entity, Repository, Transaction)\n    │   ├── QueueModule (Job Queue)\n    │   ├── SessionModule (Session)\n    │   ├── MetricsModule (Metrics)\n    │   ├── HealthModule (Health Check)\n    │   └── Microservice/\n    │       ├── ConfigCenterModule\n    │       ├── ServiceRegistryModule\n    │       ├── ServiceClient\n    │       ├── Governance (Circuit Breaker/Rate Limit/Retry)\n    │       └── Tracing\n    │\n    ├── ControllerRegistry\n    │   └── All module controllers\n    │\n    ├── WebSocketGatewayRegistry\n    │   └── WebSocket gateways\n    │\n    └── InterceptorRegistry\n        └── Interceptor registry\n```\n\n### DI Container\n\n```\nContainer\n    │\n    ├── providers (Map\u003ctoken, ProviderConfig\u003e)\n    │   ├── Singleton (shared globally)\n    │   ├── Transient (new instance per resolve)\n    │   └── Scoped (per-request instance)\n    │\n    ├── singletons (singleton instance cache)\n    │\n    ├── scopedInstances (WeakMap, request-level cache)\n    │\n    ├── dependencyPlans (dependency resolution plan cache)\n    │\n    └── postProcessors (instance post-processors)\n```\n\nFor detailed lifecycle documentation, see\n[Request Lifecycle](./docs/request-lifecycle.md).\n\n## Getting Started\n\n### Requirements\n\n- Bun \u003e= `1.3.10`\n\n### TypeScript Configuration ⚠️\n\n**Critical**: Ensure your `tsconfig.json` includes these decorator settings:\n\n```json\n{\n  \"compilerOptions\": {\n    \"emitDecoratorMetadata\": true,\n    \"experimentalDecorators\": true\n  }\n}\n```\n\nWithout these, dependency injection will fail (injected services will be\n`undefined`). See\n[Troubleshooting Guide](./docs/troubleshooting.md#-critical-injected-dependencies-are-undefined)\nfor details.\n\n### Install\n\n```bash\nbun install\n```\n\n### Hello World\n\n```ts\nimport { Application, Controller, GET, Injectable } from \"@dangao/bun-server\";\n\n@Injectable()\nclass HealthService {\n  public ping() {\n    return { status: \"ok\" };\n  }\n}\n\n@Controller(\"/api\")\nclass HealthController {\n  public constructor(private readonly service: HealthService) {}\n\n  @GET(\"/health\")\n  public check() {\n    return this.service.ping();\n  }\n}\n\nconst app = new Application({ port: 3100 });\napp.getContainer().register(HealthService);\napp.registerController(HealthController);\napp.listen();\n```\n\n### Useful scripts\n\n```bash\nbun --cwd=packages/bun-server test\nbun --cwd=packages/bun-server run bench\nbun --cwd=packages/bun-server run bench:router\nbun --cwd=packages/bun-server run bench:di\n```\n\n\u003e Running `bun test` from the repo root fails because Bun only scans the current\n\u003e workspace. Use the commands above or `cd packages/bun-server` first.\n\n### Advanced Example: Interface + Symbol + Module\n\nThis example demonstrates using interfaces with Symbol tokens and module-based\ndependency injection:\n\n```ts\nimport {\n  Application,\n  Body,\n  CONFIG_SERVICE_TOKEN,\n  ConfigModule,\n  ConfigService,\n  Controller,\n  GET,\n  Inject,\n  Injectable,\n  Module,\n  Param,\n  POST,\n} from \"@dangao/bun-server\";\n\n// Define service interface\ninterface UserService {\n  find(id: string): Promise\u003c{ id: string; name: string } | undefined\u003e;\n  create(name: string): { id: string; name: string };\n}\n\n// Create Symbol token for DI\nconst UserService = Symbol(\"UserService\");\n\n// Implement the interface\n@Injectable()\nclass UserServiceImpl implements UserService {\n  private readonly users = new Map\u003cstring, { id: string; name: string }\u003e([\n    [\"1\", { id: \"1\", name: \"Alice\" }],\n  ]);\n\n  public async find(id: string) {\n    return this.users.get(id);\n  }\n\n  public create(name: string) {\n    const id = String(this.users.size + 1);\n    const user = { id, name };\n    this.users.set(id, user);\n    return user;\n  }\n}\n\n@Controller(\"/api/users\")\nclass UserController {\n  public constructor(\n    private readonly service: UserService,\n    @Inject(CONFIG_SERVICE_TOKEN) private readonly config: ConfigService,\n  ) {}\n\n  @GET(\"/:id\")\n  public async getUser(@Param(\"id\") id: string) {\n    const user = await this.service.find(id);\n    if (!user) {\n      return { error: \"Not Found\" };\n    }\n    return user;\n  }\n\n  @POST(\"/\")\n  public createUser(@Body(\"name\") name: string) {\n    return this.service.create(name);\n  }\n}\n\n// Define module with Symbol-based provider\n@Module({\n  controllers: [UserController],\n  providers: [\n    {\n      provide: UserService,\n      useClass: UserServiceImpl,\n    },\n  ],\n  exports: [UserService],\n})\nclass UserModule {}\n\n// Configure modules\nConfigModule.forRoot({\n  defaultConfig: {\n    app: {\n      name: \"Advanced App\",\n      port: 3100,\n    },\n  },\n});\n\n// Register module and start application\n@Module({\n  imports: [ConfigModule],\n  controllers: [UserController],\n  providers: [\n    {\n      provide: UserService,\n      useClass: UserServiceImpl,\n    },\n  ],\n})\nclass AppModule {}\n\nconst app = new Application({ port: 3100 });\napp.registerModule(AppModule);\napp.listen();\n```\n\n**Key points:**\n\n- **Interface-based design**: Define contracts with TypeScript interfaces\n- **Symbol tokens**: Use `Symbol()` for type-safe dependency injection tokens\n- **Module providers**: Register providers using\n  `provide: Symbol, useClass: Implementation`\n- **Type-safe injection**: Inject services using `@Inject(Symbol)` with\n  interface types\n\n## Examples \u0026 Extensions\n\n### 📚 Organized Examples\n\nExamples are organized by difficulty and feature category:\n\n- **[Quick Start](./examples/00-quick-start/)** - Get started in 5 minutes\n  - `01-hello-world.ts` - Minimal example (5 lines)\n  - `02-basic-routing.ts` - HTTP methods and route parameters\n  - `03-dependency-injection.ts` - DI basics with services\n\n- **[Core Features](./examples/01-core-features/)** - Deep dive into framework\n  mechanics\n  - `basic-app.ts` - DI + Logger + Swagger + Config integration\n  - `multi-module-app.ts` - Module dependencies and organization\n  - `context-scope-app.ts` - Request scoping and ContextService\n  - `full-app.ts` - Validation, uploads, static files, WebSocket\n  - `lifecycle-app.ts` - Lifecycle hooks (OnModuleInit, OnModuleDestroy, etc.)\n  - `async-config-app.ts` - Async module config with `forRootAsync()`\n  - `idle-timeout-app.ts` - Global and route-level idleTimeout\n\n- **[Official Modules](./examples/02-official-modules/)** - Ready-to-use modules\n  - `auth-app.ts` - JWT + OAuth2 authentication (with Web UI)\n  - `session-app.ts` - Session management\n  - `database-app.ts` - Database connection and queries\n  - `nacos-auto-register-app.ts` - Nacos autoRegister switch example\n  - `orm-app.ts` - Entity + Repository pattern\n  - `cache-app.ts` - Caching with decorators\n  - `queue-app.ts` - Task queues and Cron jobs\n  - `dashboard-app.ts` - Built-in monitoring dashboard (with Web UI)\n\n- **[Advanced](./examples/03-advanced/)** - Custom framework extensions\n  - `custom-decorator-app.ts` - Create custom decorators\n  - `apply-decorators-app.ts` - Decorator composition with `applyDecorators()`\n  - `testing-app.ts` - TestingModule with mock providers and HTTP client\n  - `type-safe-client-app.ts` - Type-safe API client from controller metadata\n  - `debug-app.ts` - Request recording and replay (with Web UI)\n  - `websocket-chat-app.ts` - Complete WebSocket chat with rooms (with Web UI)\n  - `microservice-app.ts` - Microservices architecture\n\n- **[Real World](./examples/04-real-world/)** - Production-ready examples\n  - `database-test-app.ts` - Database connection tester (Web UI)\n  - `perf/app.ts` - Performance benchmarking\n  - `perf/cluster-app.ts` - Zero-config cluster with `ClusterManager`\n\n### 🔑 Symbol + Interface Pattern\n\nThis framework features a unique **Symbol + Interface co-naming pattern** that\nsolves TypeScript's type erasure problem:\n\n```typescript\n// 1. Define interface and Symbol with same name\ninterface UserService {\n  find(id: string): Promise\u003cUser\u003e;\n}\nconst UserService = Symbol('UserService');\n\n// 2. Implement interface\n@Injectable()\nclass UserServiceImpl implements UserService {\n  async find(id: string) { ... }\n}\n\n// 3. Register with Symbol token\n@Module({\n  providers: [{\n    provide: UserService,      // Symbol token\n    useClass: UserServiceImpl, // Implementation\n  }],\n})\n\n// 4. Inject with type safety\nconstructor(private readonly userService: UserService) {}\n```\n\n**Key**: Import as `import { UserService }` (not `import type { UserService }`).\n\nSee [Symbol + Interface Pattern Guide](./docs/symbol-interface-pattern.md) for\ndetails.\n\n### 🔌 Extensions\n\n- `packages/bun-server/src/extensions/`: Official extensions (e.g.\n  `LoggerExtension`) for plugging in external capabilities.\n\n### 📖 Complete Example Index\n\nSee [examples/README.md](./examples/README.md) for the complete catalog with\nlearning paths, difficulty ratings, and usage scenarios.\n\n## Benchmark Suite\n\n### Internal Micro-benchmarks\n\n`PerformanceHarness` \u0026 `StressTester` based benchmarks:\n\n| Script            | Description                                                           |\n| ----------------- | --------------------------------------------------------------------- |\n| `router.bench.ts` | static/dynamic route hits, `router.handle` and stress runs            |\n| `di.bench.ts`     | singleton vs factory resolves, nested dependencies, concurrent stress |\n\n```bash\nbun benchmark/router.bench.ts\nbun benchmark/di.bench.ts\n```\n\n### Framework Comparison (bun-server vs Express vs NestJS)\n\nReal HTTP load testing with [wrk](https://github.com/wg/wrk), comparing\nbun-server against Express 5 and NestJS 11. All frameworks run on the same Bun\nruntime to isolate framework overhead.\n\n**Prerequisites:** wrk (`brew install wrk` / `apt install wrk`). The script\nautomatically raises `ulimit -n` to 10240 for child processes.\n\n```bash\nbun benchmark/run-wrk-compare.ts        # full comparison (3 tiers)\nTIER=0 bun benchmark/run-wrk-compare.ts  # Light tier only\nbun benchmark/run-wrk.ts                 # bun-server only (3 tiers)\n```\n\n\u003e **Environment:** Apple M2 Pro (8P + 4E cores) / darwin arm64 / Bun 1.3.10\n\n#### Req/Sec (Light: -t2 -c50 -d10s)\n\n| Endpoint              | bun-server   | Express  | NestJS   |\n|-----------------------|--------------|----------|----------|\n| GET /ping             | **31.41k**   | 30.01k   | 26.52k   |\n| GET /json             | **28.22k**   | 25.99k   | 23.64k   |\n| GET /users/:id        | **30.88k**   | 29.91k   | 25.62k   |\n| GET /search?q=        | **29.96k**   | 28.70k   | 25.17k   |\n| POST /users           | **27.65k**   | 21.37k   | 19.38k   |\n| POST /users/validated | **26.60k**   | 21.28k   | 18.93k   |\n| GET /middleware        | **29.52k**   | 28.57k   | 24.69k   |\n| GET /headers          | **30.98k**   | 29.57k   | 26.43k   |\n| GET /io               | **21.37k**   | 19.46k   | 18.49k   |\n\nZero errors across all frameworks and tiers. See the full report for Medium and\nHeavy tier results.\n\n\u003e 📊 Full comparison report (3 tiers, latency breakdown, per-framework\n\u003e details): [`benchmark/REPORT_COMPARE.md`](./benchmark/REPORT_COMPARE.md)\n\u003e\n\u003e 📋 Single-framework detailed report:\n\u003e [`benchmark/REPORT.md`](./benchmark/REPORT.md)\n\n### Multi-process Benchmark (reusePort, Linux only)\n\n```bash\nbun benchmark/run-wrk-cluster.ts          # default: 1 worker per CPU core\nWORKERS=4 bun benchmark/run-wrk-cluster.ts\n```\n\nSpawns N workers sharing the same port via `SO_REUSEPORT`. The kernel\ndistributes connections across processes. Report saved to\n`benchmark/REPORT_CLUSTER.md`. Note: `reusePort` only works on **Linux**;\nmacOS/Windows silently ignore it.\n\n## Docs \u0026 Localization\n\n- **English** (default): `docs/api.md`, `docs/guide.md`,\n  `docs/best-practices.md`, `docs/migration.md`, `docs/extensions.md`,\n  `docs/deployment.md`, `docs/performance.md`, `docs/troubleshooting.md`,\n  `docs/error-handling.md`, `docs/request-lifecycle.md`.\n- **Chinese**: mirrored under `docs/zh/`. If something is missing, please fall\n  back to the English source.\n- **Skills \u0026 Troubleshooting**:\n  - In-repo troubleshooting cases: [`skills/`](./skills/README.md)\n  - Agent skills repository: [`bun-server-skills`](https://github.com/dangaogit/bun-server-skills)\n  - Install for Cursor (pick one):\n    ```bash\n    # bun\n    bunx skills add https://github.com/dangaogit/bun-server-skills --skill bun-server-best-practices\n    # npx\n    npx skills add https://github.com/dangaogit/bun-server-skills --skill bun-server-best-practices\n    # pnpm\n    pnpm dlx skills add https://github.com/dangaogit/bun-server-skills --skill bun-server-best-practices\n    # yarn\n    yarn dlx skills add https://github.com/dangaogit/bun-server-skills --skill bun-server-best-practices\n    # git (manual)\n    mkdir -p ~/.cursor/skills \u0026\u0026 git clone https://github.com/dangaogit/bun-server-skills.git ~/.cursor/skills/bun-server-skills\n    ```\n\n## Roadmap\n\nRelease history and changelogs are tracked in the [`.changelog/`](./.changelog/)\ndirectory.\n\n## AI-Assisted Development\n\nBun Server is designed to work seamlessly with AI coding assistants like Cursor,\nGitHub Copilot, and others. The framework includes source code and tests in the\nnpm package distribution, enabling AI tools to:\n\n- **Understand framework internals**: AI can analyze the actual implementation\n  code, not just type definitions, providing more accurate suggestions.\n- **Provide context-aware help**: When you ask about framework features, AI can\n  reference the actual source code to give precise answers.\n- **Suggest best practices**: AI can learn from the framework's patterns and\n  suggest similar approaches in your code.\n- **Debug more effectively**: AI can trace through the framework code to help\n  diagnose issues.\n\n### Best Practices for AI-Assisted Development\n\n1. **Reference framework source**: When working with Bun Server, AI tools can\n   access the source code at `node_modules/@dangao/bun-server/src/` to\n   understand implementation details.\n\n2. **Use type hints**: The framework provides comprehensive TypeScript types.\n   Leverage these in your code to help AI understand your intent better.\n\n3. **Follow framework patterns**: The included source code serves as a reference\n   for framework patterns. Ask AI to suggest code that follows similar patterns.\n\n4. **Leverage test examples**: The included test files demonstrate usage\n   patterns and edge cases. Reference these when asking AI for implementation\n   help.\n\n5. **Ask specific questions**: Since AI can access the framework source, you can\n   ask specific questions like \"How does the DI container resolve dependencies?\"\n   and get accurate answers based on the actual code.\n\n## Engineering Guidelines\n\n- Comments \u0026 log messages **must be in English** to keep the codebase\n  international-friendly.\n- Documentation defaults to English; Chinese copies live in `docs/zh/`.\n- Benchmarks belong to `benchmark/` and should run inside Bun environments.\n\n## Contributing\n\n1. Fork \u0026 create a feature branch.\n2. Run `bun test` (and relevant benchmarks if the change affects performance).\n3. Submit a PR with a clear description and test evidence.\n\nIssues and discussions are welcome for new ideas or perf bottlenecks.\n\n## License\n\nReleased under the [MIT License](./LICENSE).\n\n## Other Languages\n\n- [中文 README](./README_ZH.md)\n\nEnjoy building on Bun Server!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdangaogit%2Fbun-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdangaogit%2Fbun-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdangaogit%2Fbun-server/lists"}