Development Build Release Automation

0.1.6 · active · verified Tue Apr 21

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.

Common errors

```
Error: Command 'dev-build-release' not found
```
cause The CLI tool's binary is not globally installed, not in the PATH, or `npx` was not used.

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).
```
Error: ENOENT: no such file or directory, open 'package.json'
```
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.

fix Navigate to the root directory of your project where `package.json` is located before running any `dev-build-release` commands.
```
Version string generated with unexpected branch format: '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.

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

Warnings

breaking 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.
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.
gotcha 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.
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.
gotcha 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.
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.

Install

npm install dev-build-release npm
yarn add dev-build-release yarn
pnpm add dev-build-release pnpm

Imports

dev-build-release (CLI)
wrong:
```
import devBuildRelease from 'dev-build-release';
```
correct:
```
npx dev-build-release -b BUILD_NUMBER -g BRANCH_NAME
```
This package primarily exposes command-line interfaces (CLIs) via its `bin` entry points. It is not intended for direct programmatic import.
determine-version (CLI)
wrong:
```
const determineVersion = require('dev-build-release/bin/determine-version');
```
correct:
```
npx determine-version -p comma-delimited,list,of-parent-repos
```
Invoke directly via `npx` or by configuring a script in `package.json` that points to the binary in `node_modules/.bin/`.
generate-version-file (CLI)
wrong:
```
import { generateVersionFile } from 'dev-build-release';
```
correct:
```
npx generate-version-file
```
Typically used as a post-build step in CI/CD pipelines, often configured via an npm script (e.g., `npm run version-file`).

Quickstart

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.

{
  "name": "my-project",
  "version": "1.0.0",
  "description": "A sample project",
  "scripts": {
    "version-file": "node ./node_modules/dev-build-release/bin/generate-version-file",
    "postbuild": "npm run version-file",
    "prestart": "npm run version-file"
  },
  "devDependencies": {
    "dev-build-release": "^0.1.6"
  }
}

// To install:
// npm install dev-build-release --save-dev

// Simulate running dev-build-release to update package.json version
console.log("\n--- Simulating: npx dev-build-release -b 456 -g feature/my-new-feature ---");
// In a real shell, this would update package.json to "1.0.0-feature-my-new-feature.456"
// For demonstration, imagine the file is updated.

// Simulate generating version.json after a build
console.log("\n--- Simulating: npm run version-file (via postbuild or prestart hook) ---");
// This command, if run in a project with the above package.json, 
// would create a 'version.json' file in the root with content like:
/*
{
  "version": "1.0.0-feature-my-new-feature.456",
  "buildNumber": "456",
  "branchName": "feature-my-new-feature",
  "buildType": "feature"
}
*/
console.log("Check your 'package.json' for version updates and 'version.json' for generated info after running these commands in a real project.");

view raw JSON →