{"id":14006818,"url":"https://github.com/marcosrjjunior/hono-boilerplate","last_synced_at":"2025-10-24T08:17:38.229Z","repository":{"id":201123961,"uuid":"699580128","full_name":"marcosrjjunior/hono-boilerplate","owner":"marcosrjjunior","description":"📝 hono boilerplate to run a typescript server using node, bun...","archived":false,"fork":false,"pushed_at":"2025-09-03T07:58:15.000Z","size":1050,"stargazers_count":64,"open_issues_count":0,"forks_count":4,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-13T04:57:30.437Z","etag":null,"topics":["api","bun","hono","honojs","javascript","kysely","nodejs","postgree","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/marcosrjjunior.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":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-10-02T23:05:27.000Z","updated_at":"2025-09-03T07:58:19.000Z","dependencies_parsed_at":null,"dependency_job_id":"87f4a43b-a7a2-4291-94df-a81b53733056","html_url":"https://github.com/marcosrjjunior/hono-boilerplate","commit_stats":null,"previous_names":["marcosrjjunior/hono-kysely-boilerplate"],"tags_count":19,"template":false,"template_full_name":null,"purl":"pkg:github/marcosrjjunior/hono-boilerplate","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcosrjjunior%2Fhono-boilerplate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcosrjjunior%2Fhono-boilerplate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcosrjjunior%2Fhono-boilerplate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcosrjjunior%2Fhono-boilerplate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/marcosrjjunior","download_url":"https://codeload.github.com/marcosrjjunior/hono-boilerplate/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcosrjjunior%2Fhono-boilerplate/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278314967,"owners_count":25966773,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-04T02:00:05.491Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["api","bun","hono","honojs","javascript","kysely","nodejs","postgree","typescript"],"created_at":"2024-08-10T10:01:39.422Z","updated_at":"2025-10-04T12:35:05.010Z","avatar_url":"https://github.com/marcosrjjunior.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# Hono Boilerplate\n\nBoilerplate for your typescript projects using [Hono](https://hono.dev).\n\n[Project Structure](#project-structure)  \n[Tech Stack](#tech-stack)  \n[Requirements](#requirements)  \n[Run Locally](#run-locally)  \n[Manage your database using migrations](#manage-your-database-using-migrations)  \n[Run test](#run-test)  \n[FAQ](#faq)  \n[Dependencies](#dependencies)  \n[Extras](#extras)\n\n## Project Structure\n\nThe main implementation is inside of the `/app` directory where it uses basic ts node implementation.\n\n```bash\n/src\n\n/app/cases: # Use cases of your application\n/app/repositories: # Repositories and interfaces used by the use cases\n/lib/db: # Database structure: migrations, seed, types\n/routes: # Routes and middlewares\n/tests:  # Integration tests\n\nnode.ts: # Initial file to run the project using Node\nbun.ts:  # Initial file to run the project using Bun\n```\n\n## Tech Stack\n\n**Geral:** [Hono](https://hono.dev), [Zod](https://zod.dev), Eslint  \n**Database:** [Kysely](https://kysely.dev) (queries, migrations, types)  \n**Test:** [Bun test](https://bun.sh/docs/cli/test)\n\n## Requirements\n\n[node.js v20+](https://nodejs.org/en) or [bun](https://bun.sh)  \n[nvm](https://github.com/nvm-sh/nvm#install--update-script) installed to manage node versions  \n[pnpm](https://pnpm.io) to manage dependencies(npm install -g pnpm)\n\n## Run Locally\n\n\u003cdetails\u003e\n\n\u003csummary\u003e📁 Setup your database\u003c/summary\u003e\n\nI recommend using [dbngin](https://dbngin.com) to spin up an local DB on your machine.\n\n\u003e [!NOTE]  \n\u003e If you prefer docker, you can use postgres service from [this docker compose](https://gist.github.com/marcosrjjunior/d5250416b5fe43d982f998c0b7744464)\n\nCreate your database\n\n```\nCREATE DATABASE project\n```\n\n\u003c/details\u003e\n\n#### **Update your environment variables**\n\nCreate a `.env` files from `.env.example` and populate the values.\n\n```\ncp .env.example .env\n```\n\n#### **Install your dependencies**\n\n\u003cdetails\u003e\n\n\u003csummary\u003eNodejs\u003c/summary\u003e\n\n```sh\nnvm use\npnpm install\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\n\u003csummary\u003eBun\u003c/summary\u003e\n\n```sh\nbun install --lockfile-only\n# Reference: https://bun.sh/docs/install/lockfile\n```\n\n\u003c/details\u003e\n\n#### **Run the project**\n\n\u003cdetails\u003e\n\n\u003csummary\u003eNodejs\u003c/summary\u003e\n\n```sh\npnpm node:dev or pnpm dev\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\n\u003csummary\u003eBun\u003c/summary\u003e\n\n```sh\npnpm bun:dev\n```\n\n\u003c/details\u003e\n\nFrom here you should be getting a server running on `http://localhost:3333`\n\n## Manage your database using migrations\n\nMigrations are currently defined under `lib/db/migrations`. An initial migration is already there as an example, adjust to meet your project requirements. [Reference](https://kysely.dev/docs/migrations)\n\nRun all migrations\n\n```sh\npnpm db:migrate:up\n```\n\n\u003e This command will perform the \"up\" function for all new migrations\n\nRollback previous migration\n\n```sh\npnpm db:migrate:down\n```\n\n\u003e This command will perform the \"down\" function from previous migration\n\nRun seed\n\n```sh\npnpm db:seed\n```\n\nReset migrations + run seed\n\n```sh\npnpm db:reset\n```\n\n#### How to write a migration\n\nTo make an update on the database you will need to create a migration\n\nRun the command\n\n```sh\npnpm db:migrate:create\n```\n\nThis will generate a new file under `/lib/db/migrations/DATE-initial.ts`\n\n- Rename the file to describe what the migration will do e.g `DATE-adding_phone_column_to_user.ts`\n\n- Functions **up** and **down** should work.\n\n##### DB types\n\nThis project uses [kysely-codegen](https://github.com/RobinBlomberg/kysely-codegen).\nAfter running the migration you can re-generate the types using\n\n```sh\npnpm db:generate:types\n```\n\n## Endpoints\n\nThe endpoints are documented in the project under the \"/endpoints\" directory.  \nTo run an access you can use the client or the extension.\n\n- [Bruno API Client](https://www.usebruno.com).\n- [VSCode Extension](https://marketplace.visualstudio.com/items?itemName=bruno-api-client.bruno)\n\n## Run test\n\nTests are implemented using bun which follows a jest-compatible structure.\n\n```sh\n# unit tests\npnpm test\n\npnpm test:integration\n```\n\nTests also run on pull requests and push to main, check `.github/workflows/lint-and-test.yaml`\n\n\u003e Reference: https://bun.sh/docs/cli/test#run-tests\n\n## Build\n\n\u003cdetails\u003e\n\n\u003csummary\u003eNodejs\u003c/summary\u003e\n\n```sh\npnpm node:build\npnpm node:start\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\n\u003csummary\u003eBun\u003c/summary\u003e\n\n```sh\npnpm bun:build\npnpm bun:start\n```\n\n\u003c/details\u003e\n\n## FAQ\n\n\u003cdetails\u003e\n\n\u003csummary\u003eWhy this structure?\u003c/summary\u003e\n\nThis is a matter of personal preference and depends on your application and deployment process.\n\nI've been using this case structure for a while and have found it enjoyable, though I'm still improving and learning as I go.\n\nI often aim for a balanced approach to structure for various reasons.\n\nAs a personal recommendation, try not to become too attached to any one framework. You’ll gain more value by focusing on structuring your code and learning about patterns that can benefit your team, projects, and clients.\n\nFeel free to adapt these ideas to fit your needs.\n\n[Hono best practices](https://hono.dev/guides/best-practices#best-practices)  \n[Hono presets](https://hono.dev/api/presets#which-preset-should-i-use)\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\n\u003csummary\u003eFramework agnostic?\u003c/summary\u003e\n\nThanks to Hono's simplicity, you can structure your project in a way that suits your needs.\n\nThe core of this project is located in the /app directory, where I use only JavaScript; none of these files are specific to Hono. This means that if you ever need to switch away from Hono for any reason, you can simply copy the /app directory and adjust the request handling as needed.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\n\u003csummary\u003eBun or node?\u003c/summary\u003e\n\nThanks to this structure, I can easily switch between them for testing. However, I still recommend using Node.js.\n\nIt really depends on your project and situation. I haven’t had the chance to test it in a large-scale real-world project yet, so I can’t say for sure. However, Bun is expected to be more efficient and use less memory.\n\nCurrently, I'm using Bun to run my tests, and it works well since it’s [based on Jest](https://bun.sh/docs/cli/test).\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\n\u003csummary\u003eWhy hono?\u003c/summary\u003e\n\n[Features](https://hono.dev/top#features)\n\nBased on my experience with Express.js and Fastify, I’ve found Hono to be powerful, easy to use, and supported by an active community.\n\nGive it a try.\n\nHere are some basic benchmarks (though they’re not particularly significant).  \n[Requests benchmark](https://web-frameworks-benchmark.netlify.app/result?f=express,hono,fastify,hono-bun)  \n[Compare benchmark](https://web-frameworks-benchmark.netlify.app/compare?f=express,hono,fastify,hono-bun)\n\nIf you're still not convinced, Fastify is also an excellent option.\n\n\u003c/details\u003e\n\n## Dependencies\n\n**Nodejs**\n\n\u003e To run the project using nodejs, we need some extra dependencies.\n\u003e These are already set in the project.\n\n```\n// dependencies\n@hono/node-server\n\n// devDependencies\ntypescript\ntsx\n```\n\n---\n\n## Extras\n\n#### Adding sentry\n\n- For the setup you can use the [hono middleware](https://github.com/honojs/middleware/tree/main/packages/sentry) created for that, you can follow the instructions on the readme there.\n\nThe setup is basically adding the middleware on the initial file.\n\n```ts\n...\nimport { sentry } from '@hono/sentry'\n...\n\napp.use(\n  '*',\n  sentry({\n    dsn: process.env.SENTRY_DNS,\n    tracesSampleRate: isProduction ? 0.2 : 0.8,\n    environment,\n  }),\n)\n```\n\nThen you can call on your global `app.onError`\n\n```ts\napp.onError((error, c) =\u003e {\n  c.get('sentry').captureException(e, {\n    tags: {}, // any tag\n    extra: {}, // any extra object\n  })\n\n  return c.json({ error, message: error.message || 'Unknown Error' }, 500)\n})\n```\n\n#### Connection example using tursodb (sqlie)\n\n- [Gist example](https://gist.github.com/marcosrjjunior/0a717f4b8b584a13fb36fdec4398d048)\n\n---\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarcosrjjunior%2Fhono-boilerplate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarcosrjjunior%2Fhono-boilerplate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarcosrjjunior%2Fhono-boilerplate/lists"}