{"id":12924,"library":"build-number-generator","title":"Build Number Generator","description":"build-number-generator is a utility that creates unique, human-readable build numbers for software projects. These nine-digit integers encode the build date (YYMMDD) and a count of two-minute intervals after midnight (CCC), ensuring uniqueness for builds at least two minutes apart. The current stable version is 3.0.0, released on 2025-06-26. The package offers both a command-line interface and an API for programmatic use in Node.js, Deno, and web browsers, supporting ESM, CJS, and UMD formats. Key differentiators include its no-dependency footprint, tiny size, and the ability to infer the build time directly from the number without external storage, making it suitable for CI/CD environments. It ships with full TypeScript types.","status":"active","version":"3.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/prantlf/build-number-generator","tags":["javascript","buildnumber","build-number","build","number","version","generator","typescript"],"install":[{"cmd":"npm install build-number-generator","lang":"bash","label":"npm"},{"cmd":"yarn add build-number-generator","lang":"bash","label":"yarn"},{"cmd":"pnpm add build-number-generator","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"ESM is the primary export since v2.0.0, CJS is available but direct require() is discouraged for newer Node.js versions. v3.x explicitly requires Node.js >=18.","wrong":"const generate = require('build-number-generator')","symbol":"generate","correct":"import { generate } from 'build-number-generator'"},{"note":"This is a named export; a default import is not provided for the core functions.","wrong":"import parse from 'build-number-generator'","symbol":"parse","correct":"import { parse } from 'build-number-generator'"},{"note":"Used to check if a string is a valid build number generated by this library.","symbol":"validate","correct":"import { validate } from 'build-number-generator'"}],"quickstart":{"code":"import { generate, parse } from 'build-number-generator';\n\nasync function runBuildProcess() {\n  const productVersion = '1.2.3';\n  const buildNumber = generate();\n\n  console.log(`Generated build number: ${buildNumber}`);\n  console.log(`Full version string: ${productVersion}.${buildNumber}`);\n\n  const parsedDate = parse(buildNumber);\n  console.log(`Build number ${buildNumber} corresponds to: ${parsedDate.toDateString()} ${parsedDate.toLocaleTimeString()}`);\n\n  const invalidBuildNumber = '12345'; // Too short\n  try {\n    parse(invalidBuildNumber);\n  } catch (error: any) {\n    console.log(`Attempted to parse invalid build number '${invalidBuildNumber}': ${error.message}`);\n  }\n}\n\nrunBuildProcess();","lang":"typescript","description":"This quickstart demonstrates generating a new build number, combining it with a product version, and then parsing a build number back into a human-readable date. It also shows error handling for invalid build numbers."},"warnings":[{"fix":"Ensure your project runs on Node.js 18 or newer. If you must use older Node.js versions, consider pinning to `build-number-generator@^2.0.0` or `^1.0.0` depending on your specific Node.js version requirements (e.g., v1.x for Node.js < 14.8).","message":"Version 3.0.0 introduced a breaking change by upgrading dependencies and raising the minimum supported Node.js version. It now requires Node.js >=18.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Upgrade your Node.js environment to at least version 14.8, or preferably 16+. If using Node.js < 14.8, you must stick to `build-number-generator@^1.0.0`.","message":"Version 2.0.0 removed the `commander` dependency and modernized the project, aligning with newer Node.js features. This also implicitly raised the minimum Node.js version requirement for full compatibility (specifically for ESM and some internal modernizations).","severity":"breaking","affected_versions":">=2.0.0 <3.0.0"},{"fix":"For CLI usage, ensure global installation or verify that your local `node_modules/.bin` symlinks are correctly resolving. For programmatic CJS usage, stick to named exports or use ESM where possible.","message":"The `build-number-generator` CLI tool (`buildnumgen`) changed its CJS export paths and bin script paths in patch versions of v2.0.x (e.g., v2.0.3). While generally transparent, this could affect some very specific build setups or older package managers resolving paths explicitly.","severity":"gotcha","affected_versions":">=2.0.0 <2.0.4"},{"fix":"If experiencing TypeScript errors with `build-number-generator@2.x`, upgrade to `build-number-generator@^2.0.4` or later to ensure correct type definitions are included and referenced in `package.json` exports.","message":"TypeScript types for the package were initially missing or incorrectly included in published packages in early v2.x releases (e.g., v2.0.1, v2.0.2). This was corrected in later patch versions.","severity":"gotcha","affected_versions":">=2.0.0 <2.0.4"},{"fix":"Factor this design choice into your versioning strategy. If sub-two-minute uniqueness is critical, append an additional unique identifier (e.g., commit hash, incrementing counter) to the generated build number, or ensure builds are spaced out.","message":"The generated build numbers are unique per a two-minute interval. If your CI/CD pipeline performs multiple builds within the same two-minute window, they will receive the *same* build number. This is by design.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure the package is installed (`npm install build-number-generator`). If using Node.js < 14.8, you must use version 1.x. For Node.js >=18, use version 3.x and ensure you're using `import` statements for ESM.","cause":"Attempting to `require()` or `import` the package without it being installed, or with a Node.js version that does not support its module format.","error":"Error: Cannot find module 'build-number-generator'"},{"fix":"Use named ESM imports: `import { generate } from 'build-number-generator';`. If you are stuck on an older Node.js version requiring CJS, verify `package.json` `exports` or ensure you are using a compatible package version (e.g., v1.x).","cause":"Incorrect import statement, often trying to use CommonJS `require` syntax (`const generate = require('build-number-generator')`) when the package is primarily ESM, or attempting a default import when only named exports are provided.","error":"TypeError: generate is not a function"},{"fix":"Always wrap calls to `parse()` in a `try...catch` block, or validate the build number first using `validate()` before parsing, especially if the input is user-supplied or external.","cause":"Attempting to call `.toDateString()` on the result of `parse()` when `parse()` received an invalid build number and threw an error, which was not caught.","error":"TypeError: Cannot read properties of undefined (reading 'toDateString')"},{"fix":"Ensure the input string is exactly 9 digits long and conforms to the YYMMDDCCC pattern (e.g., `240419123` for April 19, 2024). This error also occurs if the numeric value exceeds `235929999`.","cause":"The string passed to `parse()` or `validate()` does not match the expected 9-digit BCD format.","error":"Error: build number 'YYYYMMDDCCC' does not comply with the 'YYYYMMDDCCC' format"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"build-number-generator"}