{"id":15428,"library":"dev-build-release","title":"Development Build Release Automation","description":"The `dev-build-release` package is a suite of command-line tools designed to automate versioning for development and feature branch releases within JavaScript/TypeScript projects. Its primary utility, `dev-build-release`, modifies the `package.json` version string by appending build numbers and branch names, following a structured schema (e.g., `1.0.0-feat-branch.123`). This functionality is essential for maintaining distinct pre-release versions in continuous integration and delivery (CI/CD) environments. The package also includes `determine-version`, which assists in identifying downstream dependent repositories that may require updates based on the current project's version, and `generate-version-file`, a tool that creates a `version.json` file containing detailed build information derived from `package.json` and, optionally, CI variables from systems like Jenkins or GitLab. Currently at version `0.1.6`, the project demonstrates a moderate release cadence, focusing on compatibility fixes, such as adapting to older JavaScript engines by internally replacing `replaceAll` with `replace`, and enhancing integration with diverse CI systems. Its key differentiator is its ability to streamline the often-complex process of consistent development versioning, removing the need for manual intervention and proving particularly valuable for workflows that rely heavily on feature branches.","status":"active","version":"0.1.6","language":"javascript","source_language":"en","source_url":"https://github.com/jgodi/dev-build-release","tags":["javascript","npm","release","dev"],"install":[{"cmd":"npm install dev-build-release","lang":"bash","label":"npm"},{"cmd":"yarn add dev-build-release","lang":"bash","label":"yarn"},{"cmd":"pnpm add dev-build-release","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for the 'determine-version' post-commit git hook functionality.","package":"ghooks","optional":true}],"imports":[{"note":"This package primarily exposes command-line interfaces (CLIs) via its `bin` entry points. It is not intended for direct programmatic import.","wrong":"import devBuildRelease from 'dev-build-release';","symbol":"dev-build-release (CLI)","correct":"npx dev-build-release -b BUILD_NUMBER -g BRANCH_NAME"},{"note":"Invoke directly via `npx` or by configuring a script in `package.json` that points to the binary in `node_modules/.bin/`.","wrong":"const determineVersion = require('dev-build-release/bin/determine-version');","symbol":"determine-version (CLI)","correct":"npx determine-version -p comma-delimited,list,of-parent-repos"},{"note":"Typically used as a post-build step in CI/CD pipelines, often configured via an npm script (e.g., `npm run version-file`).","wrong":"import { generateVersionFile } from 'dev-build-release';","symbol":"generate-version-file (CLI)","correct":"npx generate-version-file"}],"quickstart":{"code":"{\n  \"name\": \"my-project\",\n  \"version\": \"1.0.0\",\n  \"description\": \"A sample project\",\n  \"scripts\": {\n    \"version-file\": \"node ./node_modules/dev-build-release/bin/generate-version-file\",\n    \"postbuild\": \"npm run version-file\",\n    \"prestart\": \"npm run version-file\"\n  },\n  \"devDependencies\": {\n    \"dev-build-release\": \"^0.1.6\"\n  }\n}\n\n// To install:\n// npm install dev-build-release --save-dev\n\n// Simulate running dev-build-release to update package.json version\nconsole.log(\"\\n--- Simulating: npx dev-build-release -b 456 -g feature/my-new-feature ---\");\n// In a real shell, this would update package.json to \"1.0.0-feature-my-new-feature.456\"\n// For demonstration, imagine the file is updated.\n\n// Simulate generating version.json after a build\nconsole.log(\"\\n--- Simulating: npm run version-file (via postbuild or prestart hook) ---\");\n// This command, if run in a project with the above package.json, \n// would create a 'version.json' file in the root with content like:\n/*\n{\n  \"version\": \"1.0.0-feature-my-new-feature.456\",\n  \"buildNumber\": \"456\",\n  \"branchName\": \"feature-my-new-feature\",\n  \"buildType\": \"feature\"\n}\n*/\nconsole.log(\"Check your 'package.json' for version updates and 'version.json' for generated info after running these commands in a real project.\");","lang":"typescript","description":"This quickstart demonstrates installing `dev-build-release` as a dev dependency and shows how to use its main CLI commands: `dev-build-release` for modifying `package.json` version, and `generate-version-file` via an npm script to create a `version.json` artifact."},"warnings":[{"fix":"Update any CI/CD scripts, build processes, or dependent consumers that parse the version string to expect the new `feat-newFeature` hyphenated format for branch names.","message":"The convention for including branch names in the version string changed. Previously, only the last segment of a branch name (e.g., 'newFeature' from 'feat/newFeature') was used. Now, the full branch path is included with forward slashes replaced by hyphens (e.g., 'feat-newFeature'). This impacts any parsing logic downstream.","severity":"breaking","affected_versions":">=0.1.3"},{"fix":"Ensure your Node.js environment is compatible with the package's requirements. This change specifically broadens compatibility, so users on older Node.js versions might find previous issues resolved.","message":"The internal implementation for string replacement was changed from `.replaceAll()` to `.replace()` with a global regex flag to support older JavaScript environments. While this is a compatibility fix, it highlights potential runtime environment considerations.","severity":"gotcha","affected_versions":">=0.1.4"},{"fix":"Review your CI/CD configuration to ensure that the correct environment variables (Jenkins or GitLab) are exposed and named appropriately for `generate-version-file` to pick up the desired build information.","message":"The `generate-version-file` utility has updated its logic to prioritize GitLab pipeline variables for populating build information if Jenkins variables are not available. This might affect CI/CD setups relying exclusively on Jenkins or specific variable naming conventions.","severity":"gotcha","affected_versions":">=0.1.5"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"To run directly, use `npx dev-build-release ...`. If using within npm scripts, ensure the script references `node ./node_modules/dev-build-release/bin/dev-build-release` or relies on `node_modules/.bin` being in the PATH (which npm handles for scripts).","cause":"The CLI tool's binary is not globally installed, not in the PATH, or `npx` was not used.","error":"Error: Command 'dev-build-release' not found"},{"fix":"Navigate to the root directory of your project where `package.json` is located before running any `dev-build-release` commands.","cause":"The `dev-build-release` or related commands (`determine-version`, `generate-version-file`) must be executed in a directory that contains a `package.json` file.","error":"Error: ENOENT: no such file or directory, open 'package.json'"},{"fix":"Adjust any scripts or logic that consume the generated version string to expect hyphens (`-`) instead of forward slashes (`/`) in the branch name segment (e.g., `feat-myFeature` instead of `feat/myFeature`).","cause":"This typically occurs after upgrading to `dev-build-release` v0.1.3 or later, which changed how branch names with slashes are formatted in the version string.","error":"Version string generated with unexpected branch format: 'feat/myFeature' instead of 'feat-myFeature'."}],"ecosystem":"npm"}