npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

express-file-routing

v3.0.3

Published

Simple file-based routing for Express

Downloads

5,838

Readme

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("/", await router()), which will add a separate mini-router to your app, or by wrapping your whole Express instance with a await 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("/", await router()) // as router middleware or

// Option 2
await createRouter(app) // as wrapper function

app.listen(2000)

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

  • routes/index.ts
export const get = 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

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

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)
  • routerOptions: Native Express Router Options objects forwarded as-is to the underlying router

Examples

HTTP Method Matching

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

export const get = async (req, res) => { ... }

export const post = async (req, res) => { ... }

// since it's not allowed to name constants '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.

// routes/dashboard
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())

await 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("/", await router()) // or await createRouter(app)

app.use(async (err, req, res, next) => {
  ...
})

Catch-All (unstable)

This library lets you extend dynamic routes to catch-all routes by prefixing it with three dots ... inside the brackets. This will make that route match itself but also all subsequent routes within that route.

Note: Since this feature got added recently, it might be unstable. Feedback is welcome.

// routes/users/[...catchall].js
export const get = async (req, res) => {
  return res.json({ path: req.params[0] })
}
  • routes/users/[...catchall].js matches /users/a, /users/a/b and so on, but not /users.

Migrating from v2

The latest version v3 fixed stable support for ESM & CJS compatibility. But also introduced a breaking change in the library's API. To upgrade, first install the latest version from npm.

Upgrade version

npm install express-file-routing@latest

Await the router

Registering the file-router in v2 was synchronous. Newer versions require you to await the router. So the only change in your codebase will be to await the router instead of calling it synchronously:

const app = express()

- app.use(router())
+ app.use(await router())

app.listen(2000)

Or if you were using createRouter():

const app = express()

- createRouter(app)
+ await createRouter(app)

app.listen(2000)

Note: If you environment does not support top-level await, you might need to wrap you code in an async function.