booee / next-build-id

Easily set your `next build` BUILD_ID to the latest git commit hash

next-build-id

Override next build output to use a consistent build id

Simple CLI and module that lets you define your own build id when using Next.js.

New in version 2!

When using Next.js 6+ (which introduced the generateBuildId config prop), you can use next-build-id as a module within your next.config.js logic to set the BUILD_ID to the most recent git commit hash. This approach means you don't need to use the next-build-id CLI - just use next build as normal and you'll get the build id you want!

// next.config.js
const nextBuildId = require('next-build-id')
module.exports = {
  generateBuildId: async () => {
    const fromGit = await nextBuildId({ dir: __dirname })
    return fromGit.id
  }
}

Intro

This tool is necessary if you're running multiple instances of your Next.js app on different servers sitting behind a load balancer without session affinity. Otherwise, if your Next.js builds end up with different build ids, a client loading content from different servers can result in this Next.js error, which causes the app to blow up for that client.

This module updates/overrides the following:

• uuid defined in .next/BUILD_ID
• hashes for all chunks defined in .next/build-stats.json (Next.js 4 or below)

By default, this CLI/module will overwrite those values with the hash of the latest git commit (git rev-parse HEAD), but it will also allow you to define your own id.

If you have distDir defined in a next.config.js file, it will be respected. Otherwise, this module assumes the Next.js build output is in a relative .next directory.

Install

$ npm i --save next-build-id

CLI Usage

Modify your build script to run next-build-id after next build (only needed for production builds).

For instance, if you have an npm run script in package.json that looks like this:

{
  "scripts": {
    "build": "next build"
  }
}

You can change it to this:

{
  "scripts": {
    "build": "next build && next-build-id"
  }
}

The above example will use the hash of the latest git commit as the build id. If you'd like to define your own build id, pass it to the CLI using the --id flag:

{
  "scripts": {
    "build": "next build && next-build-id --id $MY_CUSTOM_ID"
  }
}

If you are building a directory other than the project root, you can pass that as an argument, just like you do with next build:

{
  "scripts": {
    "build": "next build client && next-build-id client"
  }
}

Module Usage

This module exports a single function that accepts an options object and returns a Promise.

The options supported are:

• dir (string): the directory built by next build
• write (boolean): whether to overwrite the BUILD_ID in the dist dir (not needed when using generateBuildId in next.config.js)
• id (string): define a custom id instead of deferring to git rev-parse HEAD

The returned Promise resolves to a result object containing:

• inputDir (string): the resolved path of the Next.js app
• outputDir (string): the resolved path of the next build output
• id (string): the build id used
• files (array of strings): resolved paths of each file updated with the build id

Example:

const nextBuildId = require('next-build-id')

const opts = {}
// opts.dir = '/path/to/input/dir'
// opts.write = true
// opts.id = 'my_custom_id'

nextBuildId(opts).then(result => {
  console.log('success!')
  console.log('input dir:', result.inputDir)
  console.log('output dir:', result.outputDir)
  console.log('build id:', result.id)
  console.log('updated files:', result.files)
}).catch(err => {
  console.error('you broke it', err)
})

Reference

• zeit/next.js#786
• zeit/next.js#2978 (comment)
• zeit/next.js#3299 (comment)
• "Handle BUILD_ID Mismatch Error" on Next.js wiki

License

ISC © Andrew Goode