Consistent Git-based Build ID for Next.js

3.0.0 · active · verified Tue Apr 21

next-build-id is a utility package for Next.js applications, currently at version 3.0.0. It addresses a common issue in multi-server deployments where different instances of a Next.js app might have varying build IDs, leading to "invalid build file hash" errors for clients. This package provides a mechanism to generate a consistent build ID, derived from the local Git repository's state, specifically the latest commit hash (`git rev-parse HEAD`) or a description based on the most recent Git tag (`git describe --tags`). It exports an asynchronous function (the primary export) and a synchronous variant, both intended to be used with Next.js's `generateBuildId` configuration option in `next.config.js`. The package helps ensure that all deployed instances of a Next.js application serve assets built with the same identifier, crucial for load-balanced environments without sticky sessions where apps are built directly on each server.

Common errors

```
Error: ENOENT: no such file or directory, open '/path/to/your/project/.next/BUILD_ID'
```
cause Next.js cannot find the `BUILD_ID` file, often because `next build` was not run, or the `.next` directory was deleted or not deployed with the application.

fix Ensure you run `npm run build` (or `yarn build`) before starting your Next.js application in production. Verify that the `.next` directory, including the `BUILD_ID` file, is correctly deployed to your server. This error can also occur if `next-build-id` fails to generate an ID due to missing `git`.
```
Next.js errors like "invalid build file hash"
```
cause This typically occurs in multi-server deployments where multiple instances of the Next.js application are running with different build IDs, causing clients to receive inconsistent assets.

fix Implement `next-build-id` in your `next.config.js`'s `generateBuildId` function to ensure all deployed instances of your Next.js application use a consistent, git-based build ID. This is critical for load-balanced environments without session affinity.

Warnings

gotcha This package relies on the `git` command being available in the environment where `next build` is executed. If `git` is not installed or accessible (e.g., in a minimal Docker image), build ID generation will fail.
Fix: Ensure `git` is installed and in the system's PATH during the build process. For Docker, add `RUN apt-get update && apt-get install -y git` or equivalent for your base image.
gotcha The `dir` option should correctly point to a directory within your local Git repository, typically the project root. Using `__dirname` from `next.config.js` is generally safe, but incorrect paths can lead to failed or unexpected build IDs.
Fix: Verify that the `dir` option resolves to a path containing the `.git` directory relevant to your project's version control. For monorepos, this might require adjusting the path relative to the `next.config.js` location.
gotcha When using `describe: true` for tag-based build IDs, if no Git tags exist in the repository, it will fallback to the latest commit SHA unless `fallbackToSha: false` is explicitly set. This can lead to unexpected build ID formats if tags are expected but not present.
Fix: Ensure your repository has relevant Git tags if you rely on the `describe` option. If strict tag usage is required, set `fallbackToSha: false` to force an error when no tags are found.
gotcha Next.js's internal build ID behavior is subject to change, especially with new bundlers like Turbopack. Relying heavily on `BUILD_ID` for external systems (e.g., release names in Sentry) might require adjustments in future Next.js versions.
Fix: Monitor Next.js release notes for changes related to build ID generation. For critical integrations, consider direct Git SHA retrieval rather than relying solely on the Next.js `generateBuildId` hook for custom release tracking.

Install

npm install next-build-id npm
yarn add next-build-id yarn
pnpm add next-build-id pnpm

Imports

nextBuildId
wrong:
```
const nextBuildId = require('next-build-id');
```
correct:
```
import nextBuildId from 'next-build-id';
```
The README examples use `require`, but ESM import is standard for modern Next.js configurations. The primary export is the asynchronous function.

nextBuildId.sync

wrong:

import { sync as nextBuildIdSync } from 'next-build-id';

correct:

import nextBuildId from 'next-build-id'; const buildIdSync = nextBuildId.sync({ dir: __dirname });

The synchronous version is exposed as a property on the default export, not a separate named export.

Quickstart

Demonstrates how to integrate next-build-id into your Next.js configuration to generate a consistent, git-based build ID, preventing deployment issues.

// next.config.js
const nextBuildId = require('next-build-id');

/** @type {import('next').NextConfig} */
const nextConfig = {
  // Required to ensure consistent build IDs across multiple servers
  // and prevent 'invalid build file hash' errors.
  generateBuildId: async () => {
    // Use the latest git commit hash as the build ID by default.
    // Pass { describe: true } to use git tags instead (e.g., 'v1.0.0-19-ga8f7eee').
    // The `dir` option should point to your project's root containing the .git folder.
    return nextBuildId({ dir: __dirname });
  },
  // Other Next.js configurations here...
};

module.exports = nextConfig;

view raw JSON →