README.md

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