Registry / web-framework / express-subdomain

express-subdomain

library1.0.6jsnpmunverified

Simple and lightweight middleware for handling subdomains in Express.js applications. Current stable version is 1.0.6, with minimal releases since initial publication. Key differentiators: zero dependencies, supports multi-level subdomains, wildcards, and chaining. Simpler than alternatives like vhost, focusing only on subdomain routing without virtual hosting features.

web-framework

npm install express-subdomain

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · EXPRESS-SUBDOMAIN

express-subdomain

web-frameworkjavascriptv1.0.6

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

✓ import subdomain from 'express-subdomain'

✗ const subdomain = require('express-subdomain')

ESM-only; package ships TypeScript types but no CommonJS support

subdomain

✓ import subdomain from 'express-subdomain'

✗ import { subdomain } from 'express-subdomain'

Default export only; named import is incorrect

subdomain

✓ const subdomain = require('express-subdomain')

✗ const { subdomain } = require('express-subdomain')

CJS requires default assignment; destructured import does not work

Demonstrates basic subdomain routing with Express Router and wildcard subdomain middleware.

import express from 'express'; import subdomain from 'express-subdomain'; const app = express(); const apiRouter = express.Router(); apiRouter.get('/', (req, res) => { res.send('Welcome to API'); }); app.use(subdomain('api', apiRouter)); app.get('/', (req, res) => { res.send('Homepage'); }); app.listen(3000, () => console.log('Server running on port 3000'));

Debug

Known issues

gotchaSubdomain middleware must be registered before other routes that match the base domain, otherwise Express may match base routes first.

fix

Ensure app.use(subdomain(...)) is placed before app.get('/', ...).

affects: >=1.0

gotchaWildcard subdomains (e.g., '*.api') match any single subdomain part, not multi-level wildcards.

fix

Use explicit multi-level subdomain strings like 'v1.api' or chain subdomain middleware for deeper nesting.

affects: >=1.0

gotchaSubdomain resolution depends on the Host header; local development requires proper hosts file entries (e.g., 'subdomain.localhost' may not work).

fix

Add entries to /etc/hosts or use tools like ngrok to test subdomains.

affects: >=1.0

Errors

Common errors & fixes

Cannot find module 'express-subdomain'

Package not installed or used in a non-ESM context without proper import.

fix

Run 'npm install express-subdomain' and use 'import subdomain from 'express-subdomain'' in ESM code.

TypeError: subdomain is not a function

Attempted to use named import instead of default import.

fix

Use 'import subdomain from 'express-subdomain'' (default import) instead of 'import { subdomain }...'.

Upgrade

Version history

1.0.6latest on npm

Audit

Dependencies

expressoptionalpeer dependency; middleware operates on Express request/response objects

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/bmullan91/express-subdomain ↗

packagehttps://www.npmjs.com/package/express-subdomain ↗

homepagehttps://npmjs.com/package/express-subdomain ↗