1 | <h1 align="center" style="border-bottom: none;">📦🚀 + <img alt="npm" src=".github/ASSETS/npm_icon.svg"/><br/>semantic-release-npmx</h1>
|
2 | <h3 align="center">Semantic release plugin for npm publishing that supports monorepos!</h3>
|
3 | <p align="center">
|
4 | <a href="https://travis-ci.com/jdalrymple/semantic-release-npmx">
|
5 | <img src="https://travis-ci.com/jdalrymple/semantic-release-npmx.svg?branch=master" alt="Travis Pipeline Status">
|
6 | </a>
|
7 | <a href="https://codeclimate.com/github/jdalrymple/semantic-release-npmx">
|
8 | <img src="https://codeclimate.com/github/jdalrymple/semantic-release-npmx/badges/gpa.svg" alt="Code Climate maintainability">
|
9 | </a>
|
10 | <a href="https://codecov.io/gh/jdalrymple/semantic-release-npmx">
|
11 | <img src="https://img.shields.io/codecov/c/github/jdalrymple/semantic-release-npmx/master.svg" alt="CodeCov test coverage">
|
12 | </a>
|
13 | <a href="https://david-dm.org/jdalrymple/semantic-release-npmx">
|
14 | <img src="https://david-dm.org/jdalrymple/semantic-release-npmx/status.svg" alt="Dependency Status" />
|
15 | </a>
|
16 | <a href="https://david-dm.org/jdalrymple/semantic-release-npmx?type=dev">
|
17 | <img src="https://david-dm.org/jdalrymple/semantic-release-npmx/dev-status.svg.svg" alt="Dev Dependency Status" />
|
18 | </a>
|
19 | <img src="https://flat.badgen.net/dependabot/jdalrymple/semantic-release-npmx?icon=dependabot" alt="Dependabot Badge" />
|
20 |
|
21 | <img src="https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg" alt="Semantic Release">
|
22 | </a> -->
|
23 | <a href="http://commitizen.github.io/cz-cli/">
|
24 | <img src="https://img.shields.io/badge/commitizen-friendly-brightgreen.svg" alt="Commitizen">
|
25 | </a>
|
26 | <img src="https://img.shields.io/badge/code%20style-prettier-ff69b4.svg" alt="Prettier">
|
27 | <a href="https://packagephobia.now.sh/result?p=semantic-release-npmx">
|
28 | <img src="https://packagephobia.now.sh/badge?p=semantic-release-npmx" alt="Install Size">
|
29 | </a>
|
30 | <a href="LICENSE.md">
|
31 | <img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="Licence: MIT">
|
32 | </a>
|
33 | </p>
|
34 |
|
35 | **[IN DEVELOPMENT]** [**semantic-release**](https://github.com/semantic-release/semantic-release) plugin to publish a [npm](https://www.npmjs.com) package based off of the work done [here](https://github.com/semantic-release/npm). Supports monorepos (lerna, and yarn) **but** is restricted to fixed versioning for now.
|
36 |
|
37 |
|
38 | | Step | Description | |
|
39 | |--------------------|-----------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------|
|
40 | | `verifyConditions` | Verify the presence of the `NPM_TOKEN` environment variable, create or update the `.npmrc` file with the token and verify the token is valid. | |
|
41 | | `prepare` | Update the `package.json` version and [create](https://docs.npmjs.com/cli/pack) the npm package tarball. | |
|
42 | | `addChannel` | | [Add a release to a dist-tag](https://docs.npmjs.com/cli/dist-tag). |
|
43 | | `publish` | [Publish the npm package](https://docs.npmjs.com/cli/publish) to the registry. | |
|
44 |
|
45 | ## Install
|
46 |
|
47 | ```bash
|
48 | $ npm install semantic-release-npmx -D
|
49 | ```
|
50 |
|
51 | ## Usage
|
52 |
|
53 | The plugin can be configured in the [**semantic-release** configuration file](https://github.com/semantic-release/semantic-release/blob/master/docs/usage/configuration.md#configuration):
|
54 |
|
55 | ```json
|
56 | {
|
57 | "plugins": [
|
58 | "@semantic-release/commit-analyzer",
|
59 | "@semantic-release/release-notes-generator",
|
60 | "semantic-release-npmx",
|
61 | ]
|
62 | }
|
63 | ```
|
64 |
|
65 | ## Configuration
|
66 |
|
67 | ### Npm registry authentication
|
68 |
|
69 | The npm authentication configuration is **required** and can be set via [environment variables](#environment-variables).
|
70 |
|
71 | Both the [token](https://docs.npmjs.com/getting-started/working_with_tokens) and the legacy (`username`, `password` and `email`) authentication are supported. It is recommended to use the [token](https://docs.npmjs.com/getting-started/working_with_tokens) authentication. The legacy authentication is supported as the alternative npm registries [Artifactory](https://www.jfrog.com/open-source/#os-arti) and [npm-registry-couchapp](https://github.com/npm/npm-registry-couchapp) only supports that form of authentication.
|
72 |
|
73 | **Note**: Only the `auth-only` [level of npm two-factor authentication](https://docs.npmjs.com/getting-started/using-two-factor-authentication#levels-of-authentication) is supported, **semantic-release** will not work with the default `auth-and-writes` level.
|
74 |
|
75 | ### Environment variables
|
76 |
|
77 | | Variable | Description |
|
78 | | -------------- | ----------------------------------------------------------------------------------------------------------------------------- |
|
79 | | `NPM_TOKEN` | Npm token created via [npm token create](https://docs.npmjs.com/getting-started/working_with_tokens#how-to-create-new-tokens) |
|
80 | | `NPM_USERNAME` | Npm username created via [npm adduser](https://docs.npmjs.com/cli/adduser) or on [npmjs.com](https://www.npmjs.com) |
|
81 | | `NPM_PASSWORD` | Password of the npm user. |
|
82 | | `NPM_EMAIL` | Email address associated with the npm user |
|
83 |
|
84 | Use either `NPM_TOKEN` for token authentication or `NPM_USERNAME`, `NPM_PASSWORD` and `NPM_EMAIL` for legacy authentication
|
85 |
|
86 | ### Options
|
87 |
|
88 | | Options | Description | Default |
|
89 | |--------------|---------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------|
|
90 | | `npmPublish` | Whether to publish the `npm` package to the registry. If `false` the `package.json` version will still be updated. | `false` if the `package.json` [private](https://docs.npmjs.com/files/package.json#private) property is `true`, `true` otherwise. |
|
91 | | `pkgRoot` | Directory path to publish. | `.` |
|
92 | | `tarballDir` | Directory path in which to write the the package tarball. If `false` the tarball is not be kept on the file system. This is relative to the cwd of where semantic-release is called from, even for sub-packages | `false` |
|
93 |
|
94 | **Note**: The `pkgRoot` directory must contains a `package.json`. The version will be updated only in the `package.json` and `npm-shrinkwrap.json` within the `pkgRoot` directory.
|
95 |
|
96 | **Note**: If you use a [shareable configuration](https://github.com/semantic-release/semantic-release/blob/master/docs/usage/shareable-configurations.md#shareable-configurations) that defines one of these options you can set it to `false` in your [**semantic-release** configuration](https://github.com/semantic-release/semantic-release/blob/master/docs/usage/configuration.md#configuration) in order to use the default value.
|
97 |
|
98 | ### Npm configuration
|
99 |
|
100 | The plugin uses the [`npm` CLI](https://github.com/npm/cli) which will read the configuration from [`.npmrc`](https://docs.npmjs.com/files/npmrc). See [`npm config`](https://docs.npmjs.com/misc/config) for the option list.
|
101 |
|
102 | The [`registry`](https://docs.npmjs.com/misc/registry) can be configured via the npm environment variable `NPM_CONFIG_REGISTRY` and will take precedence over the configuration in `.npmrc`.
|
103 |
|
104 | The [`registry`](https://docs.npmjs.com/misc/registry) and [`dist-tag`](https://docs.npmjs.com/cli/dist-tag) can be configured in the `package.json` and will take precedence over the configuration in `.npmrc` and `NPM_CONFIG_REGISTRY`:
|
105 | ```json
|
106 | {
|
107 | "publishConfig": {
|
108 | "registry": "https://registry.npmjs.org/",
|
109 | "tag": "latest"
|
110 | }
|
111 | }
|
112 | ```
|
113 |
|
114 | ### Examples
|
115 |
|
116 | The `npmPublish` and `tarballDir` option can be used to skip the publishing to the `npm` registry and instead, release the package tarball with another plugin. For example with the [@semantic-release/github](https://github.com/semantic-release/github) plugin:
|
117 |
|
118 | ```json
|
119 | {
|
120 | "plugins": [
|
121 | "@semantic-release/commit-analyzer",
|
122 | "@semantic-release/release-notes-generator",
|
123 | ["semantic-release-npmx", {
|
124 | "npmPublish": false,
|
125 | "tarballDir": "dist",
|
126 | }],
|
127 | ["@semantic-release/github", {
|
128 | "assets": "dist/*.tgz"
|
129 | }]
|
130 | ]
|
131 | }
|
132 | ```
|
133 |
|
134 | When publishing from a sub-directory with the `pkgRoot` option, the `package.json` and `npm-shrinkwrap.json` updated with the new version can be moved to another directory with a `postpublish` [npm script](https://docs.npmjs.com/misc/scripts). For example with the [@semantic-release/git](https://github.com/semantic-release/git) plugin:
|
135 |
|
136 | ```json
|
137 | {
|
138 | "plugins": [
|
139 | "@semantic-release/commit-analyzer",
|
140 | "@semantic-release/release-notes-generator",
|
141 | ["semantic-release-npmx", {
|
142 | "pkgRoot": "dist",
|
143 | }],
|
144 | ["@semantic-release/git", {
|
145 | "assets": ["package.json", "npm-shrinkwrap.json"]
|
146 | }]
|
147 | ]
|
148 | }
|
149 | ```
|
150 | ```json
|
151 | {
|
152 | "scripts": {
|
153 | "postpublish": "cp -r dist/package.json . && cp -r dist/npm-shrinkwrap.json ."
|
154 | }
|
155 | }
|
156 | ```
|
157 |
|
158 | #### Monorepos
|
159 | Configuration is pretty much the same, but nested to include configuration for subpackages as well.
|
160 | `tarballDir` will be relative to the root directory.
|
161 |
|
162 | ```json
|
163 | {
|
164 | "plugins": [
|
165 | ["semantic-release-npmx", {
|
166 | "default": {
|
167 | "npmPublish": false,
|
168 | "tarballDir": "dist",
|
169 | },
|
170 | "package1": {
|
171 | "npmPublish": true,
|
172 | "tarballDir": "dist",
|
173 | }
|
174 | }],
|
175 | ]
|
176 | }
|
177 | ```
|
178 |
|
179 | ## TODO
|
180 | - [ ] Handle independant versioning. This will probably require modifications to semantic-release itself. The context object is what tracks the nextRelease/Version information and that i calculated internally by SR. Perhaps if
|
181 | that functinality was exported as a default plugin?
|