@szum-tech/semantic-release-config

v2.3.7

Published

2 months ago

Recommended setup for releasing semantically using GitHub Actions workflows compliance with the Szum-Tech standards.

0High
0Medium
0Low

szum-tech Szum-Tech semantic-release conventional-changelog semantic-release-config publish npm npm-publish github github-publish release

📚 Features

Uses Conventional Commits to generate release notes, changelogs and determine the version for new releases.
Creates or updates a CHANGELOG.md file.
Publishes to npm (optional).
Creates a new release on GitHub.
Updates GitHub issues and PRs that are resolved by a new release.
Commits and pushes the current version to package.json.
Offers predefined configurations or configuration builder function

📖 Table of Contents

🎯 Getting Started

⚙️ Installation

@szum-tech/semantic-release-config is available as an npm package.

# NPM
npm install --save-dev semantic-release @szum-tech/semantic-release-config

# YARN
yarn add -D semantic-release @szum-tech/semantic-release-config

# PNPM
pnpm add --save-dev semantic-release @szum-tech/semantic-release-config

# BUN
bun add --dev semantic-release @szum-tech/semantic-release-config

Configuration

Basic information needed to understand, how to set up semantic-release configuration, you are able to find under USAGE > Configuration in semantic-release documentation.

Predefined configs

without-npm - @szum-tech/semantic-release-config/without-npm - allows you to perform the code release process, excluding publishing the code to npm
with-npm - @szum-tech/semantic-release-config/with-npm - allows you to perform the code release process, including publishing the code to npm

Predefined configurations could be set via either:

A .releaserc file, written in YAML or JSON, with optional extensions: .yaml/.yml/.json/.js/.cjs/.mjs
A release.config.(js|cjs|.mjs) file that exports an object
A release key in the project's package.json file

The following examples show how to integrate predefined configuration in project:

Via release.config.mjs file:

export { default } from "@szum-tech/semantic-release-config/with-npm";
// OR
// export { config } from "@szum-tech/semantic-release-config/without-npm";
// if you don't want to publish your project on npm

Imported configurations also could be used to extends yours:

/**
 * @type {import('semantic-release').GlobalConfig}
 */
export default {
  branches: ["master", "next"],
  extends: "@szum-tech/semantic-release-config/with-npm"
  // OR
  // extends: "@szum-tech/semantic-release-config/without-npm";
  // if you don't want to publish your project on npm
};

Via release.config.cjs file:

module.exports = require("@szum-tech/semantic-release-config/with-npm");
// OR
// module.exports = required("@szum-tech/semantic-release-config/without-npm");
// if you don't want to publish your project on npm

OR extend configuration

/**
 * @type {import('semantic-release').GlobalConfig}
 */
module.exports = {
  branches: ["master", "next"],
  extends: "@szum-tech/semantic-release-config/with-npm"
  // OR
  // extends: "@szum-tech/semantic-release-config/without-npm";
  // if you don't want to publish your project on npm
};

Via release key in the project's package.json file:

{
  "release": {
    "extends": "@szum-tech/semantic-release-config/with-npm"
    // OR
    //  "extends": "@szum-tech/semantic-release-config/without-npm";
    // if you don't want to publish your project on npm
  }
}

Via .releaserc file:

{
  "extends": "@szum-tech/semantic-release-config/with-npm"
  // OR
  //  "extends": "@szum-tech/semantic-release-config/without-npm";
  // if you don't want to publish your project on npm
}

Configuration Builder

@szum-tech/semantic-release-config also returns the getConfig function:

// For *.mjs
import { getConfig } from "@szum-tech/semantic-release-config";

// For *.cjs
const { getConfig } = require("@szum-tech/semantic-release-config");

This function takes an argument configurationOptions, where the is located features variable - defining configurable features.

Features Table

| Name | Description | Type | Default Value | | :--: | :---------------------------------------: | :-----: | :-----------: | | npm | Defined if release will be publish on npm | Boolean | false |

The following examples show how to integrate configuration builder function in project:

Via release.config.mjs file:

import { getConfig } from "@szum-tech/semantic-release-config";

export default getConfig({ features: { npmPublish: true } });

Via release.config.cjs file:

const { getConfig } = require("@szum-tech/semantic-release-config");

module.exports = getConfig({ features: { npmPublish: true } });

💻 Environment Variables Configuration

Ensure that your CI configuration has the following environment variables set:

GITHUB_TOKEN: A GitHub personal access token
NPM_TOKEN: A npm personal access token (optional if you don't publish your project on npm)

🚀 Minimal GitHub Release workflow

This is the bare minimum required steps to trigger a new release. This will push a new release every time an eligible commit is pushed to git. Check the opinionated flow to see how to trigger releases manually. Create .github/workflows/publish.yml:

name: Publish 🚀

on:
  push:
    branches: [main]

env:
  NODE_VERSION: 22.x

jobs:
  publish:
    name: Publish 🚀
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code 📚
        uses: actions/checkout@v4
      - name: Set up Node 🟢
        uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: "npm"
      - name: Install packages ⚙️
        run: npm ci
      - name: Build 🏗️
        run: npm run build
      - name: Publish package 🚀
        run: npx semantic-release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}