{"id":31287976,"url":"https://github.com/hpbyte/hono-starter","last_synced_at":"2026-04-06T09:33:40.613Z","repository":{"id":315696890,"uuid":"1060522932","full_name":"hpbyte/hono-starter","owner":"hpbyte","description":"🚀 Enterprise-ready Hono starter with NestJS-style architecture, dependency injection, and PostgreSQL integration - built for Bun runtime","archived":false,"fork":false,"pushed_at":"2026-01-29T01:49:25.000Z","size":92,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-29T17:19:28.697Z","etag":null,"topics":["boilerplate","bunjs","dependency-injection","drizzle-orm","honojs","http-server","nestjs","postgresql","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hpbyte.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-09-20T04:28:51.000Z","updated_at":"2026-01-29T01:49:28.000Z","dependencies_parsed_at":null,"dependency_job_id":"ea231aee-0197-4f29-937e-851e03015bfa","html_url":"https://github.com/hpbyte/hono-starter","commit_stats":null,"previous_names":["hpbyte/hono-starter"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/hpbyte/hono-starter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hpbyte%2Fhono-starter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hpbyte%2Fhono-starter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hpbyte%2Fhono-starter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hpbyte%2Fhono-starter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hpbyte","download_url":"https://codeload.github.com/hpbyte/hono-starter/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hpbyte%2Fhono-starter/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31466629,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-06T08:36:52.050Z","status":"ssl_error","status_checked_at":"2026-04-06T08:36:51.267Z","response_time":112,"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":["boilerplate","bunjs","dependency-injection","drizzle-orm","honojs","http-server","nestjs","postgresql","typescript"],"created_at":"2025-09-24T11:39:08.537Z","updated_at":"2026-04-06T09:33:40.608Z","avatar_url":"https://github.com/hpbyte.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Hono Starter\n\nA starter kit for building Bun + Hono services with a [NestJS](https://nestjs.com/)-like structure, Dependency injection is baked in, and [PostgreSQL](https://www.postgresql.org/) via [Drizzle ORM](https://orm.drizzle.team/).\n\n## Why?\n\nHono is really great but due to its unopinionated nature, there's a lack of guidance in terms of application structure and best practices for enterprise applications.\n\nThis aims to provide as a starting point for enterprise apps and contains ready-to-use base tooling so you can focus on features instead of wiring from scratch.\n\n## Stack\n\n- ⚡ **Bun + Hono** for fast server-side rendering and routing\n- 💉 **Inversify DI** with Nest-like modules, controllers, and injectable services\n- 🗄️ **Drizzle ORM** already configured for PostgreSQL\n- 🔄 **Background runtime** that auto-discovers jobs and handles lifecycle\n- 🛡️ **Zod** for schema validation and type-safe configuration\n- 🧱 **Layered structure** (`core`, `modules`, `shared`) for better maintainability\n- 🧪 **TypeScript-first** with ESLint, Prettier, and `tsc` ready to run\n\n## Project Structure\n\n```\nsrc/\n├── bootstrap.ts           # Bootstraps the DI container, server, and runtime\n├── core/                  # Foundation services used across the app\n│   ├── config/            # Typed config loading \u0026 validation (Zod)\n│   ├── database/          # Drizzle client, config, migrations output\n│   ├── di/                # Module decorator(s) + container factory\n│   └── http/              # Hono server wrapper with lifecycle helpers\n├── modules/               # Feature modules (controllers, services, jobs)\n│   ├── background/        # Sample background job + runtime coordination\n│   ├── health/            # `/health` endpoint and status checks\n│   └── user/              # `/users` example using Drizzle query API\n└── shared/                # Reusable interfaces and type contracts\n```\n\n## Getting Started\n\n### Prerequisites\n\n- [Bun](https://bun.sh) `\u003e=1.2`\n- Docker \u0026 Docker Compose (for local PostgreSQL)\n\n### Installation\n\n```bash\nbun install\ncp .env.example .env\n```\n\nUpdate `.env` (see [Environment Variables](#environment-variables)).\n\n### Run the stack locally\n\n```bash\ndocker compose up -d db       # start postgres\nbun run db:migrate            # apply pending migrations\nbun run dev                   # start Hono with hot reload on http://localhost:3000\n```\n\n### Running with Docker\n\n```bash\ndocker compose up --build -d\n```\n\n## Architecture Notes\n\n- **Dependency Injection**: `@Module({...})` ties together providers, controllers, and background jobs. `bootstrap.ts` collects modules, builds an Inversify container, and resolves the `HttpServer` and `BackgroundRuntime` singletons.\n- **HTTP Controllers**: Anything bound as a controller is auto-registered on the Hono app when the server starts. Implement `HttpController.registerRoutes(app)` to declare routes.\n- **Background Jobs**: Implement `IBackgroundJob` (`id`, `start`, `stop`) and add the job class to a module's `backgroundJobs` array. The runtime starts every job on boot and stops them on shutdown.\n- **Graceful Shutdown**: `src/main.ts` listens for `SIGINT/SIGTERM`, stops jobs, and closes the HTTP server in order.\n- **Database Access**: Use the injected `DrizzleClient` (`drizzle.database`) for type-safe queries. Place schema files under `src/core/database/schema/` for Drizzle Kit to pick them up.\n\n## Environment Variables\n\n`src/core/config/config.schema.ts` validates configuration at startup. Provide these variables via `.env` or your environment:\n\n| Variable       | Required | Default | Description                  |\n| -------------- | -------- | ------- | ---------------------------- |\n| `DATABASE_URL` | ✅       | –       | PostgreSQL connection string |\n| `PORT`         | ❌       | `3000`  | HTTP server port             |\n\nExample `.env`:\n\n```env\nDATABASE_URL=postgresql://postgres:postgres@localhost:5432/hono\nPORT=3000\n```\n\n## Database Workflow\n\nDrizzle Kit is preconfigured via `src/core/database/drizzle.config.ts`.\n\n```bash\nbun run db:generate   # generate SQL migration files from schema changes\nbun run db:migrate    # apply migrations\nbun run db:push       # push schema directly (not recommended for prod)\nbun run db:studio     # open Drizzle Studio UI\n```\n\nPlace table definitions in `src/core/database/schema/` (e.g. `users.ts`). They are aggregated automatically when you run Drizzle commands.\n\n## Adding New Features\n\n### Create a module\n\n1. Create a directory under `src/modules/\u003cfeature\u003e`.\n2. Add services/controllers with the `@Injectable()` decorator.\n3. Register them in `\u003cfeature\u003e.module.ts` using `@Module({ providers, controllers, backgroundJobs })`.\n4. Export the module class and register it inside the `modules` array in `src/bootstrap.ts`.\n\n### Register an HTTP controller\n\n```ts\n@Injectable()\nexport class ExampleController implements HttpController {\n  constructor(private readonly svc: ExampleService) {}\n\n  registerRoutes(app: Hono) {\n    app.get('/example', () =\u003e this.svc.handle())\n  }\n}\n```\n\nOnce the module is included in `bootstrap.ts`, the controller routes are attached automatically.\n\n### Add a background job\n\n```ts\n@Injectable()\nexport class ReportJob implements IBackgroundJob {\n  readonly id = 'report-job'\n  constructor(private readonly handler: ReportHandler) {}\n  async start() {\n    await this.handler.run()\n  }\n  async stop() {\n    await this.handler.stop()\n  }\n}\n```\n\nAdd `ReportJob` to the module's `backgroundJobs` array to have it resolved and started.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhpbyte%2Fhono-starter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhpbyte%2Fhono-starter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhpbyte%2Fhono-starter/lists"}