Skip to content
Super simple subdomain middleware for expressjs
Branch: master
Clone or download
Latest commit 66bb8e6 Jul 12, 2018
Type Name Latest commit message Commit time
Failed to load latest commit information.
test Updated Readme Jul 11, 2018
.gitignore multi-tld tests Feb 19, 2016
.travis.yml multi-tld tests Feb 19, 2016 update readme - list tld gotcha Feb 19, 2016
index.js minor update May 3, 2014
package.json version bump to v1.0.5 Feb 20, 2016

Build Status Coverage Status


Is simply express middleware. In the examples below I am using Express v4.x.


With npm, saving it as a dependency.

npm i express-subdomain --save

Simple usage

Let's say you want to provide a RESTful API via the url

Express boilerplate code:

var subdomain = require('express-subdomain');
var express = require('express');
var app = express();

// *** Code examples below go here! ***

app.get('/', function(req, res) {

API Router

var router = express.Router();

//api specific routes
router.get('/', function(req, res) {
    res.send('Welcome to our API!');

router.get('/users', function(req, res) {
        { name: "Brian" }

Now register the subdomain middleware:

app.use(subdomain('api', router));

The API is alive: --> "Welcome to our API!" --> "[{"name":"Brian"}]"

Multi-level Subdomains

app.use(subdomain('v1.api', router)); //using the same router --> "Welcome to our API!" --> "[{"name":"Brian"}]"


Say you wanted to ensure that the user has an API key before getting access to it... and this is across all versions.

Note: In the example below, the passed function to subdomain can be just a pure piece of middleware.

var checkUser = subdomain('*.api', function(req, res, next) {
    if(!req.session.user.valid) {
        return res.send('Permission denied.');


This can be used in tandem with the examples above.

Note: The order in which the calls to app.use() is very important. Read more about it here.

app.use(subdomain('v1.api', router));

Divide and Conquer

The subdomains can also be chained, for example to achieve the same behaviour as above:

var router = express.Router(); //main api router
var v1Routes = express.Router();
var v2Routes = express.Router();

v1Routes.get('/', function(req, res) {
    res.send('API - version 1');
v2Routes.get('/', function(req, res) {
    res.send('API - version 2');

var checkUser = function(req, res, next) {
    if(!req.session.user.valid) {
        return res.send('Permission denied.');

//the api middleware flow
router.use(subdomain('*.v1', v1Routes));
router.use(subdomain('*.v2', v2Routes));

//basic routing..
router.get('/', function(req, res) {
    res.send('Welcome to the API!');

//attach the api
app.use(subdomain('api', router));

Invalid user --> Permission denied.

Valid user --> Welcome to the API! --> API - version 1 --> API - version 1 --> API - version 2 --> API - version 2

Developing Locally

If you plan to use this middleware while developing locally, you'll have to ensure that your subdomain is listed in your hosts file.

On Linux or OSX, add your subdomain to /etc/hosts:

You may not have write permissions on your hosts file, in which case you can grant them:

$ sudo chmod a+rw /etc/hosts

Note: Express parses the request URL for a top level domain, so developing locally without one won't be possible because Express will treat the subdomain as the domain, and the actual domain as a TLD.


On Windows 7 and 8, the hosts file path is %systemroot%\system32\drivers\etc.


Multilevel TLD's, such as you have to pass api.example as the subdomain:

app.use(subdomain('api.example', router));

See for more info.

Need in-depth examples?

Have a look at the tests!

You can’t perform that action at this time.