Neutron Polarization Manipulator

    TypeScript icon, indicating that this package has built-in type declarations

    2.0.5 • Public • Published


    GitHub release (latest by date)

    Flexible system-based file routing for Express with 0 dependencies.


    npm install express-file-routing

    Note: If you prefer yarn instead of npm, just use yarn add express-file-routing.

    How to use

    Fundamentally, there are two ways of adding this library to your codebase: either as a middleware app.use("/", router()), which will add a separate mini-router to your app, or by wrapping your whole Express instance with a createRouter(app), which will bind the routes directly to your app. In most cases, it doesn't matter on what option you decide, even though one or the other might perform better in some scenarios.

    • app.ts (main)
    import express from "express"
    import createRouter, { router } from "express-file-routing"
    const app = express()
    // Option 1
    app.use("/", router()) // as router middleware or
    // Option 2
    createRouter(app) // as wrapper function

    Note: It uses your project's /routes directory as source by default.

    • routes/index.ts
    export default async (req, res) => {
      if (req.method !== "GET") return res.status(405)
      return res.json({ hello: "world" })

    Directory Structure

    Files inside your project's /routes directory will get matched an url path automatically.

    ├── app.ts
    ├── routes
        ├── index.ts // index routes
        ├── posts
            ├── index.ts
            └── :id.ts or [id].ts // dynamic params
        └── users.ts
    └── package.json
    • /routes/index.ts → /
    • /routes/posts/index.ts → /posts
    • /routes/posts/[id].ts → /posts/:id
    • /routes/users.ts → /users

    Note: Files prefixed with an underscore or ending with .d.ts are excluded from route generation.


    createRouter(app, {
      directory: path.join(__dirname, "routes"),
      additionalMethods: ["ws", ...]
    // or
    app.use("/", router({
      directory: path.join(__dirname, "routes"),
      additionalMethods: ["ws", ...]


    • directory: The path to the routes directory (defaults to /routes)
    • additionalMethods: Additional methods that match an export from a route like ws (e.g. ws for express-ws)


    HTTP Method Matching

    If you export functions named e.g. get, post, put, patch, delete/del etc. those will get matched their corresponding http method automatically.

    export const get = async (req, res) => { ... }
    export const post = async (req, res) => { ... }
    // it's not allowed to name variables 'delete': try 'del' instead
    export const del = async (req, res) => { ... }
    // you can still use a wildcard default export in addition
    export default async (req, res) => { ... }

    Note: Named method exports gain priority over wildcard exports (= default exports).


    You can add isolated, route specific middlewares by exporting an array of Express request handlers from your route file.

    import { rateLimit, bearerToken, userAuth } from "../middlewares"
    export const get = [
      rateLimit(), bearerToken(), userAuth(),
      async (req, res) => { ... }

    A middleware function might look like the following:

    // middlewares/userAuth.ts
    export default (options) => async (req, res, next) => {
      if (req.authenticated) next()

    Custom Methods Exports

    You can add support for other method exports to your route files. This means that if your root app instance accepts non built-in handler invocations like, handler), you can make them being recognized as valid handlers.

    // app.ts
    import ws from "express-ws"
    const { app } = ws(express())
    createRouter(app, {
      additionalMethods: ["ws"]
    // routes/index.ts
    export const ws = async (ws, req) => {
      ws.send("hello world")

    Usage with TypeScript

    Adding support for route & method handler type definitions is as straightforward as including Express' native Handler type from @types/express.

    // routes/posts.ts
    import type { Handler } from "express"
    export const get: Handler = async (req, res, next) => { ... }

    Error Handling

    It is essential to catch potential errors (500s, 404s etc.) within your route handlers and forward them through next(err) if necessary, as treated in the Express' docs on error handling.

    Defining custom error-handling middleware functions should happen after applying your file-system routes.

    app.use("/", router()) // or createRouter(app)
    app.use(async (err, req, res, next) => {


    npm i express-file-routing

    DownloadsWeekly Downloads






    Unpacked Size

    26.5 kB

    Total Files


    Last publish


    • matthiaaas