{"id":13672872,"url":"https://github.com/unix/koa-ts","last_synced_at":"2025-09-25T14:48:55.943Z","repository":{"id":41038482,"uuid":"122935229","full_name":"unix/koa-ts","owner":"unix","description":"The best practice of building Koa2 with TypeScript","archived":false,"fork":false,"pushed_at":"2023-03-04T03:17:31.000Z","size":1230,"stargazers_count":378,"open_issues_count":10,"forks_count":55,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-09-20T02:54:41.117Z","etag":null,"topics":["koa-typescript","koa2","koa2-starter","koa2-typescript-guide","nodejs-typescript"],"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/unix.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","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}},"created_at":"2018-02-26T08:07:10.000Z","updated_at":"2025-07-22T11:20:08.000Z","dependencies_parsed_at":"2024-07-19T16:52:28.081Z","dependency_job_id":"eacaaa91-8a34-45f2-9b16-4128304c4711","html_url":"https://github.com/unix/koa-ts","commit_stats":null,"previous_names":["wittbulter/koa2-typescript-guide"],"tags_count":24,"template":false,"template_full_name":null,"purl":"pkg:github/unix/koa-ts","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unix%2Fkoa-ts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unix%2Fkoa-ts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unix%2Fkoa-ts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unix%2Fkoa-ts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/unix","download_url":"https://codeload.github.com/unix/koa-ts/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unix%2Fkoa-ts/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":276936338,"owners_count":25731570,"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-09-25T02:00:09.612Z","response_time":80,"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":["koa-typescript","koa2","koa2-starter","koa2-typescript-guide","nodejs-typescript"],"created_at":"2024-08-02T09:01:53.538Z","updated_at":"2025-09-25T14:48:55.900Z","avatar_url":"https://github.com/unix.png","language":"TypeScript","funding_links":[],"categories":["TypeScript","目录"],"sub_categories":[],"readme":"### koa-ts\n\nThe best practice of building Koa2 with TypeScript. [中文](/README_CN.md)\n\n---\n\n#### Usage\n\n1. Run `npm init koa-ts`\n\n2. Install dependencies: `yarn`\n\n3. Rename `.env.example` to `.env`, and run `prisma db push` to synchronize the data model\n\n4. Start the server: `yarn dev`. visit: http://127.0.0.1:3000/apis/sessions\n\n\u003e **(Optional)** the project has built-in a docker compose, run `yarn dev:db` to run database automatic.\n\n---\n\n#### Project Layout\n\n```\n├── app\n│   ├── controllers         ---  server controllers\n│   ├── helpers             ---  helper func (interceptor / error handler / validator...)\n│   ├── jobs                ---  task (periodic task / trigger task / email server...)\n│   ├── entities            ---  database entities/models\n│   └── services            ---  adhesive controller and model\n├── config\n│   ├── constants        ---  environment variable\n│   ├── koa.middlewares     ---  middlewares for Koa\n│   ├── routing.middlewares ---  middlewares for Routing Controller\n│   ├── routing.options     ---  configs for Routing Controller\n│   ├── bootstrap           ---  lifecycle\n│   └── interceptors        ---  global interceptor\n│   └── utils               ---  pure functions for help\n└── test                    ---  utils for testcase\n├── .env           ---  environment file\n```\n\n---\n\n#### Feature\n\n- Separation configuration and business logic.\n\n- Export scheme model and interface, follow style of TypeScript.\n\n- Test cases and lint configuration.\n\n- The best practice for Dependency Injection in Koa project.\n\n- Get constraints on your data model with Prisma.\n\n- TypeScript hotload.\n\n---\n\n#### Lifecycle\n\n1. `app.ts` -\u003e collect env vars `constants` -\u003e collect env files `variables.env`\n\n2. envs ready, call `bootstrap.before()`\n\n3. lift `routing-controllers` -\u003e lift Koa middlewares -\u003e register `Container` for DI\n\n4. start Koa \u0026amp; invoke `bootstrap.after()` after startup\n\n---\n\n#### Databases\n\nThe project uses Prisma as the intelligent ORM tool by default. Supports `PostgreSQL`, `MySQL` and `SQLite`.\n\n- You can change the data type and connection method in the `.env` file\n- After each modification to file `/prisma/schema.prisma`, you need to run `prisma migrate dev` to migrate the database.\n- After each modification to file `/prisma/schema.prisma`, you need to run `prisma generate` to sync types.\n\n---\n\n#### About Environments\n\nWhen nodejs is running, `ENV` does not mean `NODE_ENV`:\n\n- After NodeJS project is built, we always run it as `NODE_ENV=PRODUCTION`, which may affect some framework optimizations.\n- `NODE_ENV` only identifies the NodeJS runtime, independent of the business.\n- You should use `ENV` to identify the environment.\n\nFor the data settings of each environment, you can refer to the following:\n\n- **Development Mode** (`ENV=development`): read configurations from `configs/constants/development.ts` file, but it will still be overwritten by `.env` file.\n\n- **Production Mode** (`ENV=production`): read configurations from `configs/constants/production.ts` file, but it will still be overwritten by `.env` file.\n\n---\n\n#### Reference\n\n- [routing-controllers](https://github.com/typestack/routing-controllers)\n- [Prisma](https://www.prisma.io/docs/concepts)\n\n---\n\n#### LICENSE\n\nThis project is licensed under the MIT License. See the [LICENSE](./LICENSE) file for more info.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funix%2Fkoa-ts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Funix%2Fkoa-ts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funix%2Fkoa-ts/lists"}