{"id":15719,"library":"next-build-id","title":"Consistent Git-based Build ID for Next.js","description":"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.","status":"active","version":"3.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/nexdrew/next-build-id","tags":["javascript","next","next.js","build","id","BUILD_ID","git","head","describe"],"install":[{"cmd":"npm install next-build-id","lang":"bash","label":"npm"},{"cmd":"yarn add next-build-id","lang":"bash","label":"yarn"},{"cmd":"pnpm add next-build-id","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for generating build IDs from the local repository; not an npm package but an external program dependency.","package":"git","optional":false},{"reason":"Implicit peer dependency; the package is designed specifically for Next.js applications, integrating with its build process.","package":"next","optional":false}],"imports":[{"note":"The README examples use `require`, but ESM import is standard for modern Next.js configurations. The primary export is the asynchronous function.","wrong":"const nextBuildId = require('next-build-id');","symbol":"nextBuildId","correct":"import nextBuildId from 'next-build-id';"},{"note":"The synchronous version is exposed as a property on the default export, not a separate named export.","wrong":"import { sync as nextBuildIdSync } from 'next-build-id';","symbol":"nextBuildId.sync","correct":"import nextBuildId from 'next-build-id'; const buildIdSync = nextBuildId.sync({ dir: __dirname });"}],"quickstart":{"code":"// next.config.js\nconst nextBuildId = require('next-build-id');\n\n/** @type {import('next').NextConfig} */\nconst nextConfig = {\n  // Required to ensure consistent build IDs across multiple servers\n  // and prevent 'invalid build file hash' errors.\n  generateBuildId: async () => {\n    // Use the latest git commit hash as the build ID by default.\n    // Pass { describe: true } to use git tags instead (e.g., 'v1.0.0-19-ga8f7eee').\n    // The `dir` option should point to your project's root containing the .git folder.\n    return nextBuildId({ dir: __dirname });\n  },\n  // Other Next.js configurations here...\n};\n\nmodule.exports = nextConfig;","lang":"javascript","description":"Demonstrates how to integrate next-build-id into your Next.js configuration to generate a consistent, git-based build ID, preventing deployment issues."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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`.","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.","error":"Error: ENOENT: no such file or directory, open '/path/to/your/project/.next/BUILD_ID'"},{"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.","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.","error":"Next.js errors like \"invalid build file hash\""}],"ecosystem":"npm"}