You are browsing Nuxt 2 docs. Go to Nuxt 3 docs, or learn more about Nuxt 2 Long Term Support.

The serverMiddleware property

Define server-side middleware.


  • Type: Array
    • Items: String or Object or Function

Nuxt internally creates a connect instance that you can add your own custom middleware to. This allows us to register additional routes (typically /api routes) without need for an external server.

This allows you to create a client API/server API pattern using Nuxt alone. This means that from the browser (for example, within a Vue component) you can make a request to a route in your server middleware.

One benefit of this pattern is that the server middleware exists on the server (like most middleware), not on the client. This means that you can handle environment variables and secrets in the server middleware, without exposing that information to the user.

Because connect itself is a middleware, registered middleware will work with both nuxt start and also when used as a middleware with programmatic usages like express-template . Nuxt Modules can also provide serverMiddleware using this.addServerMiddleware()

Additional to them, we introduced a prefix option which defaults to true. It will add the router base to your server middlewares.

Example:

  • Server middleware path: /server-middleware
  • Router base: /admin
  • With prefix: true (default): /admin/server-middleware
  • With prefix: false: /server-middleware

serverMiddleware vs middleware!

Don't confuse it with routes middleware which are called before each route by Vue on the client and server. Middleware listed in the serverMiddleware property runs on the server before vue-server-renderer and can be used for server-specific tasks like handling API requests or serving assets.

Do not add serverMiddleware to the middleware/ directory.Middleware are bundled by webpack into your production bundle and run on beforeRouteEnter. If you add serverMiddleware to the middleware/ directory it will be wrongly picked up by Nuxt as middleware and will add wrong dependencies to your bundle or generate errors.

Usage

If middleware is String Nuxt will try to automatically resolve and require it.

nuxt.config.js
import serveStatic from 'serve-static'

export default {
  serverMiddleware: [
    // Will register redirect-ssl npm package
    'redirect-ssl',

    // Will register file from project server-middleware directory to handle /server-middleware/* requires
    { path: '/server-middleware', handler: '~/server-middleware/index.js' },

    // We can create custom instances too
    { path: '/static2', handler: serveStatic(__dirname + '/static2') }
  ]
}
If you don't want middleware to register for all routes, use the Object form with a specific path. If you don't do this, the nuxt default handler won't work!

Custom Server Middleware

It is also possible to write custom middleware. For more information See Connect Docs .

Middleware (server-middleware/logger.js):

server-middleware/logger.js
export default function (req, res, next) {
  // req is the Node.js http request object
  console.log(req.url)

  // res is the Node.js http response object

  // next is a function to call to invoke the next middleware
  // Don't forget to call next at the end if your middleware is not an endpoint!
  next()
}
nuxt.config.js
serverMiddleware: ['~/server-middleware/logger']

Custom API endpoint

A server middleware can also extend Express. This allows the creation of REST endpoints.

server-middleware/rest.js
const bodyParser = require('body-parser')
const app = require('express')()

app.use(bodyParser.json())
app.all('/getJSON', (req, res) => {
  res.json({ data: 'data' })
})

module.exports = app
nuxt.config.js
serverMiddleware: [
  { path: "/server-middleware", handler: "~/server-middleware/rest.js" },
],

Object Syntax

If your server middleware consists of a list of functions mapped to paths:

export default {
  serverMiddleware: [
    { path: '/a', handler: '~/server-middleware/a.js' },
    { path: '/b', handler: '~/server-middleware/b.js' },
    { path: '/c', handler: '~/server-middleware/c.js' }
  ]
}

You can alternatively pass an object to define them, as follows:

export default {
  serverMiddleware: {
    '/a': '~/server-middleware/a.js',
    '/b': '~/server-middleware/b.js',
    '/c': '~/server-middleware/c.js'
  }
}