next-build-id

library3.0.0jsnpmunverified

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.

devops

npm install next-build-id

github ↗package ↗

INSTALL

IMPORT

SIG · NEXT-BUILD-ID

next-build-id

devopsjavascriptv3.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

nextBuildId

✓ import nextBuildId from 'next-build-id';

✗ const nextBuildId = require('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

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

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

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

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;

Debug

Known issues

gotchaThis 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.

affects: >=1.0.0

gotchaThe `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.

affects: >=1.0.0

gotchaWhen 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.

affects: >=1.0.0

gotchaNext.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.

affects: >=1.0.0

Errors

Common errors & fixes

Error: ENOENT: no such file or directory, open '/path/to/your/project/.next/BUILD_ID'

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"

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.

Upgrade

Version history

3.0.0latest on npm

Audit

Dependencies

gitrequiredRequired for generating build IDs from the local repository; not an npm package but an external program dependency.

nextrequiredImplicit peer dependency; the package is designed specifically for Next.js applications, integrating with its build process.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/nexdrew/next-build-id ↗

packagehttps://www.npmjs.com/package/next-build-id ↗