nexpress-router

A familiar Express style method router for Next.js

Features

• Compatible with Express.js middleware and router.
• Works with async handlers (with error catching)
• Lightweight
• TypeScript support

Installation

npm install nexpress-router
// or
yarn add nexpress-router

Usage

nexpress-router was designed for use with Next.js API Routes:

// pages/api/hello-world.js
import nr from "nexpress-router";

const router = nr()
  .use(middleware())
  .get((req, res) => {
    res.send("Hello, world!");
  })
  .post((req, res) => {
    res.json({ hello: "world!" });
  })
  .put(async (req, res) => {
    res.end("async/await is also supported!");
  })
  .patch(async (req, res) => {
    throw new Error("Errors can be caught and handled.");
  });

export default router;

For quick migration from Custom Express server, simply replacing express() and express.Router() with nr() and follow the match multiple routes recipe.

For usage in pages with getServerSideProps, see .run.

TypeScript

By default, the base interfaces of req and res are IncomingMessage and ServerResponse. When using in API Routes, you would set them to NextApiRequest and NextApiResponse by providing the generics to the factory function like so:

import { NextApiRequest, NextApiResponse } from "next";
import nr from "nexpress-router";

const router = nr<NextApiRequest, NextApiResponse>();

You can also define custom properties to req and res (such as req.user or res.cookie) like so:

interface ExtendedRequest {
  user: string;
}
interface ExtendedResponse {
  cookie(name: string, value: string): void;
}

handler.post<ExtendedRequest, ExtendedResponse>((req, res) => {
  req.user = "Picard";
  res.cookie("sid", "8108");
});

API

The API is very similar to Express.js, but with some differences:

• It does not include any helper methods or template engine (you can incorporate them using middleware).
• It does not support error-handling middleware pattern. Use options.onError instead.

nr(options)

Initialize an instance of nexpress-router.

options.onError

Accepts a function as a catch-all error handler; executed whenever a middleware throws an error. By default, it responds with status code 500 and an error message if any.

type ErrorHandler<Req, Res> = (
  err: any,
  req: Req,
  res: Res,
  next: NextHandler // (err?: any) => void;
) => any | Promise<any>;

function onError(err, req, res, next) {
  logger.log(err);

  res.status(500).end(err.toString());
  // OR continue...
  next();
}

const router = nr({ onError });

router
  .use((req, res, next) => {
    throw new Error("Error occured!!");
    // or use next
    next(Error("Error occured!!"));
  })
  .use((req, res) => {
    // this will run if next() is called in onError
    res.end("no more error.");
  });

options.onNoMatch

Accepts a function of (req, res) as a handler when no route is matched. By default, it responds with 404 status and not found body.

function onNoMatch(req, res) {
  res.status(404).end("page is not found..!");
}

const router = nr({ onNoMatch });

options.attachParams

Passing true will attach params object to req. By default does not set to req.params.

const router = nr({ attachParams: true });

router.get("/users/:userId/posts/:postId", (req, res) => {
  // Visiting '/users/1/posts/14' will render '{"userId":"1","postId":"14"}'
  res.send(req.params);
});

.use(base, ...fn)

base (optional) - match all route to the right of base or match all if omitted.

fn(s) are functions of (req, res[, next]) or an instance of nexpress-router, where it will act as a sub application.

// Mount a middleware function
router.use((req, res, next) => {
  req.hello = "world!";
  next();
});

// Or include a base
router.use("/foo", fn); // Only run in /bar/**

// Mount an instance of nexpress-router
const common = nr().use(middleware1).use("/", middleware2);
const auth = nr().use("/home", authStuff);
const subapp = nr().get(getHandle).post("/bar", postHandle).put("/", putHandle);
router
  // `middleware1` and `middleware2` run everywhere
  .use(common)
  // `authStuff` ONLY runs on /home/*
  .use(auth)
  // `getHandle` runs on /foo/*
  // `postHandle` runs on /foo/bar
  // `putHandle` runs on /foo
  .use("/foo", subapp);

// You can use libraries aswell.
router.use(passport.initialize());

.METHOD(pattern, ...fns)

METHOD is an HTTP method (GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS, TRACE) in lowercase.

pattern (optional) - match all route based on supported pattern or match all if omitted.

fn(s) are functions of (req, res[, next]).

router.get("/api/user", (req, res, next) => {
  res.json(req.user);
});
router.post("/api/add-user", (req, res, next) => {
  res.end("User created");
});
router.put("/api/user/:id", (req, res, next) => {
  // https://nextjs.org/docs/routing/dynamic-routes
  res.end(`User ${req.query.id} updated`);
});
router.get((req, res, next) => {
  res.end("This matches whatever route");
});

.all(pattern, ...fns)

Same as .METHOD but accepts any methods.

.run(req, res)

Runs req and res the middleware and returns a promise. It will not render 404 on not found or onError on error.

This can be useful in getServerSideProps.

// page/index.js
export async function getServerSideProps({ req, res }) {
  const handler = nr().use(passport.initialize()).post(middleware);
  try {
    await handler.run(req, res);
  } catch (e) {
    // handle error
  }
  // do something with the new/upgraded req and res
  return {
    props: { user: req.user },
  };
}

More Goodies

Next.js

If you created the file /api/<specific-route>.js folder, the handler will only run on that specific route.

If you need to create all handlers for all routes in one file (similar to Express.js). You can use Optional catch all API routes.

// pages/api/[[...slug]].js
import nr from "nexpress-router";

const router = nr({ attachParams: true })
  .use("/api/hello", middleware())
  .get("/api/user/:userId", (req, res) => {
    res.send(`Hello ${req.params.userId}`);
  });

export default router;

While this allows quick migration from Express.js, it may be best to split routes into different files (/api/user/[userId].js, /api/hello.js) in the future.

Using in other frameworks

nexpress-router supports any frameworks and runtimes that support (req, res) => void handler.

const { send } = require("micro");
const nr = require("nexpress-router");

module.exports = nr()
  .use(middleware)
  .get((req, res) => {
    res.end("Hello, world!");
  })
  .post((req, res) => {
    send(res, 200, { hello: "world!" });
  });

const nr = require("nexpress-router");

module.exports = nr()
  .use(middleware)
  .get((req, res) => {
    res.send("Hello, world!");
  })
  .post((req, res) => {
    res.json({ hello: "world" });
  });

const http = require("http");
const nr = require("nexpress-router");

const router = nr()
  .use(middleware)
  .get((req, res) => {
    res.end("Hello, world!");
  })
  .post((req, res) => {
    res.setHeader("content-type", "application/json");
    res.end(JSON.stringify({ hello: "world" }));
  });

http.createServer(router).listen(PORT);

Contributing

Please see contributing.md.

License

MIT