# @dotcom-tool-kit/circleci-npm

This plugin is for managing the `publish:tag` hook that is run from circleci to publish the built package to the npm registry.

The tool-kit/publish job is triggered in your circleci pipeline once you do a release with a tag matching the semver format. If your tag is a beta version, i.e. `v1.6.0-beta.1`, then the publish job will tag your build as a prerelease version. If your tag is a release version, i.e. `v1.6.0`, then the publish job will tag your build as the latest version.

This plugin will be installed as a dependency of the [component](https://github.com/Financial-Times/dotcom-tool-kit/tree/main/plugins/component) plugin so you do not need to install it separately if you are using either of those plugins.


## Installation

Install `@dotcom-tool-kit/circleci-npm` as a `devDependency` in your app:

```sh
npm install --save-dev @dotcom-tool-kit/circleci-npm
```

Add the plugin to your [Tool Kit configuration](https://github.com/financial-times/dotcom-tool-kit/blob/main/readme.md#configuring-tool-kit):

```yaml
plugins:
	- '@dotcom-tool-kit/circleci-npm'
```

Install this plugin's hooks:

```sh
npx dotcom-tool-kit --install
```

### For Tool Kit generated CircleCI `config.yml`

If you are migrating your project to Tool Kit for the first time then this plugin can generate a new `.circleci/config.yml` file for your project including Tool Kit configured workflows. To use this feature please delete or rename your existing CircleCI `config.yml` file before running the install command.

### Adding to an existing Tool Kit generated CircleCI `config.yml`

If you have the automated comment `# CONFIG GENERATED BY DOTCOM-TOOL-KIT, DO NOT EDIT BY HAND\n` in your `config.yml`, running the install command will add the tool-kit/publish job to your `config.yml`. Furthermore, this will add the tags filter to the rest of the tool-kit jobs in your workflow in `config.yml`, as CircleCI will only run the jobs if the rest of the jobs have the tags filter.

### Adding to a custom CircleCI `config.yml`

If you don't have the automated comment in your `config.yml` and therefore choose to add the tool-kit/publish job manually, (1) copy and paste the below code snippet and (2) add the tags filter to the rest of the tool-kit jobs:

```yaml
	- tool-kit/publish:
		context: npm-publish-token
		requires:
		- tool-kit/test
		filters:
		branches:
			ignore: /.*/
		tags:
			only: /^v\d+\.\d+\.\d+(-.+)?/
```

## Hooks

| Event | Description | Installed to...| Default tasks |
|-|-|-|-|
| `publish:tag` | Publishes the built package to the npm registry | `publish-tag` job in `.circle/config.yml`  | NpmPublish |