semantic-release

semantic-release

Version 24.2.1
Published 11 days ago
291 kB
29 dependencies
MIT license

Install

npm i semantic-release

yarn add semantic-release

pnpm add semantic-release

Overview

Automated semver compliant package publishing

Namespaces

namespace semantic-release

module 'semantic-release' {}

function default

default: (options: Options, environment?: Config) => Promise<Result>;

Run semantic-release and returns a Promise that resolves to a Result object.

interface AnalyzeCommitsContext

interface AnalyzeCommitsContext extends VerifyConditionsContext {}

Context used for the analyze commits step.

property commits

commits: ReadonlyArray<Commit>;

List of commits taken into account when determining the new version.

property lastRelease

lastRelease: LastRelease;

Last release

property releases

releases: ReadonlyArray<Release>;

List of releases

interface BaseContext

interface BaseContext {}

Base context used in every semantic release step.

property logger

logger: Signale<'error' | 'log' | 'success' | 'warn'>;

Signale console loger instance.
Has error, log, warn and success methods.

property stderr

stderr: NodeJS.WriteStream;

stderr for semantic-release process

property stdout

stdout: NodeJS.WriteStream;

stdout for semantic-release process

interface BranchObject

interface BranchObject {}

property channel

channel?: string | false | undefined;

The distribution channel on which to publish releases from this branch.
If this field is set to false, then the branch will be released on the default distribution channel (for example the @latest [dist-tag](https://docs.npmjs.com/cli/dist-tag) for npm). This is also the default behavior for the first [release branch](https://semantic-release.gitbook.io/semantic-release/usage/workflow-configuration#release-branches) if the channel property is not set.
For all other branches, if the channel property is not set, then the channel name will be the same as the branch name.
The value of channel, if defined as a string, is generated with [Lodash template](https://lodash.com/docs#template) with the variable name set to the branch name.
For example {name: 'next', channel: 'channel-${name}'} will be expanded to {name: 'next', channel: 'channel-next'}.

property name

name: string;

The name of git branch.
A name is required for all types of branch. It can be defined as a [glob](https://github.com/micromatch/micromatch#matching-features) in which case the definition will be expanded to one per matching branch existing in the repository.
If name doesn't match any branch existing in the repository, the definition will be ignored. For example, the default configuration includes the definition next and next-major which will become active only when the branches next and/or next-major are created in the repository.

property prerelease

prerelease?: string | boolean | undefined;

The pre-release identifier to append to [semantic versions](https://semver.org/) released from this branch.
A prerelease property applies only to pre-release branches and the prerelease value must be valid per the [Semantic Versioning Specification](https://semver.org/#spec-item-9). It will determine the name of versions. For example if prerelease is set to "beta", the version will be formatted like 2.0.0-beta.1, 2.0.0-beta.2, etc.
The value of prerelease, if defined as a string, is generated with [Lodash template](https://lodash.com/docs#template) with the variable name set to the name of the branch.
If the prerelease property is set to true` then the name of the branch is used as the pre-release identifier.
Required for pre-release branches.

property range

range?: string | undefined;

The range of [semantic versions](https://semver.org/) to support on this branch.
A range only applies to maintenance branches and must be formatted like N.N.x or N.x (N is a number). If no range is specified but the name is formatted as a range, then the branch will be considered a maintenance branch and the name value will be used for the range.
Required for maintenance branches, unless name is formatted like N.N.x or N.x (N is a number).

interface Commit

interface Commit {}

property author

author: {
    /**
     * The commit author name.
     */
    name: string;

    /**
     * The commit author email.
     */
    email: string;

    /**
     * The commit author date.
     */
    short: string;
};

The commit author information.

property body

body: string;

The commit body.

property commit

commit: {
    /**
     * The commit hash.
     */
    long: string;

    /**
     * The commit abbreviated hash.
     */
    short: string;
};

The commit abbreviated and full hash.

property committer

committer: {
    /**
     * The committer name.
     */
    name: string;

    /**
     * The committer email.
     */
    email: string;

    /**
     * The committer date.
     */
    short: string;
};

The committer information.

property committerDate

committerDate: string;

The committer date.

property hash

hash: string;

The commit hash.

property message

message: string;

The commit full message (subject and body).

property subject

subject: string;

The commit subject.

property tree

tree: {
    /**
     * The commit tree hash.
     */
    long: string;

    /**
     * The commit abbreviated tree hash.
     */
    short: string;
};

The commit abbreviated and full tree hash.

interface Config

interface Config {}

semantic-release configuration specific for API usage.

property cwd

cwd?: string | undefined;

The current working directory to use. It should be configured to the root of the Git repository to release from.
It allows to run semantic-release from a specific path without having to change the local process cwd with process.chdir().
process.cwd

property env

env?: Record<string, any> | undefined;

The environment variables to use.
It allows to run semantic-release with specific environment variables without having to modify the local process.env.
process.env

property stderr

stderr?: NodeJS.WriteStream | undefined;

The writable stream used to log errors.
It allows to configure semantic-release to write errors to a specific stream rather than the local process.stderr.
process.stderr

property stdout

stdout?: NodeJS.WriteStream | undefined;

The writable stream used to log information.
It allows to configure semantic-release to write logs to a specific stream rather than the local process.stdout.
process.stdout

interface EnvCi

interface EnvCi {}

property branch

branch: string;

Current branch name

property commit

commit: string;

Commit hash

property isCi

isCi: boolean;

Boolean, true if the environment is a CI environment

interface FailContext

interface FailContext extends BaseContext {}

property errors

errors: AggregateError;

Errors that occurred during the release process.

interface GlobalConfig

interface GlobalConfig extends Options {}

semantic-release options, after normalization and defaults have been applied.

property branches

branches: ReadonlyArray<BranchSpec> | BranchSpec;

The branches on which releases should happen. By default **semantic-release** will release:
* regular releases to the default distribution channel from the branch master / main * regular releases to a distribution channel matching the branch name from any existing branch with a name matching a maintenance release range (N.N.x or N.x.x or N.x with N being a number) * regular releases to the next distribution channel from the branch next if it exists * regular releases to the next-major distribution channel from the branch next-major if it exists. * prereleases to the beta distribution channel from the branch beta if it exists * prereleases to the alpha distribution channel from the branch alpha if it exists
**Note**: If your repository does not have a release branch, then **semantic-release** will fail with an ERELEASEBRANCHES error message. If you are using the default configuration, you can fix this error by pushing a master/`main branch.
**Note**: Once **semantic-release** is configured, any user with the permission to push commits on one of those branches will be able to publish a release. It is recommended to protect those branches, for example with [GitHub protected branches](https://help.github.com/articles/about-protected-branches).
See [Workflow configuration](https://semantic-release.gitbook.io/semantic-release/usage/workflow-configuration#workflow-configuration) for more details.

property plugins

plugins: ReadonlyArray<PluginSpec>;

Define the list of plugins to use. Plugins will run in series, in the order defined, for each [step](https://semantic-release.gitbook.io/semantic-release/#release-steps) if they implement it.
Plugins configuration can be defined by wrapping the name and an options object in an array.
See [Plugins configuration](https://semantic-release.gitbook.io/semantic-release/usage/plugins#plugins) for more details.
Default: `[ "@semantic-release/commit-analyzer", "@semantic-release/release-notes-generator", "@semantic-release/npm", "@semantic-release/github" ]`

property repositoryUrl

repositoryUrl: string;

The git repository URL.
Any valid git url format is supported (see [git protocols](https://git-scm.com/book/en/v2/Git-on-the-Server-The-Protocols))
Default: repository property in package.json, or git origin url.

property tagFormat

tagFormat: string;

The git tag format used by **semantic-release** to identify releases. The tag name is generated with [Lodash template](https://lodash.com/docs#template) and will be compiled with the version variable.
**Note**: The tagFormat must contain the version variable exactly once and compile to a [valid git reference](https://git-scm.com/docs/git-check-ref-format#_description).

interface LastRelease

interface LastRelease {}

property channels

channels: string[];

List of channels the release was published to.

property gitHead

gitHead: string;

The Git checksum of the last commit of the release.

property gitTag

gitTag: string;

The Git tag of the release.

property name

name: string;

The Release name

property version

version: string;

The version name of the release.

interface NextRelease

interface NextRelease extends Omit<LastRelease, 'channels'> {}

property channel

channel: string;

The release channel of the release.

property notes

notes?: string | undefined;

The release notes of the next release.

property type

type: ReleaseType;

The semver export type of the release.

interface Options

interface Options {}

semantic-release options.
Can be used to set any core option or plugin options. Each option will take precedence over options configured in the configuration file and shareable configurations.

property branches

branches?: ReadonlyArray<BranchSpec> | BranchSpec | undefined;

The branches on which releases should happen. By default **semantic-release** will release:
* regular releases to the default distribution channel from the branch master/`main * regular releases to a distribution channel matching the branch name from any existing branch with a name matching a maintenance release range (N.N.x or N.x.x or N.x with N being a number) * regular releases to the next distribution channel from the branch next if it exists * regular releases to the next-major distribution channel from the branch next-major if it exists. * prereleases to the beta distribution channel from the branch beta if it exists * prereleases to the alpha distribution channel from the branch alpha if it exists
**Note**: If your repository does not have a release branch, then **semantic-release** will fail with an ERELEASEBRANCHES error message. If you are using the default configuration, you can fix this error by pushing a master/main branch.
**Note**: Once **semantic-release** is configured, any user with the permission to push commits on one of those branches will be able to publish a release. It is recommended to protect those branches, for example with [GitHub protected branches](https://help.github.com/articles/about-protected-branches).
See [Workflow configuration](https://semantic-release.gitbook.io/semantic-release/usage/workflow-configuration#workflow-configuration) for more details.

property ci

ci?: boolean | undefined;

Set to false to skip Continuous Integration environment verifications. This allows for making releases from a local machine.

property dryRun

dryRun?: boolean | undefined;

Dry-run mode, skip publishing, print next version and release notes.

property extends

extends?: ReadonlyArray<string> | string | undefined;

List of modules or file paths containing a [shareable configuration](https://semantic-release.gitbook.io/semantic-release/usage/shareable-configurations). If multiple shareable configurations are set, they will be imported in the order defined with each configuration option taking precedence over the options defined in a previous shareable configuration.
**Note**: Options defined via CLI arguments or in the configuration file will take precedence over the ones defined in any shareable configuration.

property plugins

plugins?: ReadonlyArray<PluginSpec> | undefined;

Define the list of plugins to use. Plugins will run in series, in the order defined, for each [step](https://semantic-release.gitbook.io/semantic-release/#release-steps) if they implement it.
Plugins configuration can be defined by wrapping the name and an options object in an array.
See [Plugins configuration](https://semantic-release.gitbook.io/semantic-release/usage/plugins#plugins) for more details.
Default: `[ "@semantic-release/commit-analyzer", "@semantic-release/release-notes-generator", "@semantic-release/npm", "@semantic-release/github" ]`

property repositoryUrl

repositoryUrl?: string | undefined;

The git repository URL.
Any valid git url format is supported (see [git protocols](https://git-scm.com/book/en/v2/Git-on-the-Server-The-Protocols))
Default: repository property in package.json, or git origin url.

property tagFormat

tagFormat?: string | undefined;

The git tag format used by **semantic-release** to identify releases. The tag name is generated with [Lodash template](https://lodash.com/docs#template) and will be compiled with the version variable.
**Note**: The tagFormat must contain the version variable exactly once and compile to a [valid git reference](https://git-scm.com/docs/git-check-ref-format#_description).

index signature

[name: string]: any;

Any other options supported by plugins.

interface Release

interface Release {}

Details of a release published by a publish plugin.

property gitHead

gitHead: string;

The sha of the last commit being part of the release.

property gitTag

gitTag: string;

The Git tag associated with the release.

property name

name?: string | undefined;

The release name, only if set by the corresponding publish plugin.

property notes

notes: string;

The release notes for the release.

property pluginName

pluginName: string;

The name of the plugin that published the release.

property type

type: ReleaseType;

The semver export type of the release.

property url

url?: string | undefined;

The release URL, only if set by the corresponding publish plugin.

property version

version: string;

The version of the release.

interface VerifyConditionsContext

interface VerifyConditionsContext extends BaseContext {}

Context used for the verify conditions step.

property branch

branch: BranchObject;

Information of the current branch

property branches

branches: ReadonlyArray<BranchObject>;

Information on branches

property cwd

cwd?: string | undefined;

The current working directory to use. It should be configured to the root of the Git repository to release from.
It allows to run semantic-release from a specific path without having to change the local process cwd with process.chdir().
process.cwd

property env

env: Record<string, string>;

The environment variables to use.
It allows to run semantic-release with specific environment variables without having to modify the local process.env.
process.env

property envCi

envCi: EnvCi;

Information about the CI environment.

interface VerifyReleaseContext

interface VerifyReleaseContext extends AnalyzeCommitsContext {}

Context used for the verify release step.

property nextRelease

nextRelease: NextRelease;

The next release.

type AddChannelContext

type AddChannelContext = VerifyReleaseContext;

Context used for the add channel step.

type BranchSpec

type BranchSpec = string | BranchObject;

Specifies a git branch holding commits to analyze and code to release.
Each branch may be defined either by a string or an object. Specifying a string is a shortcut for specifying that string as the name field, for example "master" expands to {name: "master"}.

type GenerateNotesContext

type GenerateNotesContext = VerifyReleaseContext;

Context used for the generate notes step.

type PluginSpec

type PluginSpec<T = any> = string | [string, T];

Specifies a plugin to use.
The plugin is specified by its module name.
To pass options to a plugin, specify an array containing the plugin module name and an options object.

type PrepareContext

type PrepareContext = VerifyReleaseContext;

Context used for the prepare step.

type PublishContext

type PublishContext = VerifyReleaseContext;

Context used for the publish step.

type ReleaseType

type ReleaseType =
    | 'prerelease'
    | 'prepatch'
    | 'patch'
    | 'preminor'
    | 'minor'
    | 'premajor'
    | 'major';

A semver release type. See https://github.com/semantic-release/commit-analyzer/blob/master/lib/default-release-types.js

type Result

type Result =
    | false
    | {
          /**
           * Information related to the last release found.
           */
          lastRelease: LastRelease;

          /**
           * The list of commits included in the new release.
           */
          commits: Commit[];

          /**
           * Information related to the newly published release.
           */
          nextRelease: NextRelease;

          /**
           * The list of releases published, one release per publish plugin.
           */
          releases: Release[];
      };

An object with details of the release if a release was published, or false if no release was published.

type SuccessContext

type SuccessContext = VerifyReleaseContext;

Context used for the success step.

Package Files (1)

index.d.ts

Peer Dependencies (0)

No peer dependencies.

Badge

To add a badge like this oneto your package's README, use the codes available below.

You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/semantic-release.

Markdown

[![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/semantic-release)

HTML

<a href="https://www.jsdocs.io/package/semantic-release"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>

Updated 10 days ago.
Package analyzed in 4481 ms.
Missing or incorrect documentation? Open an issue for this package.

semantic-release

Install

Overview

Index

Namespaces

Namespaces

namespace semantic-release

function default

interface AnalyzeCommitsContext

property commits

property lastRelease

property releases

interface BaseContext

property logger

property stderr

property stdout

interface BranchObject

property channel

property name

property prerelease

property range

interface Commit

property author

property body

property commit

property committer

property committerDate

property hash

property message

property subject

property tree

interface Config

property cwd

property env

property stderr

property stdout

interface EnvCi

property branch

property commit

property isCi

interface FailContext

property errors

interface GlobalConfig

property branches

property plugins

property repositoryUrl

property tagFormat

interface LastRelease

property channels

property gitHead

property gitTag

property name

property version

interface NextRelease

property channel

property notes

property type

interface Options

property branches

property ci

property dryRun

property extends

property plugins

property repositoryUrl

property tagFormat

index signature

interface Release

property gitHead

property gitTag

property name

property notes

property pluginName

property type

property url

property version

interface VerifyConditionsContext

property branch

property branches

property cwd

property env