koa-subdomain

Simple and lightweight Koa middleware to handle multilevel and wildcard subdomains.

Installation

Install using npm:

npm install koa-subdomain --save

Usage

use with koa-router:

const Koa = require('koa');
const Subdomain = require('koa-subdomain');
const Router = require('koa-router');
 
const app = new Koa();
const subdomain = new Subdomain();
const router = new Router();
 
router.get('/', async ctx => {
  ctx.body = 'one';
});
 
// one.example.com
subdomain.use('one', router.routes());
 
app.use(subdomain.routes());
app.listen(8888);

more example:

const app = require('koa')();
const subdomain = require('koa-subdomain')();
 
// one.example.com
subdomain.use('one', router1);
 
// two.example.com
subdomain.use('two', router2);
 
subdomain
  .use('a.one', router3)  // a.one.example.com
  .use('b.one', router4); // b.one.example.com
 
// example.com
subdomain.use('', router5);
 
// *.example.com
subdomain.use('*', router6);
 
// *.one.example.com
subdomain.use('*.one', router7);
 
// one.*.example.com
subdomain.use('one.*', router8);
 
app.use(subdomain.routes());
app.listen(8888);

Wildcard subdomains will be accessible under wildcardSubdomains in the state of koa context.

const Koa = require('koa');
const Subdomain = require('koa-subdomain');
const Router = require('koa-router');
 
const app = new Koa();
const subdomain = new Subdomain();
const router1 = new Router();
const router2 = new Router();
 
// get test.example.com
router1.get('/', async ctx => {
    // in body will stand "test"
    ctx.body = ctx.state.wildcardSubdomains[0];
});
 
// get foo.bar.example.com
router2.get('/', async ctx => {
    // in body will stand "foo bar"
    ctx.body = ctx.state.wildcardSubdomains.join(' ');
});
 
// *.example.com
subdomain.use('*', router1.routes());
subdomain.use('*.*', router2.routes());
 
app.use(subdomain.routes());
app.listen(8888);

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.

const app = new Koa();
 
app.subdomainOffset = 1
 
// one.localhost:3000
subdomain.use('one', router);

koa1

Install:

npm install koa-subdomain@1 --save

Usage:

const app = require('koa')();
const subdomain = require('koa-subdomain')();
const router = require('koa-router')();
 
router.get('/', function * () {
  this.body = 'one';
});
 
// one.example.com
subdomain.use('one', router.routes());
 
app.use(subdomain.routes());
app.listen(8888);

Run test

git clone https://github.com/keenwon/koa-subdomain.git
cd koa-subdomain
npm install
npm test