Need private packages and team management tools?Check out npm Teams »

next-connect

0.6.6 • Public • Published

next-connect

npm install size CircleCI codecov PRs Welcome

The method routing and middleware layer for Next.js (also works in micro or Node.js HTTP Server). Powered by trouter.

Installation

npm install next-connect
// or
yarn add next-connect

Usage

next-connect is often used in API Routes:

// pages/api/index.js
import nextConnect from "next-connect";
 
const handler = nextConnect();
 
handler
  .use(someMiddleware())
  .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!');
  });
 
export default handler;

For usage in pages with getServerSideProps, see .apply.

See an example in nextjs-mongodb-app (CRUD, Authentication with Passport, and more)

API

The API is similar to Express.js with several differences.

nextConnect(options)

Initialize an instance of next-connect.

options.onError

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

function onError(err, req, res, next) {
  logger.log(err);
 
  res.status(500).end(err.toString());
  // OR: you may want to continue
  next()
}
 
const handler = nextConnect({ onError });
 
handler
  .use((req, res, next) => {
    throw new Error('oh no!');
    // or use next
    next(Error('oh no'));
  })
  .use((req, res) => {
    // this will run if next() is called in onError
    res.end('error no more');
  });

options.onNoMatch

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

function onNoMatch(req, res) {
  res.status(404).end('page is not found... or is it')
}
 
const handler = nextConnect({ onNoMatch });

.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 next-connect, where it will act as a sub application.

handler.use((req, res, next) => {
  req.hello = 'world';
  // call next if you want to proceed to next in chain
  next();
});
 
// Reuse an instance of nextConnect
const anotherHandler = nextConnect()
anotherHandler.use(commonFn).use(anotherFn);
handler.use(anotherHandler);
 
// You can use a library too.
handler.use(passport.initialize());

.METHOD(pattern, ...fns)

METHOD is a 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]). This is ideal to be used in API Routes.

handler.use('/user', passport.initialize());
handler.get('/user', (req, res, next) => {
  res.json(req.user);
});
handler.post('/users', (req, res, next) => {
  res.end('User created');
});
handler.put('/user/:id', (req, res, next) => {
  // https://nextjs.org/docs/routing/dynamic-routes
  res.end(`User ${req.query.id} updated`);
});
handler.get((req, res, next) => {
  res.end('This matchs whatever route')
})

However, since Next.js already handles routing (including dynamic routes), we often omit pattern in .METHOD.

.apply(req, res)

Applies the middleware and returns a promise after which you can use the upgraded req and res.

This can be useful in getServerSideProps.

// page/index.js
export async function getServerSideProps({ req, res }) {
  const handler = nextConnect();
  handler.use(passport.initialize());
  try {
    await handler.apply(req, res);
  } catch(e) {
    // handle the error
  }
  // do something with the upgraded req and res
  return {
    props: { user: req.user }, // will be passed to the page component as props
  }
};

Using in other frameworks

next-connect supports any frameworks that has the signature of (req, res).

Micro

const {send} = require('micro')
const handler = require('next-connect')()
 
handler
  .use(someMiddleware())
  .get(() => 'hello world')
  .post((req, res) => {
    send(res, 200, { hello: 'world' })
  });
 
module.exports = handler;

Node.js HTTP Server

const handler = require('next-connect')()
const http = require('http');
 
handler
  .use(someMiddleware())
  .get((req, res) => {
    res.end('Hello world');
  })
  .post((req, res) => {
    res.setHeader('content-type', 'application/json');
    res.end(JSON.stringify({ hello: 'world' }));
  });
 
http.createServer(handler).listen(PORT);

Contributing

Please see my contributing.md.

License

MIT

Install

npm i next-connect

DownloadsWeekly Downloads

2,784

Version

0.6.6

License

MIT

Unpacked Size

13.5 kB

Total Files

8

Last publish

Collaborators

  • avatar