blitz.config.js

You can customize advanced behavior of Blitz with

blitz.config.js.

blitz.config.js is a regular Node.js module, not a JSON file. It gets used by the Blitz server and build phases, and it's not included in the browser build.

Take a look at the following

blitz.config.js example:

module.exports = {
  /* config options here */
}

You can also use a function:

module.exports = (phase, {defaultConfig}) => {
  return {
    /* config options here */
  }
}

phase is the current context in which the configuration is loaded. You can see the available phases here. Phases can be imported from next/constants:

const {PHASE_DEVELOPMENT_SERVER} = require("next/constants")
module.exports = (phase, {defaultConfig}) => {
  if (phase === PHASE_DEVELOPMENT_SERVER) {
    return {
      /* development only config options here */
    }
  }
  return {
    /* config options for all phases except development here */
  }
}

The commented lines are the place where you can put the configs allowed by

blitz.config.js, which are defined here.

However, none of the configs are required, and it's not necessary to understand what each config does, instead, search for the features you need to enable or modify in this section and they will show you what to do.

Avoid using new JavaScript features not available in your target Node.js version.

blitz.config.js will not be parsed by Webpack, Babel or TypeScript.

Webpack Config

You can customize the Blitz webpack config. See

our webpack documentation for details

Build Target

Blitz supports various build targets, each changing the way your application is built and run. We'll explain each of the targets below.

server target

Your application will be built and deployed as a monolith. This is the default target and no action is required on your part to opt-in.

serverless target

This target will output independent pages that don't require a monolithic server.

It's only compatible with

blitz start --production or Serverless deployment platforms (like Vercel) — you cannot use the custom server API.

To opt-into this target, set the following configuration in your

blitz.config.js:

module.exports = {
  target: "serverless",
}

Deployments to

Vercel will automatically enable this target. You should not opt-into it yourself.

Middleware

HTTP middleware can be added queries and mutations.

See the middleware documentation for full details.

module.exports = {
  middleware: [
    (req, res, next) => {
      res.blitzCtx.referer = req.headers.referer
      return next()
    },
  ],

CDN Support with Asset Prefix

To set up a

CDN, you can set up an asset prefix and configure your CDN's origin to resolve to the domain that Blitz is hosted on.

const isProd = process.env.NODE_ENV === "production"
module.exports = {
  // Use the CDN in production and localhost for development.
  assetPrefix: isProd ? "https://cdn.mydomain.com" : "",
}

Blitz will automatically use your prefix in the scripts it loads, but this has no effect whatsoever on the

public folder; if you want to serve those assets over a CDN, you'll have to introduce the prefix yourself. One way of introducing a prefix that works inside your components and varies by environment is documented in this example.

Custom Page Extensions

Aimed at modules like

@next/mdx, which adds support for pages ending with .mdx. You can configure the extensions looked for in the pages directory when resolving pages.

module.exports = {
  pageExtensions: ["mdx", "jsx", "js", "ts", "tsx"],
}

Static Optimization Indicator

When a page qualifies for

Automatic Static Optimization we show an indicator to let you know.

This is helpful since automatic static optimization can be very beneficial and knowing immediately in development if the page qualifies can be useful.

In some cases this indicator might not be useful, like when working on electron applications.

module.exports = {
  devIndicators: {
    autoPrerender: false,
  },
}

Configuring onDemandEntries for Development

Blitz exposes some options that give you some control over how the server will dispose or keep in memory built pages in development.

module.exports = {
  onDemandEntries: {
    // period (in ms) where the server will keep pages in the buffer
    maxInactiveAge: 25 * 1000,
    // number of pages that should be kept simultaneously without being disposed
    pagesBufferLength: 2,
  },
}

Setting a custom build directory

You can specify a name to use for a custom build directory to use instead of

.next.

module.exports = {
  distDir: "build",
}

Now if you run

blitz build Blitz will use build instead of the default .next folder.

distDir should not leave your project directory. For example, ../build is an invalid directory.

Configuring the Build ID

Blitz uses a constant id generated at build time to identify which version of your application is being served. This can cause problems in multi-server deployments when

blitz build is ran on every server. In order to keep a static build id between builds you can provide your own build id.

module.exports = {
  generateBuildId: async () => {
    // You can, for example, get the latest git commit hash here
    return "my-build-id"
  },
}

Compression

Blitz provides

gzip compression to compress rendered content and static files. Compression only works with the server target. In general you will want to enable compression on a HTTP proxy like nginx, to offload load from the Node.js process.

module.exports = {
  compress: false,
}

Disabling ETag Generation

By default we generate

etags for every page by default. You may want to disable etag generation for HTML pages depending on your cache strategy.

module.exports = {
  generateEtags: false,
}

Disabling x-powered-by

By default Next.js adds the

x-powered-by header. To opt-out of it, disable the poweredByHeader config:

module.exports = {
  poweredByHeader: false,
}