DOCSEARCHbyAlgolia
Submit Docs

Cngpac Documentation

website·Indexed 30 days ago

https://cngpac.dev

A highly configurable package release manager for npm that handles the entire release lifecycle. Cngpac uses a system of changenotes and a versioning pipeline to automate version bumping, changelog generation, and publishing via built-in publishers (like npm) and releasers (like GitHub).

Tokens
14.1K
Snippets
94
Records
127
Agent score
44%

What's inside Cngpac

  1. Overview of Cngpac package release manager

    Cngpac is a configurable release manager for npm that automates the entire release lifecycle via a single configuration file. It uses a changenote-based philosophy to handle semantic version calculation, changelog generation (including commit links and contributor attribution), updating package.json, tagging, pushing, publishing to NPM, and creating GitHub releases. The pipeline is fully composable through plugins, allowing developers to swap or extend any stage of the process.

  2. Overview of Cngpac release management

    Cngpac is a highly configurable package release manager for npm that automates the entire release lifecycle via a single configuration file. It uses a changenote-based philosophy to automate semantic version calculation, changelog generation (including commit links and PR references), updating package.json, tagging, pushing to git, publishing to NPM, and creating GitHub releases. The pipeline is pluggable, allowing users to swap or extend any stage of the process.

  3. Overview of cngpac CLI commands

    Cngpac provides a set of seven commands to manage the full software release lifecycle, from initial scaffolding to publishing releases.
    # Command Reference
init     # Scaffold config and CI workflow
change   # (Alias: cng) Add a new changenote
commit   # Commit a staged changenote using its title
prepare  # (Alias: prep) Calculate version and write prepare config
version  # (Alias: vrsn) Bump version, generate changelog, publish, and release
reprepare # (Alias: reprep) Reattempt a failed release
preview  # Generate changelog preview and open in browser

  4. Understand the cngpac preview internal workflow

    When cngpac preview is executed, the tool performs the following steps:

    1. Reads all changenotes from .changenotes/.
    2. Enriches changenotes with git metadata (commit hash, authors).
    3. Retrieves the package name from package.json.
    4. Uses the configured changelog generator plugin to produce markdown.
    5. Converts markdown to HTML using remark and rehype.
    6. Wraps the HTML in a dark-themed styled page.
    7. Writes the result to a temporary HTML file.
    8. Opens the temporary file in the default browser.

  5. Implement a custom Releaser plugin

    You can create a custom releaser by implementing the ReleaserPlugin type. The plugin function receives an object containing the following properties:

    • versionBump (VersionBump): Information about the version bump.
    • changelog (string): The generated changelog in markdown format.
    • tagName (string): The name of the git tag.
    • config (CngpacConfig): The complete Cngpac configuration object.
    import type { ReleaserPlugin } from "cngpac";

const myReleaser: ReleaserPlugin = async ({ versionBump, changelog, tagName, config }) => {
  // ...release logic...
};

  6. Understand the role of Releaser plugins in cngpac

    Releaser plugins are executed after publishers during the version command. Their primary purpose is to handle post-publishing tasks, such as creating a release entry on platforms like GitHub.

  7. Use built-in publishers to distribute packages

    Publisher plugins in cngpac execute after a git push during the version command. They are used to publish packages to registries or other distribution channels. The built-in createNpmPublisher plugin allows publishing specifically to the npm registry.

  8. Prerequisites for using Cngpac

    To use Cngpac, you must meet the following requirements:

    • Node.js version 24 or higher
    • A published npm package with a package.json file
    • A GitHub repository

  9. Configure CI workflow based on package manager

    The cngpac init command automatically detects the package manager using npm_config_user_agent and configures the generated .github/workflows/version.yml with the appropriate install commands and runtime actions:

    • npm: Uses npm ci and actions/setup-node@v6.
    • pnpm: Uses pnpm install --frozen-lockfile and actions/setup-node@v6.
    • yarn: Uses yarn install --frozen-lockfile and actions/setup-node@v6.
    • bun: Uses bun install --frozen-lockfile and oven-sh/setup-bun@v2.

  10. Initialize Cngpac in a project

    Run the initialization command from the project root to set up the release pipeline. Cngpac auto-detects the GitHub repository from package.json and adapts the CI workflow based on the detected package manager (npm, pnpm, yarn, or bun).

    This process creates two files:

    1. cngpac.config.ts: Used for release pipeline configuration.
    2. .github/workflows/version.yml: The CI workflow triggered by prepare.json.
    npx cngpac init

  11. Create a custom Releaser plugin

    Custom releasers are implemented using the ReleaserPlugin type. They run after publishers during the version command and receive a context object containing version bump details, the generated changelog, the git tag name, and the full project configuration.
    import type { ReleaserPlugin } from "cngpac";

const myReleaser: ReleaserPlugin = async ({ versionBump, changelog, tagName, config }) => {
  // Implement release logic here (e.g., calling an external API)
};

export default defineConfig({
  // ...
  releasers: [myReleaser],
});

  12. Execute the Cngpac versioning pipeline

    Cngpac follows a four-phase release flow:

    1. Setup: Initialize the project with cngpac init to create cngpac.config.ts and the GitHub Actions workflow.
    2. Development: For each change, use cngpac change to create a changenote and cngpac commit to stage/commit it using the changenote title.
    3. Release Prep: Run cngpac prepare release to calculate the next semantic version and generate prepare.json. Push this file to the main branch to trigger CI. For pre-releases, use prepare prerelease [tag], prepatch, preminor, or premajor.
    4. CI/Automated: The CI workflow executes the version command with flags to automate the release process.
    # Setup
cngpac init

# Development
cngpac change
cngpac commit

# Release Prep
cngpac prepare release
# OR for pre-release
cngpac prepare prerelease beta

# CI Command
cngpac version --commit --tag --push --publish --release