🚀Announcing Flightcontrol - Easily Deploy Blitz.js and Next.js to AWS 🚀
Back to Documentation Menu

blitz.config.js

Topics

Jump to a Topic

You can customize advanced behavior of Blitz with blitz.config.js or blitz.config.ts.

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:

import { PHASE_DEVELOPMENT_SERVER } from "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.

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 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",
}

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()
    },
  ],

Logging

Log Level

By default Blitz logs various things at runtime. You can adjust the verbosity using the log level setting.

  • Default: info
  • Options: trace | debug | info | warn | error | fatal
module.exports = {
  log: {
    level: "info",
  },
}

Log Type

It is also possible to adjust the logging type, which could be helpful if you prefer to forward the logs in JSON format.

  • Default: pretty
  • Options: pretty | json | hidden
module.exports = {
  log: {
    type: "pretty",
  },
}

Codegen

If you want to use custom templates with blitz generate instead of the default ones (e.g. with different styles), you can provide a path to the local template directory:

module.exports = {
  codegen: {
    templateDir: "./templates",
  },
}

The template directory should have the following structure:

.
├── form
│   └── __ModelName__Form.tsx
├── mutation
│   └── __input__.ts
├── mutations
│   ├── create__ModelName__.ts
│   ├── delete__ModelName__.ts
│   └── update__ModelName__.ts
├── page
│   ├── __modelIdParam__
│   │   └── edit.tsx
│   ├── __modelIdParam__.tsx
│   ├── index.tsx
│   └── new.tsx
├── queries
│   ├── get__ModelName__.ts
│   └── get__ModelNames__.ts
└── query
    └── __name__.ts

If some folders are omitted in your custom template directory, blitz generate will fallback to the default templates. You can check them out here.

CLI

Clear Console On Blitz Dev

When you run blitz dev, the console gets cleared. You can disable it by setting the cli.clearConsoleOnBlitzDev to false:

module.exports = {
  cli: {
    clearConsoleOnBlitzDev: false,
  },
}

Proxy support

Proxy support is enabled automatically for recipe install if either http_proxy or https_proxy environment variable is present. You can also set proxy using:

module.exports = {
  cli: {
    httpProxy: "http://127.0.0.1:8080",
    httpsProxy: "http://127.0.0.1:8080",
    noProxy: "localhost",
  },
}

Please note that proxy configuration in blitz.config.js will override environment proxy configuration.

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.js will automatically use your asset prefix for the JavaScript and CSS files it loads from the /_next/ path (.next/static/ folder). For example, with the above configuration, the following request for a JS chunk:

/_next/static/chunks/4b9b41aaa062cbbfeff4add70f256968c51ece5d.4d708494b3aed70c04f0.js

Would instead become:

https://cdn.mydomain.com/_next/static/chunks/4b9b41aaa062cbbfeff4add70f256968c51ece5d.4d708494b3aed70c04f0.js

The exact configuration for uploading your files to a given CDN will depend on your CDN of choice. The only folder you need to host on your CDN is the contents of .next/static/, which should be uploaded as _next/static/ as the above URL request indicates. Do not upload the rest of your .next/ folder, as you should not expose your server code and other configuration to the public.

While assetPrefix covers requests to _next/static, it does not influence the following paths:

  • Files in the public folder; if you want to serve those assets over a CDN, you'll have to introduce the prefix yourself
  • /_next/data/ requests for getServerSideProps pages. These requests will always be made against the main domain since they're not static.
  • /_next/data/ requests for getStaticProps pages. These requests will always be made against the main domain to support Incremental Static Generation, even if you're not using it (for consistency).

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 Blitz adds the x-powered-by header. To opt-out of it, disable the poweredByHeader config:

module.exports = {
  poweredByHeader: false,
}

Base Path

To deploy a Blitz application under a sub-path of a domain you can use the basePath config option.

basePath allows you to set a path prefix for the application. For example, to use /docs instead of / (the default), open blitz.config.js and add the basePath config:

module.exports = {
  basePath: "/docs",
}

Note: this value must be set at build time and can not be changed without re-building as the value is inlined in the client-side bundles.

When linking to other pages using Link and Router the basePath will be automatically applied.

For example using /about will automatically become /docs/about when basePath is set to /docs.

export default function HomePage() {
  return (
    <>
      <Link href={Routes.About()}>
        <a>About Page</a>
      </Link>
    </>
  )
}

Output html:

<a href="/docs/about">About Page</a>

This makes sure that you don't have to change all links in your application when changing the basePath value.

Trailing Slash

By default Blitz will redirect urls with trailing slashes to their counterpart without a trailing slash. For example /about/ will redirect to /about. You can configure this behavior to act the opposite way, where urls without trailing slashes are redirected to their counterparts with trailing slashes.

Open blitz.config.js and add the trailingSlash config:

module.exports = {
  trailingSlash: true,
}

With this option set, urls like /about will redirect to /about/.

Custom Server

You can setup and configure some items in the blitz config regarding custom servers. See the custom server documentation for full details.

Experimental

These features aren't ready for production and could change at any time.

React Root Mode

By default Blitz uses React Concurrent Mode. You can disable it by changing experimental.reactRoot to false.

  • Default: true
module.exports = {
  experimental: {
    reactRoot: false,
  },
}

Disabling HTTP Keep-Alive

Blitz.js automatically polyfills node-fetch and enables HTTP Keep-Alive by default. You may want to disable HTTP Keep-Alive for certain fetch() calls or globally.

For a single fetch() call, you can add the agent option:

import { Agent } from "https"

const url = "https://example.com"
const agent = new Agent({ keepAlive: false })
fetch(url, { agent })

To override all fetch() calls globally, you can use blitz.config.js:

module.exports = {
  httpAgentOptions: {
    keepAlive: false,
  },
}
Idea for improving this page? Edit it on GitHub.