{"id":14989430,"url":"https://github.com/keenwon/koa-subdomain","last_synced_at":"2025-10-19T12:06:52.509Z","repository":{"id":8602254,"uuid":"59014095","full_name":"keenwon/koa-subdomain","owner":"keenwon","description":"Simple and lightweight Koa middleware to handle multilevel and wildcard subdomains","archived":false,"fork":false,"pushed_at":"2023-03-04T02:49:00.000Z","size":1651,"stargazers_count":23,"open_issues_count":11,"forks_count":5,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-04-14T22:47:15.281Z","etag":null,"topics":["koa","koa-middleware","koajs","router","subdomain"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","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/keenwon.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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}},"created_at":"2016-05-17T10:45:56.000Z","updated_at":"2024-06-18T22:32:47.594Z","dependencies_parsed_at":"2024-06-18T22:32:33.054Z","dependency_job_id":"f7f61d5e-dcde-4b7d-ad9a-5bc10bc9fd16","html_url":"https://github.com/keenwon/koa-subdomain","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/keenwon%2Fkoa-subdomain","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/keenwon%2Fkoa-subdomain/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/keenwon%2Fkoa-subdomain/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/keenwon%2Fkoa-subdomain/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/keenwon","download_url":"https://codeload.github.com/keenwon/koa-subdomain/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223486880,"owners_count":17153241,"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","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","koa-middleware","koajs","router","subdomain"],"created_at":"2024-09-24T14:18:21.581Z","updated_at":"2025-10-19T12:06:52.420Z","avatar_url":"https://github.com/keenwon.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# koa-subdomain\n\n[![NPM version][npm-image]][npm-url]\n[![Node version][node-image]][node-url]\n[![Build Status][github-actions-image]][github-actions-url]\n[![Coverage Status][coveralls-image]][coveralls-url]\n[![npm download][download-image]][download-url]\n[![Dependencies Status][dependencies-image]][dependencies-url]\n[![Devdependencies Status][devdependencies-image]][devdependencies-url]\n\nSimple and lightweight Koa middleware to handle multilevel and wildcard subdomains.\n\n## Installation\n\nInstall using npm:\n\n```shell\nnpm install koa-subdomain --save\n```\n\n[![xhr-plus](https://nodei.co/npm/koa-subdomain.png)](https://npmjs.org/package/koa-subdomain)\n\n## Usage\n\nuse with [koa-router](https://github.com/alexmingoia/koa-router):\n\n```javascript\nconst Koa = require('koa');\nconst Subdomain = require('koa-subdomain');\nconst Router = require('koa-router');\n\nconst app = new Koa();\nconst subdomain = new Subdomain();\nconst router = new Router();\n\nrouter.get('/', async ctx =\u003e {\n  ctx.body = 'one';\n});\n\n// one.example.com\nsubdomain.use('one', router.routes());\n\napp.use(subdomain.routes());\napp.listen(8888);\n```\n\nmore example:\n\n```javascript\nconst app = require('koa')();\nconst subdomain = require('koa-subdomain')();\n\n// one.example.com\nsubdomain.use('one', router1);\n\n// two.example.com\nsubdomain.use('two', router2);\n\nsubdomain\n  .use('a.one', router3)  // a.one.example.com\n  .use('b.one', router4); // b.one.example.com\n\n// example.com\nsubdomain.use('', router5);\n\n// *.example.com\nsubdomain.use('*', router6);\n\n// *.one.example.com\nsubdomain.use('*.one', router7);\n\n// one.*.example.com\nsubdomain.use('one.*', router8);\n\napp.use(subdomain.routes());\napp.listen(8888);\n```\n\nWildcard subdomains will be accessible under `wildcardSubdomains` in the state of koa context.\n\n```javascript\nconst Koa = require('koa');\nconst Subdomain = require('koa-subdomain');\nconst Router = require('koa-router');\n\nconst app = new Koa();\nconst subdomain = new Subdomain();\nconst router1 = new Router();\nconst router2 = new Router();\n\n// get test.example.com\nrouter1.get('/', async ctx =\u003e {\n    // in body will stand \"test\"\n    ctx.body = ctx.state.wildcardSubdomains[0];\n});\n\n// get foo.bar.example.com\nrouter2.get('/', async ctx =\u003e {\n    // in body will stand \"foo bar\"\n    ctx.body = ctx.state.wildcardSubdomains.join(' ');\n});\n\n// *.example.com\nsubdomain.use('*', router1.routes());\nsubdomain.use('*.*', router2.routes());\n\napp.use(subdomain.routes());\napp.listen(8888);\n```\n\n**Note**: Koa has a `subdomainOffset` setting (2, by default), so the domain of the app is assumed to be the last two parts of the host. Here is an example when it is useful: if your app domain is `localhost:3000`, you need to change `subdomainOffset` to 1 for proper subdomain detection.\n\n```js\nconst app = new Koa();\n\napp.subdomainOffset = 1\n\n// one.localhost:3000\nsubdomain.use('one', router);\n```\n\n## koa1\n\nInstall:\n\n```shell\nnpm install koa-subdomain@1 --save\n```\n\nUsage:\n\n```javascript\nconst app = require('koa')();\nconst subdomain = require('koa-subdomain')();\nconst router = require('koa-router')();\n\nrouter.get('/', function * () {\n  this.body = 'one';\n});\n\n// one.example.com\nsubdomain.use('one', router.routes());\n\napp.use(subdomain.routes());\napp.listen(8888);\n```\n\n## Run test\n\n```shell\ngit clone https://github.com/keenwon/koa-subdomain.git\ncd koa-subdomain\nnpm install\nnpm test\n```\n\n[npm-image]: https://img.shields.io/npm/v/koa-subdomain.svg\n[npm-url]: https://www.npmjs.com/package/koa-subdomain\n[node-image]: https://img.shields.io/node/v/koa-subdomain.svg\n[node-url]: https://nodejs.org\n[github-actions-image]: https://github.com/keenwon/koa-subdomain/workflows/unittest/badge.svg\n[github-actions-url]: https://github.com/keenwon/koa-subdomain/actions\n[coveralls-image]: https://img.shields.io/codecov/c/github/keenwon/koa-subdomain\n[coveralls-url]: https://codecov.io/gh/keenwon/koa-subdomain\n[download-image]: https://img.shields.io/npm/dm/koa-subdomain.svg\n[download-url]: https://npmjs.org/package/koa-subdomain\n[dependencies-image]: https://img.shields.io/david/keenwon/koa-subdomain.svg\n[dependencies-url]: https://david-dm.org/keenwon/koa-subdomain\n[devdependencies-image]: https://img.shields.io/david/dev/keenwon/koa-subdomain.svg\n[devdependencies-url]: https://david-dm.org/keenwon/koa-subdomain?type=dev\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkeenwon%2Fkoa-subdomain","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkeenwon%2Fkoa-subdomain","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkeenwon%2Fkoa-subdomain/lists"}