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.
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
}
}
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.
$ npm i --save next-build-id
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"
}
}
This module exports a single function that accepts an options object and returns a Promise
.
The options supported are:
dir
(string): the directory built bynext build
write
(boolean): whether to overwrite the BUILD_ID in the dist dir (not needed when usinggenerateBuildId
in next.config.js)id
(string): define a custom id instead of deferring togit rev-parse HEAD
The returned Promise
resolves to a result object containing:
inputDir
(string): the resolved path of the Next.js appoutputDir
(string): the resolved path of thenext build
outputid
(string): the build id usedfiles
(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)
})
- zeit/next.js#786
- zeit/next.js#2978 (comment)
- zeit/next.js#3299 (comment)
- "Handle BUILD_ID Mismatch Error" on Next.js wiki
ISC © Andrew Goode