{"id":28328756,"url":"https://github.com/peterjoseph/subdomain-router-middleware","last_synced_at":"2026-05-09T09:10:38.844Z","repository":{"id":57373895,"uuid":"128497099","full_name":"peterjoseph/subdomain-router-middleware","owner":"peterjoseph","description":"Middleware for handling subdomains using Express and React.","archived":false,"fork":false,"pushed_at":"2018-04-14T11:05:17.000Z","size":17,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-06-02T17:29:28.464Z","etag":null,"topics":["express","express-js","express-middleware","middleware","react-router","react-router-v4","subdomain","subdomain-middleware"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/peterjoseph.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-04-07T04:45:34.000Z","updated_at":"2018-04-14T11:05:17.000Z","dependencies_parsed_at":"2022-09-10T22:20:53.609Z","dependency_job_id":null,"html_url":"https://github.com/peterjoseph/subdomain-router-middleware","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/peterjoseph/subdomain-router-middleware","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peterjoseph%2Fsubdomain-router-middleware","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peterjoseph%2Fsubdomain-router-middleware/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peterjoseph%2Fsubdomain-router-middleware/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peterjoseph%2Fsubdomain-router-middleware/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/peterjoseph","download_url":"https://codeload.github.com/peterjoseph/subdomain-router-middleware/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peterjoseph%2Fsubdomain-router-middleware/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261652001,"owners_count":23190171,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["express","express-js","express-middleware","middleware","react-router","react-router-v4","subdomain","subdomain-middleware"],"created_at":"2025-05-26T08:17:06.748Z","updated_at":"2026-05-09T09:10:33.803Z","avatar_url":"https://github.com/peterjoseph.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# subdomain-router-middleware\n### Middleware for handling subdomains using Express.\n\n**subdomain-router-middleware** provides validation on express routes so that they are only accessible via the correct subdomain.\n\nInstallation\n-----\n\n```\nnpm install subdomain-router-middleware\n```\n\nDependencies\n-----\n- Express JS\n- property-validator\n\nUsage\n-----\n\n1) In the router file of your express project, require the package as follows.\n\n```\nvar subdomain = require(\"subdomain-router-middleware\");\n```\n\nCertain initialisation parameters need to be declared in order for the middleware to function correctly.\n\n2) Create an object with the following parameters and pass it into the init function.\n\n```\nsubdomain.init({\n  asyncLoad: false,\n  asyncFunc: null,\n  error: {\n    success: false,\n    message: \"Invalid subdomain\"\n  }\n});\n```\n\n| Parameter | Type | Description |\n|:---|:---|:---|\n| `asyncLoad` | bool | Boolean to specify if valid subdomains should be asynchronously loaded. |\n| `asyncFunc` | Function | Specify a promise function to asynchronously load a list of valid subdomains. |\n| `error` | JSON | JSON that is returned when a subdomain is invalid. |\n\n\nIn your express routes, add the middleware.\n\n```\nrouter.get(\"/test\", subdomain.route(\"subdomain\"), function(req, res) {}\n```\n\nValidate individual subdomain\n-----\nTo specifiy a route that is only accessible with a certain subdomain, add the middleware and pass a string that contains the valid subdomain.\n\n```\nsubdomain.route(\"mysubdomain\")\n```\n\nLoad valid subdomains asyncronously\n-----\nIn many web applications, users can specify their own subdomain linked to their account.\n\nYou may need to asyncronously load a list of valid subdomains where the route is accessible.\n\nTo do so, we first need to modify the setup object we passed into the subdomain.init() function.\n\n1) Change the boolean parameter **asyncLoad** to true.\n\n2) Add a function to the **asyncFunc** parameter.\n\n```\nasyncFunc: function() {\n    return new Promise((resolve, reject) =\u003e {\n      // Server call to retrieve subdomains\n      const array = [];\n      resolve(array);\n    });\n  },\n```\n\nThe middleware expects a javascript promise that returns an array containing all of the subdomains that are valid for the route.\n\nInvalid routes with subdomain\n-----\nIf you want certain routes to be completely inaccessible via a subdomain, you can use the alternative subdomain middleware function called **root**.\n\nIn your route, add the function.\n\n```\nrouter.get(\"/test\", subdomain.root(), function(req, res) {}\n```\n\nThis route will no longer be valid when accessed through a subdomain.\n\nSubdomains in development mode\n----\n\nIf you need to test and develop locally, it is still possible to use this package.\n\nWhen NODE_ENV is set to development, an alternative regex is used that handles subdomains on localhost. More complex regex is used on production environments to determine the correct subdomain. \n\nSet the NODE_ENV environment to development.\n\n```\nprocess.env.NODE_ENV = \"development\"\n```\n\nThe chrome web browser supports using subdomains on localhost. You can test locally as follows:\n\n```\nhttp://subdomain.localhost:8080/\n```\n\n---\n\nRouter Example\n----\n```\nvar express = require(\"express\");\nvar path = require(\"path\");\nvar subdomain = require(\"subdomain-router-middleware\");\n\n// Define our express router object\nlet router = express.Router();\n\n// Initialise default subdomain parameters\nsubdomain.init({\n  asyncLoad: true,\n  asyncFunc: function() {\n    return new Promise((resolve, reject) =\u003e {\n      // Server call to retrieve subdomain for security token\n      const array = [\"subdomain1\", \"subdomain2\", \"subdomain3\"];\n      resolve(array);\n    });\n  },\n  error: {\n    success: false,\n    message: \"Invalid subdomain\"\n  }\n});\n\n// Express Route\nrouter.get(\"/test\", subdomain.route(), function(req, res) {\n  res.json({\n    success: true,\n    message: \"Endpoint loaded successfully\"\n  });\n});\n\nmodule.exports = router;\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpeterjoseph%2Fsubdomain-router-middleware","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpeterjoseph%2Fsubdomain-router-middleware","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpeterjoseph%2Fsubdomain-router-middleware/lists"}