Build-genie NPM

Project: Build Genie

Installation

To install this package from the npm registry, use the following command:

npm install build-genie

To get started with the project from the repository, clone it and install the dependencies:

npm install

Features

Build Information Generator

Generate a JSON file with details such as commit hash, tag, branch, and version.
Serve build information via an endpoint in your application.

Commit and Tag Versioning

Automate versioning using semantic versioning.
Generate a changelog based on conventional commits.
Create git tags for releases and manage lifecycle scripts.
Support for pre-releases, tag prefixes, and skipping lifecycle steps.

Usage

Command Line Usage

Build Information Commands

After installing the package globally or locally, you can use the build-genie command in the command prompt to generate the build information file:

npx build-genie generate-file --filepath /lib/build-info.json

This will generate a build information file at the specified location.

To create an endpoint to serve the generated information:

npx build-genie create-endpoint --buildInfoPath /lib/build-info.json

Commit and Tag Versioning Commands

To automate version bumps, changelog generation, and tagging:

npx build-genie release

Examples:

Generate a pre-release:

npx build-genie release --prerelease alpha

Specify the release type:

npx build-genie release --release-as minor

Perform a dry run:
```
npx build-genie release --dry-run
```

Programmatic Usage

Generating Build Information File

import { generateFile } from 'build-genie';

generateFile('/lib/build-info.json');

Creating Build Information Endpoint

import express from 'express';
import { createBuildInfoEndpoint } from 'build-genie';

const app = express();
app.get('/build-info', createBuildInfoEndpoint('/lib/build-info.json'));

app.listen(3000, () => {
  console.log('Server running on port 3000');
});

Automating Releases

const buildGenie = require('build-genie');

buildGenie({
  noVerify: true,
  infile: 'CHANGELOG.md',
  silent: true,
})
  .then(() => {
    console.log('Release complete!');
  })
  .catch((err) => {
    console.error(`Release failed with message: ${err.message}`);
  });

How It Works

Follow the Conventional Commits Specification in your repository.
When you're ready to release, run build-genie release.

The release command will:

Retrieve the current version of your repository by looking at packageFiles, falling back to the last git tag.
Bump the version in bumpFiles based on your commits.
Generate a changelog based on your commits using conventional-changelog.
Create a new commit including your bumpFiles and updated changelog.
Create a new tag with the new version number.

Configuration

Common Options

You can configure build-genie using a configuration file or by adding a stanza to your package.json:

.versionrc, .versionrc.json, .versionrc.js

package.json:

{
  "build-genie": {
    "releaseCount": 0
  }
}

Common Options:

bumpFiles: Files to bump the version in (e.g., package.json, package-lock.json).
skip: Lifecycle steps to skip (e.g., bump, changelog, commit, tag).

Example:

{
  "build-genie": {
    "bumpFiles": ["package.json", "package-lock.json"],
    "skip": {
      "changelog": true
    }
  }
}

Examples

First Release

npx build-genie release --first-release

Pre-Release

npx build-genie release --prerelease beta

Custom Lifecycle Scripts

Configure scripts in package.json:

{
  "build-genie": {
    "scripts": {
      "prerelease": "echo Running prerelease tasks...",
      "postchangelog": "replace 'https://github.com/myproject/issues/' 'https://myjira/browse/' CHANGELOG.md"
    }
  }
}

CLI Usage

First Release

To generate your changelog for your first release, simply do:

npx build-genie release --first-release

This will tag a release without bumping the version in bumpFiles. When you are ready, push the git tag and npm publish your first release.

Cutting Releases

If you typically use npm version to cut a new release, do this instead:

npx build-genie release

As long as your git commit messages are conventional and accurate, you no longer need to specify the semver type - and you get CHANGELOG generation for free!

Release as a Pre-Release

Use the flag --prerelease to generate pre-releases:

npx build-genie release --prerelease beta

This will tag your version as: 1.0.1-beta.0.

Release as a Target Type Imperatively (npm version-like)

To bypass the automated version bump and specify your own target type:

npx build-genie release --release-as minor

Prevent Git Hooks

To skip git hooks during the commit phase:

npx build-genie release --no-verify

Signing Commits and Tags

To sign commits and tags:

npx build-genie release --sign

Lifecycle Scripts

Lifecycle scripts allow you to run custom scripts at various stages of the release process.

Example configuration:

{
  "build-genie": {
    "scripts": {
      "prechangelog": "echo Before generating changelog...",
      "postchangelog": "echo After generating changelog..."
    }
  }
}

Skipping Lifecycle Steps

You can skip specific lifecycle steps:

{
  "build-genie": {
    "skip": {
      "changelog": true
    }
  }
}

Committing Generated Artifacts in the Release Commit

Use the --commit-all flag to commit all staged files in the release commit:

npx build-genie release --commit-all

Dry Run Mode

To simulate the release process without making any changes:

npx build-genie release --dry-run

Prefix Tags

To add a custom prefix to your tags:

npx build-genie release --tag-prefix @scope/package@

Tag Replacement

To replace an existing tag:

npx build-genie release --tag-force

Generate Changelogs for Old Releases

To regenerate changelogs for previous releases:

{
  "build-genie": {
    "releaseCount": 0
  }
}

CLI Help

For help with commands:

npx build-genie release --help

Code Usage

const buildGenie = require("build-genie");

buildGenie({
  noVerify: true,
  infile: "docs/CHANGELOG.md",
  silent: true,
})
  .then(() => {
    console.log("Release complete!");
  })
  .catch((err) => {
    console.error(`Release failed with message: ${err.message}`);
  });

FAQ

How is commit-and-tag-version different from semantic-release?

While both tools handle versioning and changelog generation, build-genie (based on commit-and-tag-version) focuses solely on tagging, versioning, and changelog generation without any automation in pushing to remote repositories or publishing to npm.

Should I always squash commits when merging PRs?

Squashing commits ensures a cleaner commit history and better changelog entries. It also allows associating a single PR with one structured commit message.

Can I use build-genie for additional metadata files, languages or version files?

Yes! You can configure additional bumpFiles and packageFiles to handle versioning in different file formats.

Custom Updaters

To create custom updaters for unconventional file formats, implement readVersion and writeVersion methods.

readVersion(contents = string): string

Reads the version from the given file contents.

writeVersion(contents = string, version: string): string

Writes the version to the given file contents.

Credits

build-genie integrates functionality and concepts from the following projects:

commit-and-tag-version: A fork of standard-version that provides enhanced versioning, tagging, and changelog generation capabilities.
standard-version: The original project for semantic versioning and changelog generation.

Special thanks to the maintainers of both projects for their foundational work, which serves as the basis for many of the features in build-genie.