{"id":30172088,"url":"https://github.com/tech-dex/hono-minmial-kit","last_synced_at":"2026-04-14T14:31:12.180Z","repository":{"id":309353288,"uuid":"1035940606","full_name":"Tech-Dex/hono-minmial-kit","owner":"Tech-Dex","description":"A collection of tools that provide a starting point for building web applications with Node.js and Hono. It includes configurations for TypeScript, ESLint, Prettier, and MikroORM for database management.","archived":false,"fork":false,"pushed_at":"2025-08-11T10:52:28.000Z","size":329,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-08-11T12:30:00.724Z","etag":null,"topics":["docker","docker-compose","gitlab-ci-cd","hono","honojs","honojs-boilerplate","mikro-orm","node","node-boilerplate","nodejs","terraform"],"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/Tech-Dex.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}},"created_at":"2025-08-11T10:20:29.000Z","updated_at":"2025-08-11T10:59:40.000Z","dependencies_parsed_at":"2025-08-11T12:30:06.306Z","dependency_job_id":"29a377b5-0e4f-4649-a44b-e4984000ac9d","html_url":"https://github.com/Tech-Dex/hono-minmial-kit","commit_stats":null,"previous_names":["tech-dex/hono-minmial-kit"],"tags_count":null,"template":true,"template_full_name":null,"purl":"pkg:github/Tech-Dex/hono-minmial-kit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tech-Dex%2Fhono-minmial-kit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tech-Dex%2Fhono-minmial-kit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tech-Dex%2Fhono-minmial-kit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tech-Dex%2Fhono-minmial-kit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Tech-Dex","download_url":"https://codeload.github.com/Tech-Dex/hono-minmial-kit/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tech-Dex%2Fhono-minmial-kit/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269970085,"owners_count":24505457,"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-08-11T02:00:10.019Z","response_time":75,"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":["docker","docker-compose","gitlab-ci-cd","hono","honojs","honojs-boilerplate","mikro-orm","node","node-boilerplate","nodejs","terraform"],"created_at":"2025-08-11T23:00:20.979Z","updated_at":"2025-09-16T03:58:59.573Z","avatar_url":"https://github.com/Tech-Dex.png","language":"TypeScript","readme":"# Hono Minimal Kit\n\n## Table of Contents\n\n- [Project Overview \u0026 Reasoning](#project-overview--reasoning)\n- [Features](#features)\n- [Resources \u0026 External Documentation](#resources--external-documentation)\n- [Prerequisites](#prerequisites)\n- [Installation](#installation)\n- [Running the Project](#running-the-project)\n- [Scripts](#scripts)\n- [Project Structure](#project-structure)\n- [Environment Variables](#environment-variables)\n- [API Documentation](#api-documentation)\n- [Docker \u0026 CI/CD](#docker--cicd)\n- [Developer Experience \u0026 Where to write code - Please read](#developer-experience--how-to-write-code)\n\n## Project Overview \u0026 Reasoning\n\nThis boilerplate provides a starting point for building web applications with Node and Hono. It includes configurations\nfor TypeScript, ESLint, Prettier, and Mikro-ORM for database management.\nThis is highly opinionated.\n\nThe boilerplate was initially created for a GitLab project, so it includes a GitLab CI/CD configuration file and CI/CD is for that.\nI am too lazy to migrate it to GitHub Actions, but you can do it easily if you want to use GitHub Actions.\n\nIt doesn't encourage you to overuse TypeScript nor OOP principles, but it does encourage you to use it where it makes\nsense.\nMost of the time you'll find that this is mostly used for database entities.\nThe code should be written inside the controller directly, and not in a service class, in a different file.\nI am not a fan of too many abstractions, and I believe that the code should be as simple as possible, and easy to read.\nYou will see that the code is written in a procedural \u0026 functional way, and not in an OOP way. But don't overuse\nfunctional programming\nprinciples either. Use them where it makes sense, and where it makes the code easier to read and understand.\n\nI am personally a big fan of procedural \u0026 imperative programming, and I believe that it is the best way to write code as\nit forces you\nto understand the code you are writing, and not just write it because it works. Don't be afraid of long functions.\nIf you want to read more and learn more about this YouTube Brian Will and his 2 popular videos about OOP.\n\nI went with Hono because it is a small, [fast](https://hono.dev/docs/concepts/benchmarks), portable and simple web\nframework for JavaScript ecosystem. You can switch from Node to Deno, Bun, Lambda, or Cloudflare workers easily. It is\nvery simple to use, and it is very fast. Better results than Express.js and other popular frameworks.\n\nI am not a fan of ORMs, but I have included Mikro-ORM in this boilerplate. I have had problems with performance and for\ncomplex queries they become hard to read. I went with it because it is built on top of Knex.js and I had good\nexperiences with it.\nIf you don't like it, you can use the [query builder from Mikro-ORM](https://mikro-orm.io/docs/query-builder/).\n\nI might be right, I might be wrong but that's how I felt when I wrote this boilerplate. Heavily inspired\nby [FastAPI](https://fastapi.tiangolo.com/tutorial/bigger-applications/) and my previous boilerplate written for that\nframework.\n\nI hope you will find this boilerplate useful and that you will learn something from it. I am open to suggestions and\nimprovements.\n\n## Features\n\n- **[Node](https://nodejs.org)**: A secure runtime for JavaScript and TypeScript.\n- **[Hono](https://hono.dev/)**: A small, fast, and simple web framework for Node | Deno | Bun | Lambda | Cloudflare\n  workers.\n- **[TypeScript](https://www.typescriptlang.org/)**: Strongly typed programming language that builds on JavaScript.\n- **[Mikro-ORM](https://mikro-orm.io/)**: TypeScript ORM for Node.js based on Data Mapper, Unit of Work, and Identity\n  Map patterns.\n- **[Zod](https://zod.dev/)**: TypeScript-first schema declaration and validation library.\n- **[OpenAPI](https://www.openapis.org/what-is-openapi)**: API documentation and validation.\n- **[Scalar](https://scalar.com/)**: The modern open-source developer experience platform for your APIs.\n- **[Husky](https://typicode.github.io/husky/)**: Git hooks made easy.\n\n## Resources \u0026 External Documentation\n\n- **[Hono Documentation](https://hono.dev/docs/)**: Learn more about Hono.\n- **[Micro-ORM Documentation](https://mikro-orm.io/docs/)**: Learn more about Mikro-ORM.\n- **[Hono Zod OpenAPI](https://github.com/rhinobase/hono-openapi-zod)**: Generate OpenAPI schemas from Zod schemas for\n  Hono.\n\n## Prerequisites\n\nBefore you begin, ensure you have met the following requirements:\n\n- **Node:22.14.0**: Install Node from [nodejs.org](https://nodejs.org).\n- **pnpm:10.5.2**: Install pnpm from [pnpm.io](https://pnpm.io/installation).\n- **Docker:20.10.23**: Install Docker from [docker.com](https://www.docker.com/get-started).\n  Those are the versions I used to develop this boilerplate. You can use other versions, but I can't guarantee that\n  everything will work as expected.\n\n## Installation\n\n1. Clone the repository:\n\n   ```sh\n   git clone https://github.com/Tech-Dex/hono-minmial-kit.git\n   cd hono-minmial-kit\n   ```\n\n2. Change the git remote URL:\n\n   ```sh\n   git remote set-url origin \u003cyour-repository-url\u003e\n   ```\n\n3. Install dependencies:\n\n   ```sh\n   pnpm install\n   ```\n\n## Running the Project\n\nYou should have the environment variables set in the `.env` file. [Read more about environment variables](#environment-variables).\n\nTo start the development server, run:\n\n```sh\npnpm dev\n```\n\nTo build the project, this will create the `dist` directory, run:\n\n```sh\npnpm build\n```\n\nTo start the production server, you must have the `dist` folder directory by the build command. Run:\n\n```sh\npnpm production\n```\n\nYou can also run it with Docker and Docker Compose, I recommend you to use it for development.\n\n1. Run the docker compose stack:\n\n```sh\npnpm docker:dev:up\n```\n\n2. Stop the docker compose stack:\n\n```sh\npnpm docker:dev:down\n```\n\n3. Check the logs:\n\n```sh\npnpm docker:dev:logs\n```\n\nor\n\n```sh\npnpm docker:dev:logs -f \u003cservice-name\u003e\n```\n\n## Scripts\n\nHere are the available scripts for this project:\n\n- `dev`: Start the development server with hot-reloading.\n- `start`: Start the server with ts-node. (Useful for debugging)\n- `format`: Format the code using Prettier.\n- `lint`: Lint the code using ESLint.\n- `lint:fix`: Lint and fix the code using ESLint.\n- `check`: Type-check the code using TypeScript.\n- `build`: Build the project. A `dist` folder will be created.\n- `production`: Start the production server.\n- `prepare:commit`: Run checks and format code before committing. Run it always before you want to git add and commit.\n- `db:mgrt:initial`: Create the initial database migration.\n- `db:mgrt:create`: Create a new database migration.\n- `db:mgrt:up`: Apply all pending migrations.\n- `db:mgrt:down`: Revert the last migration.\n- `db:mgrt:list`: List all migrations.\n- `db:mgrt:check`: Check the status of migrations.\n- `db:mgrt:pending`: List all pending migrations.\n- `db:mgrt:fresh`: Recreate the database and apply all migrations.\n- `db:seed:create`: Create a new database seed. (Most likely will not be needed, you can insert everything in the\n  initial seed)\n- `db:seed:run`: Run all seeds. (Will apply the seed over the current data in the database)\n- `db:seed:fresh`: Recreate the database, apply all migrations, and run all seeds.\n- `gen:secret`: Generate a new JWT secret.\n- `docker:dev:up`: Start the development stack with Docker Compose.\n- `docker:dev:down`: Stop the development stack with Docker Compose.\n- `docker:dev:logs`: Show the logs of the development stack with Docker Compose.\n\n## Project Structure\n\n```plaintext\n.\n├── .husky/                     # Git hooks\n├── dist/                       # Compiled source code - not included in the repository\n├── .env                        # Environment configuration file\n├── logs/                       # Log files generated by the application - not included in the repository\n│   └── traffic/                # Traffic logs generated by the application - not included in the repository\n├── src/                        # Source code\n│   ├── core/                   # Core modules and utilities (You can add/edit more configurations here, but most likely you will not need to)\n│       ├── config-factory.ts   # Configuration factory for Hono\n│       ├── logger.ts           # Logger class\n│       └── security.ts         # Security functions\n│   ├── entities/               # Database entities\n│   ├── lib/                    # Libraries that are not specific to the application. For example: enums, types, errors, a standalone mail service, etc.\n│   ├── routers/                # API route handlers\n│       ├── router.ts           # Main router. Add new routes here. Auth and users routes are already added.\n│       ├── auth.router.ts      # Auth routes\n│       └── users.router.ts     # Users routes\n│   ├── schemas/                # Request \u0026  Response validation schemas\n│       ├── errors.ts           # Generic zod schemas for error responses. (You can add more here based on your needs)\n│       ├── requests.ts         # Request validation schemas\n│       └── responses.ts        # Response validation schemas\n│   ├── seeders/                # Database seeders\n│       └── DatabaseSeeder.ts   # Initial database seeder. You can add your seed data here, not really necessary to create new seeders.\n│   ├── utils/                  # Utility functions\n│       └── middlewares.ts      # Middleware functions. You will most likely need to add more middlewares here. You have an example for a middleware in here.\n│   ├── index.ts                # Entry point of the application. (Most likely you will not need to edit this file, it can be changed to use Bun/Deno instead of Node)\n│   └── mikro-rom.config.ts     # Mikro-ORM configuration. (You will most likely not need to edit this file)\n├── .eslintrc.json              # ESLint configuration\n├── .prettierrc                 # Prettier configuration\n├── package.json                # Project metadata and scripts\n├── pnpm-lock.yaml              # Lockfile for dependencies\n└── tsconfig.json               # TypeScript configuration\n```\n\n## Environment Variables\n\nThe project uses environment variables for configuration. You can find the environment variables in the `envs`\ndirectory.\nYou can create a `.env` file in that directory and fill it.\n\n| Key                | Value                         | Description                                                                            |\n| ------------------ | ----------------------------- | -------------------------------------------------------------------------------------- |\n| NODE_ENV           | development                   | The environment in which the application runs.                                         |\n| MIKRO_ORM_PORT     | 3000                          | The port on which the server listens.                                                  |\n| MIKRO_ORM_HOST     | localhost                     | The database host address. localhost will work with you docker database.               |\n| MIKRO_ORM_USER     | postgres                      | The database user.                                                                     |\n| MIKRO_ORM_PASSWORD | pass                          | The password for the database user.                                                    |\n| MIKRO_ORM_PORT     | 5432                          | The port on which the database listens.                                                |\n| MIKRO_ORM_DB_NAME  | default-db                    | The name of the database.                                                              |\n| JWT_SECRET         | secret                        | The secret key used for signing JWT tokens. You can generate it with `pnpm gen:secret` |\n| JWT_ALG            | HS256                         | The algorithm used for signing JWT tokens.                                             |\n| DOMAIN             | mywebsite.com                 | The domain name of the application. Used for CORS.                                     |\n| MAILTRAP_HOST      | sandbox.smtp.mailtrap.io      | The host for the Mailtrap SMTP service.                                                |\n| MAILTRAP_PORT      | 2525                          | The port for the Mailtrap SMTP service.                                                |\n| MAILTRAP_USER      | 1b1b1b1b1b1b1b                | The username for the Mailtrap SMTP service.                                            |\n| MAILTRAP_PASS      | 2b2b2b2b2b2b2b                | The password for the Mailtrap SMTP service.                                            |\n| TARGET_MAIL_SERVICE| mailtrap                      | The target mail service to be used.                                                    |\n\n## API Documentation\n\nThe project uses OpenAPI for API documentation. You can find the API documentation at `/docs` endpoint when the server\nis running. The documentation is generated using Scalar. The health check endpoint is available at `/health`.\n![docs.png](openapi-scalar.png)\n\n### Example Routes\n\n- **POST /auth/login**: Login a user.\n- **POST /auth/register**: Register a new user.\n- **GET /auth/refresh**: Refresh the JWT token. (requires JWT authentication).\n- **GET /users/:\\_id**: Get user by ID (requires JWT authentication).\n\n## Docker \u0026 CI/CD\n\nThe project includes a Dockerfile and a docker-compose.yml file for running the application in a Docker container. There\nis also a GitLab CI/CD configuration file for packaging the application in an image and save it in the GitLab registry.\n\nIn GitLab CI/CD, you can use the following variables, you have to set the $ENV_FILE in variables:\n-\u003e Settings -\u003e CI/CD -\u003e Variables -\u003e Add Variable -\u003e Key: ENV_FILE, Type: file -\u003e Value: what you have in .env file\n\nThe .gitlab-ci.yml file is configured to run the following stages:\n\n- copy the .env file to the root directory ( as the .env is not tracked by git, we add it to the root directory only for the CI/CD)\n- run the docker build command\n\nYou can add a new stage for deploying the application to a server. There you can use sth like AWS ECS or SSH into\na server, git pull the code, and run the docker compose command. For the second option you'll be required to add a new\nvariables in the GitLab CI/CD settings for the SSH key ( SSH_PRIVATE_KEY ) and the host ( SSH_HOST ). YOu have an example\nin the .gitlab-ci.yml file.\n\nThere are files for development: dev.docker-compose.yml and dev.Dockerfile. You can use them to run the application in\ndevelopment mode with Docker. You can use the following commands:\n\n- `pnpm docker:dev:up`: Start the development stack with Docker Compose.\n- `pnpm docker:dev:down`: Stop the development stack with Docker Compose.\n- `pnpm docker:dev:logs`: Show the logs of the development stack with Docker Compose.\n- `pnpm docker:dev:logs -f \u003cservice-name\u003e`: Show the logs of a specific service with Docker Compose.\n\nMost likely you will not need to change anything in those. The Dockerfiles uses the volume to mount the source code\nfrom your local machine to the container. This way you can make changes to the code and see the changes in real-time.\n\n## Developer Experience \u0026 Where to write Code\n\n- Most of the time you'll find yourself working only inside the following\n  directories: `src/routers`, `src/entities`, `src/schemas`, `src/utils`. Sometimes you might need to work\n  inside `src/lib` and `src/seeders` ( if you don't want to create testing data manually ).\n- You should write the code inside the controller directly, and not in a service class or in a different file. If you\n  need to reuse some code, you can create a utility function inside `src/utils` and import it in the controller. Pass\n  the Context object or only what you need from context to the utility function.\n- Use plural names for the routes. For example, use `/users` instead of `/user`.\n- Use plural names for the entities. For example, use `Users` instead of `User`. The database table names should be\n  plural as well.\n  - `Users` entity will be stored in the `users` table.\n  - One-to-many relationships should be named singular_plurals. Example: `user_tickets` table.\n  - Many-to-many relationships should be named plurals_plurals. Example: `users_roles` table. If you find a better\n    name like `relationships` instead of `users_friends`, you can use that.\n- If you want to start with a different database schema, just delete everything from `src/migrations`, define your new\n  entities in `src/entities`, and run `pnpm db:mgrt:initial`. This will create the initial migration for your new\n  schema.\n- Use snake_case for the database column names. For example, use `users_roles` instead of `usersRoles`.\n- Use camelCase for the properties of the entities \u0026 request and response schemas For example, use `firstName` instead\n  of `first_name`.\n- Use PascalCase for the class names. For example, use `Users` instead of `users` or `UsersRoles` instead\n  of `usersRoles`.\n- TypeScript it is not mandatory to use, it becomes tedious to use it in some cases, and it is not always necessary.\n  Write it for things that will be reused, in a controller where you just fetch data from database, you can skip it. In\n  the end the code will be compiled to plain JavaScript. TypeScript is it here you help you develop safer code and catch\n  errors before they happen. If you are using a code editor (VSCode) install plugins that will tell you the variable\n  type or make yourself a favor and use an IDE like [WebStorm](https://www.jetbrains.com/webstorm/) that way you will\n  know types even if not declared specifically.\n- Use [Convco](https://convco.github.io/). This is a non-negotiable. It forces you to write decent commits.\n- Use [Docker](https://www.docker.com/) for development. Start a database container and connect your local code to it.\n  Later you'll test if it works for deployment with docker-compose.yml and the docker compose command.\n- Don't run the project with node-ts. DON'T DO IT. It is slow, and it is not recommended for production. Build the `dist`\n  directory and run the project from there. Use `pnpm dev` for development and `pnpm production` for production.\n\n## Contact\n\nFor any questions or inquiries, please contact:\n\n- **[FastAPI Infra Kit](https://github.com/Tech-Dex/fastapi-infra-kit)**: If you want to use\n  Python for specific features, you can use this boilerplate.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftech-dex%2Fhono-minmial-kit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftech-dex%2Fhono-minmial-kit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftech-dex%2Fhono-minmial-kit/lists"}