# JavaScript API
## Usage
```js
const semanticRelease = require("semantic-release");
const { WritableStreamBuffer } = require("stream-buffers");
const stdoutBuffer = new WritableStreamBuffer();
const stderrBuffer = new WritableStreamBuffer();
try {
const result = await semanticRelease(
{
// Core options
branches: [
"+([0-9])?(.{+([0-9]),x}).x",
"master",
"main",
"next",
"next-major",
{ name: "beta", prerelease: true },
{ name: "alpha", prerelease: true },
],
repositoryUrl: "https://github.com/me/my-package.git",
// Shareable config
extends: "my-shareable-config",
// Plugin options
githubUrl: "https://my-ghe.com",
githubApiPathPrefix: "/api-prefix",
},
{
// Run semantic-release from `/path/to/git/repo/root` without having to change local process `cwd` with `process.chdir()`
cwd: "/path/to/git/repo/root",
// Pass the variable `MY_ENV_VAR` to semantic-release without having to modify the local `process.env`
env: { ...process.env, MY_ENV_VAR: "MY_ENV_VAR_VALUE" },
// Store stdout and stderr to use later instead of writing to `process.stdout` and `process.stderr`
stdout: stdoutBuffer,
stderr: stderrBuffer,
}
);
if (result) {
const { lastRelease, commits, nextRelease, releases } = result;
console.log(
`Published ${nextRelease.type} release version ${nextRelease.version} containing ${commits.length} commits.`
);
if (lastRelease.version) {
console.log(`The last release was "${lastRelease.version}".`);
}
for (const release of releases) {
console.log(`The release was published with plugin "${release.pluginName}".`);
}
} else {
console.log("No release published.");
}
// Get stdout and stderr content
const logs = stdoutBuffer.getContentsAsString("utf8");
const errors = stderrBuffer.getContentsAsString("utf8");
} catch (err) {
console.error("The automated release failed with %O", err);
}
```
## API
### semanticRelease(\[options], \[config]) => Promise
Run **semantic-release** and returns a `Promise` that resolves to a [Result](#result) object.
#### options
Type: `Object`
**semantic-release** options.
Can be used to set any [core option](https://semantic-release.gitbook.io/semantic-release/usage/configuration#configuration) or [plugin options](https://semantic-release.gitbook.io/semantic-release/usage/plugins#configuration).
Each option, will take precedence over options configured in the [configuration file](https://semantic-release.gitbook.io/semantic-release/usage/configuration#configuration) and [shareable configurations](https://semantic-release.gitbook.io/semantic-release/usage/configuration#extends).
#### config
Type: `Object`
**semantic-release** configuration specific for API usage.
**cwd**
Type: `String`\
Default: `process.cwd()`
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()`.
**env**
Type: `Object`\
Default: `process.env`
The environment variables to use.
It allows to run **semantic-release** with specific environment variables without having to modify the local `process.env`.
**stdout**
Type: [`stream.Writable`](https://nodejs.org/api/stream.html#stream_writable_streams)\
Default: `process.stdout`
The [writable stream](https://nodejs.org/api/stream.html#stream_writable_streams) used to log information.
It allows to configure **semantic-release** to write logs to a specific stream rather than the local `process.stdout`.
**stderr**
Type: [`stream.Writable`](https://nodejs.org/api/stream.html#stream_writable_streams)\
Default: `process.stderr`
The [writable stream](https://nodejs.org/api/stream.html#stream_writable_streams) used to log errors.
It allows to configure **semantic-release** to write errors to a specific stream rather than the local `process.stderr`.
### Result
Type: `Object` `Boolean`
An object with [`lastRelease`](#lastrelease), [`nextRelease`](#nextrelease), [`commits`](#commits) and [`releases`](#releases) if a release is published or `false` if no release was published.
#### lastRelease
Type: `Object`
Information related to the last release found:
| Name | Type | Description |
| ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| version | `String` | The version of the last release. |
| gitHead | `String` | The sha of the last commit being part of the last release. |
| gitTag | `String` | The [Git tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging) associated with the last release. |
| channel | `String` | The distribution channel on which the last release was initially made available (`undefined` for the default distribution channel). |
**Note**: If no previous release is found, `lastRelease` will be an empty `Object`.
Example:
```js
{
gitHead: 'da39a3ee5e6b4b0d3255bfef95601890afd80709',
version: '1.0.0',
gitTag: 'v1.0.0',
channel: 'next'
}
```
#### commits
Type: `Array