The subdomain middleware matches Request which subdomain is conform to expectations.


Domains are interpreted in their semantical right-to-left order and matched as suffix.

The pattern is specified as the first argument. It may contain asterisk * which specify that any supplied label satisfy that position.

app.use (subdomain ("api", (req, res) => {
    // match domains like '' and ''

app.use (subdomain ("\*.user", (req, res) => {
    // match at least two labels: the first can be anything and the second
    // is exactly 'user'

The matched subdomain labels are extracted and passed by parameter.

app.use (subdomain ("api", (req, res, next, ctx, subdomains) => {
    // 'subdomains' could be 'api' or 'v1.api'

This middleware can be used along with subrouting to mount any Router on a specific domain pattern.

var app = new Router ();
var api = new Router ();

app.use (subdomain ("api", api.handle));


There is two matching mode: loose and strict. The loose mode only expect the request to be performed on a suffix-compatible hostname. For instance, api would match and as well.

To prevent this and perform a _strict_ match, simply specify the second argument. The domain of the request will have to supply exactly the same amount of labels matching the expectations.

// match every request exactly from 'api.*.*'
app.use (subdomain ("api", api.handle, SubdomainFlags.STRICT));

Skip labels

By default, the two first labels are ignored since web applications are typically served under two domain levels (eg. If it’s not the case, the number of skipped labels can be set to any desirable value.

// match exactly ''
app.use (subdomain ("", api.handle, SubdomainFlags.STRICT, 0));