Three months ago, Next.js released version 9, which added API Routes. This enabled us to write... well... APIs by exporting functions of two arguments req
and res
, which are extensions to Node's http.ClientRequest and http.ServerResponse.
This was a good excuse to move away from frameworks like Express as a custom server.
Still, something was missing: Middleware.
Middleware
Lots of us have probably learned the concept of middlewares when we worked with Express or Connect. The concept allowed us to augmented req
and res
by routing them through layers of a stack, which are known as middleware
.
The usage is somewhat like below:
app.use((req, res, next) => {
// Augmenting req
req.user = getUser(req);
// Go to the next layer
next();
});
More often, we find ourselves using libraries:
app.use(passport.initialize());
In those cases, the libraries actually return functions of (req, res, next)
just like the way we approached above.
However, in Next.js API Routes, we do not have such ability. We can only export a function of (req, res)
, there is no interfaces of app.use()
. This limitation led people back to using Express, thus rendering API Routes useless.
Possible solutions
Luckily, there are ways to achieve the similar behavior that is in Express.
Let's write some middles.
If you are unsure of which approach to go with, I recommend my next-connect.
Wrappers around handler function
I will define handler function as the function of (req, res)
that we need to export for API Routes.
Concept illustration in React
To illustrate the concept, I might use the term Higher-order component
(HOC) from React (even though it is a little bit misleading). If you use React, you may know the technique as something like the one below:
const EnhancedComponent = higherOrderComponent(WrappedComponent);
higherOrderComponent
will be something like below:
function higherOrderComponent(OriginalComponent) {
const user = getUser();
return (<OriginalComponent user={user} />);
}
In the above example, we wrap WrappedComponent
with higherOrderComponent
. Like the variable name suggests, it returned an enhanced version of the original component, not a different one. The only difference was that it added a prop to the original component. The HOC augmented the original component, not mutate it.
We can apply the concept into making a "HOC" for API Routes.
Making a middleware as a wrapper
I will take an (simplified) example from my project nextjs-mongodb-app. (check it out too)
const withDatabase = handler => {
return async (req, res) => {
await client.connect();
req.db = client.db('somedb');
return handler(req, res);
};
}
export default withDatabase;
Looking at the function withDatabase
, it accepts an argument called handler
, our original function. withDatabase
actually returns a function of (req, res)
(return async (req, res)
), which will accept the incoming requests. We can say that it replaces the original (req, res)
at this point.
Looking at the part:
req.db = client.db('somedb');
The incoming request (the original req
object) does not have db
, and we are adding it. Particularly, we are assigning db
into req
so we can access it later.
Now that we have augmented req
, we want to route it through our original handler
. Looking at return handler(req, res);
, we are calling the original handler
function we retrieve as an argument with the augmented req
and (eh, unchanged) res
.
Now in my original handler
, I can use the pass-along db
.
const handler = async (req, res) => {
const user = await req.db.findOne({ userName: req.body.username });
res.send(`Our homie is ${user.name}`);
}
Remember that withDatabase
needs handler
. We simply do withDatabase(handler)
. We now export
like so:
import withDatabase from '../middleware/withDatabase';
const handler = async (req, res) => {
const user = await req.db.findOne({ userName: req.body.username });
res.send(`Our homie is ${user.name}`);
}
export default withDatabase(handler);
// instead of export default handler;
What about an additional option? Let's say I want to specify the database to use. We can simply add it as the second argument. Let's rewrite our withDatabase
.
const withDatabase = (handler, dbToUse) => {
return async (req, res) => {
await client.connect();
req.db = client.db(dbToUse);
return handler(req, res);
};
}
Now back to our API Route file:
export default withDatabase(handler, 'testingDb');
Obviously, you can add as many arguments as you want, we only need to make sure to pass along our original handler
. You can look at another example at how I have options
in next-session.
Multiple middlewares
What about multiple middlewares? We can write similar functions to useDatabase
. Let's say we want a middleware to check the database's readiness.
const withCheckDb = (handler) {
return async (req, res) => {
req.dbHealth = await checkDatabase(req.db);
return handler(req, res);
}
}
Now that we have our additional withCheckDb
, we can wrap it along with withDatabase
.
export default withDatabase(withCheckDb(handler), 'testingDb');
One thing to be aware of is that withCheckDb
is inside withDatabase
. Why?
Looking at withCheckDb
, we see that it tries to access req.db
, which is only available after withDatabase
. The function on the outside will receive req
and res
first, and only when they are done that they pass them along into the inside ones.
So, order matters.
Stop the middleware chain early
Let's take another look at our withCheckDb
. What would happen if our database is not working? In such a case, I want it to simply respond with Database is not working
, ideally with a 500 status code.
const withCheckDb = (handler) {
return async (req, res) => {
req.dbHealth = await checkDatabase(req.db);
if (req.dbHealth === 'bad') return res.status(500).send('Database is not working :( so sorry! ');
return handler(req, res);
}
}
If the result of our checkDatabase
is bad, we send the message "Database is not working". More importantly, we also return
at that point, exiting the function. return handler(req, res);
is not executed because the function has existed/returned earlier.
By doing so, the actual handler
never run, thus the chain is cut short.
Mutate req and res directly
Another approach to middleware is to manipulate req
and res
directly. We can try to rewrite the above functions withDatabase
and withCheckDb
using this approach.
const useDatabase = async (req, res, dbToUse) => {
await client.connect();
req.db = client.db(dbToUse);
}
Instead of getting a handler
, we instead take req
and res
as arguments. Actually, we do not even need res
because we do not mutate it.
const useDatabase = async (req, dbToUse) => {
await client.connect();
req.db = client.db(dbToUse);
}
Let's go back to our handler.
import useDatabase from '../middleware/useDatabase';
const handler = async (req, res) => {
await useDatabase(req, 'testingDb');
const user = await req.db.findOne({ userName: req.body.username });
res.send(`Our homie is ${user.name}`);
}
export default handler;
By calling await useDatabase(req, 'testingDb');
, we mutate our req
by injecting our db
into it. I need to use await
because we need to wait for client.connect()
, followed by setting req.db
.
Without await
, the code will go on without req.db
and end up with a TypeError req.db is not defined
.
Multiple middleware
Let's do the same thing with withCheckDb
:
const useCheckDb = async (req, res) {
req.dbHealth = await checkDatabase(req.db);
if (req.dbHealth === 'bad') return res.status(500).send('Database is not working :( so sorry! ');
}
We need res
in this case since we call calling res.send
.
We can then go on to use multiple middlewares like so:
import useDatabase from '../middleware/useDatabase';
import useCheckDb from '../middleware/useCheckDb';
const handler = async (req, res) => {
await useDatabase(req, 'testingDb');
await useCheckDb(req, res);
const user = await req.db.findOne({ userName: req.body.username });
res.send(`Our homie is ${user.name}`);
}
export default handler;
Stop the middleware chain early
Remember that we want to stop the code if the database is not working. However, it does not just work with this approach.
useCheckDb
will still call res.status(500).send('Database is not working :( so sorry! ')
, but then the code go on. Chances are that the code will throw at req.db.findOne({ userName: req.body.username })
, or you will end up with Can't set headers after they are sent to the client
when you try to
res.send(`Our homie is ${user.name}`)
.
One way is to intentionally throw an error inside useCheckDb
const useCheckDb = async (req, res) {
req.dbHealth = await checkDatabase(req.db);
if (req.dbHealth === 'bad') throw new Error('Database is not working :( so sorry! ');
}
...and catch it with a Try/Catch.
import useDatabase from '../middleware/useDatabase';
import useCheckDb from '../middleware/useCheckDb';
const handler = async (req, res) => {
try {
await useDatabase(req, 'testingDb');
await useCheckDb(req, res);
const user = await req.db.findOne({ userName: req.body.username });
res.send(`Our homie is ${user.name}`);
} catch (e) {
res.status(500).send(e.message);
}
}
export default handler;
e.message
, in this case, will be "Database is not working :( so sorry!".
Middleware with next-connect
The two above approaches did not settle me, so I decided to write a library that will take me back to good ol' Express.js.
You can get it here.
With next-connect
, we can now use Express middleware syntax like we used to be.
import nextConnect from 'next-connect'
const handler = nextConnect();
handler.use(function (req, res, next) {
// Do some stuff with req and res here
req.user = getUser(req);
// Call next() to proceed to the next middleware in the chain
next();
})
handler.use(function (req, res) {
if (req.user) res.end(`The user is ${req.user.name}`);
else res.end('There is no user');
// next() is not called, the chain is terminated.
})
// You can use a library too.
handler.use(passport.initialize());
export default handler;
Method routing, too
What even better is that next-connect
also takes care of method handling. For example, you may want POST
request to be responded differently to PUT
request.
handler.post((req, res) => {
// Do whatever your lil' heart desires
});
handler.put((req, res) => {
// Do whatever your lil' heart desires
});
export default handler;
Example usage with next-connect
Anyway, let's get back on track. Let's try to replicate use/withDatabase
and use/withCheckDb
.
function database(dbToUse) {
return async (req, res, next) => {
await client.connect();
req.db = client.db(dbToUse);
// Calling next() and moving on!
next();
}
}
function checkDb() {
return async (req, res, next) => {
req.dbHealth = await checkDatabase(req.db);
if (req.dbHealth === 'bad') return res.status(500).send('Database is not working :( so sorry! ');
next();
}
}
The writing of the two functions are similar to our first approach. The only differences are that:
- We do not need to take in a
handler
argument - Our returned function has an additional
next
argument. - We finish by calling
next()
instead of callinghandler
.
What about suspending the code if checkDb
fail? Similarly to the first approach, next()
will not be called and whatever comes after it will not run.
For instruction on writing middlewares, here is a guide on expressjs.com.
Now, we can use it like we do in the old days of Express.js.
import nextConnect from 'next-connect'
import database from '../middleware/database';
import checkDb from '../middleware/checkDb';
const handler = nextConnect();
handler.use(database());
handler.use(checkDb());
handler.get((req, res) => {
const user = await req.db.findOne({ userName: req.body.username });
res.send(`Our homie is ${user.name}`);
});
export default handler;
What about non-API pages
We have been talking about API Routes (those in pages/api
), what about normal pages (those in pages/
). We can apply approach 2 to getInitialProps
.
Page.getInitialProps = async ({ req, res }) => {
await useMiddleware(req, res);
/* ... */
}
Document middleware
An RFC in Next.js issue #7208 enables the same approach as above but allowing it to be available globally.
It is an experimental feature and need to be enabled in nextjs.config.js
:
module.exports = {
experimental: {
documentMiddleware: true
}
};
Then, in _document.js
:
export const middleware = async ({ req, res }) => {
await useMiddleware(req, res);
};
Using next-connect
See this.
Conclusion
I hope this will help your effort on moving away from Express.js
. Moving away from Express.js
will allow our app to run faster by enabling Next.js
's optimization (and serverless, too!).
If you have any questions, feel free to leave a comment. I also recommend asking on Next.js channel on Spectrum to get answers from great people there.
Good luck on your next Next.js project!
Top comments (2)
One tip: If you want several middleware to be available on every page. Create a file (say,
withMiddleware.js
).This will apply to approach 1.
Then wrap whatever you need with
withMiddleware
.Approach 2, similar thing:
Why not just export the handler with middleware already applied to it? From the docs it seems like that's the recommended way to do it.