Neutron Polarization Manipulator

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

    2.0.5 • Public • Published

    express-file-routing

    GitHub release (latest by date)

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

    Installation

    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
    
    app.listen(2000)

    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.

    API

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

    Options

    • 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)

    Examples

    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).

    Middlewares

    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 app.ws(route, 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) => {
    
    })

    Install

    npm i express-file-routing

    DownloadsWeekly Downloads

    303

    Version

    2.0.5

    License

    MIT

    Unpacked Size

    26.5 kB

    Total Files

    10

    Last publish

    Collaborators

    • matthiaaas