# auto-plugin-understood

> NPM publishing + Python versioning plugin for auto

Latest version **2.0.9** (published 2020-07-28) · 0 weekly downloads

## Install

```sh
npm install auto-plugin-understood
pnpm add auto-plugin-understood
yarn add auto-plugin-understood
bun add auto-plugin-understood
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.0.9 |
| Published | 2020-07-28 |
| First published | 2020-02-03 |
| Weekly downloads | 0 |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 16 |
| Unpacked size | 46.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Understood Devops |
| Maintainers | michaelfrohberg |

## Links

- npm: https://www.npmjs.com/package/auto-plugin-understood
- Repository: https://github.com/understood/devops
- npm.io page: https://npm.io/package/auto-plugin-understood

## Dependencies (16)

- [faker](https://npm.io/package/faker.md) ^4.1.0
- [fp-ts](https://npm.io/package/fp-ts.md) ^2.5.3
- [io-ts](https://npm.io/package/io-ts.md) ^2.1.2
- [tslib](https://npm.io/package/tslib.md) 1.11.1
- [env-ci](https://npm.io/package/env-ci.md) ^5.0.1
- [semver](https://npm.io/package/semver.md) ^7.0.0
- [url-join](https://npm.io/package/url-join.md) ^4.0.0
- [user-home](https://npm.io/package/user-home.md) ^2.0.0
- [await-to-js](https://npm.io/package/await-to-js.md) ^2.1.1
- [parse-author](https://npm.io/package/parse-author.md) ^2.0.0
- [registry-url](https://npm.io/package/registry-url.md) ^5.1.0
- [@auto-it/core](https://npm.io/package/@auto-it/core.md) ^9.48.1
- [@octokit/rest](https://npm.io/package/@octokit/rest.md) ^18.0.3
- [parse-github-url](https://npm.io/package/parse-github-url.md) 1.0.2
- [typescript-memoize](https://npm.io/package/typescript-memoize.md) ^1.0.0-alpha.3
- [get-monorepo-packages](https://npm.io/package/get-monorepo-packages.md) ^1.1.0

## Recent versions

- 2.0.9 (latest) — 2020-07-28
- 2.0.10-canary.5.29606c1.0 (canary) — 2020-07-28
- 2.0.9-canary.5.3ed2f82.0 — 2020-07-28
- 2.0.8 — 2020-07-28
- 2.0.8-canary.4.e45a3fd.0 — 2020-07-28
- 2.0.7 — 2020-07-28
- 2.0.6 — 2020-07-28
- 2.0.5 — 2020-07-28
- 2.0.5-canary.4.f22d8da.0 — 2020-07-28
- 2.0.4 — 2020-07-28
- 2.0.4-canary.4.f26f855.0 — 2020-07-28
- 2.0.3-canary.4.de601cd.0 — 2020-07-28
- 2.0.3 — 2020-07-28
- 2.0.2 — 2020-07-28
- 2.0.1 — 2020-07-28
- … 39 more at https://npm.io/package/auto-plugin-understood/versions

## README

# NPM Plugin

Publish to NPM. Works in both a monorepo setting and for a single package. This plugin is loaded by default when `auto` is installed through `npm`. If you configure `auto` to use any other plugin this will be lost. So you must add the `npm` plugin to your plugins array if you still want NPM functionality.

## Prerequisites

To publish to npm you will need an `NPM_TOKEN` set in your environment.

## Installation

This plugin is included with the `auto` CLI so you do not have to install it. To install if you are using the `auto` API directly:

```sh
npm i --save-dev @auto-it/npm
# or
yarn add -D @auto-it/npm
```

## Usage

```json
{
  "plugins": [
    "npm",
    // or with options
    ["npm", { "forcePublish": false }]
    // other plugins
  ]
}
```

## Monorepo Usage

The `npm` plugin works out of the box with `lerna` in both [`independent`](https://github.com/lerna/lerna#independent-mode) and [`fixed`](https://github.com/lerna/lerna#fixedlocked-mode-default) mode. `auto` works on a repo basis and should be run from the root of the repo, not on each sub-package. No additional setup is required.

## Options

### setRcToken

When running the `shipit` command auto will try to set your `.npmrc` token while publishing. To disable this feature you must set the `setRcToken` to false.

```json
{
  "plugins": [
    [
      "npm",
      {
        "setRcToken": false
      }
    ]
  ]
}
```

### forcePublish

By default `auto` will force publish all packages for monorepos. To disable this behavior you must set the `setRcToken` to false.

```json
{
  "plugins": [
    [
      "npm",
      {
        "forcePublish": false
      }
    ]
  ]
}
```

### exact

To force all packages publish with [exact versions](https://github.com/lerna/lerna/blob/master/commands/version/README.md#--exact).

```json
{
  "plugins": [
    [
      "npm",
      {
        "exact": true
      }
    ]
  ]
}
```

### subPackageChangelogs

`auto` will create a changelog for each sub-package in a monorepo.
You can disable this behavior by using the `subPackageChangelogs` option.

```json
{
  "plugins": [
    [
      "npm",
      {
        "subPackageChangelogs": false
      }
    ]
  ]
}
```

### canaryScope

Publishing canary versions comes with some security risks.
If your project is private you have nothing to worry about and can skip these, but if your project is open source there are some security holes.

::: message is-warning
This feature works pretty easily/well for single packages. In a monorepo we have to deal with a lot more, and this options should be treated as experimental.
:::

#### Setup

1. Create a test scope that you publish canaries under (ex: `@auto-canary` or `@auto-test`)
2. Create a user that only has access to that scope
3. Set the default `NPM_TOKEN` to a token that can publish to that scope (this is used for any pull request)
4. Set up a `secure` token that is only accessible on the main fork (still named `NPM_TOKEN`)
5. Set up alias (only monorepos)

Step 3 might not be possible on your build platform.

The following are the ways the `auto` team knows how to do it.
If you do not see the method for you build platform, please make a pull request!

**Platform Solutions:**

- [CircleCI Context](https://circleci.com/docs/2.0/contexts/) - Contexts provide a mechanism for securing and sharing environment variables across projects. The environment variables are defined as name/value pairs and are injected at runtime.

```json
{
  "plugins": [
    [
      "npm",
      {
        "canaryScope": "@auto-canary"
      }
    ]
  ]
}
```

##### Set up alias

If you are managing a non-monorepo you do not have to do anything for this step!
If you manage a monorepo we still have to do handle our packages importing each other.
Since we just changed the name of the package all imports to our packages are now broken!

There are multiple ways to make this work and the solution might be different depending on your build target.

- [module-alias](https://www.npmjs.com/package/module-alias) - Modifiy node's require for your canary deploys (This is what `auto` uses). Useful for node packages
- [Webpack Aliases](https://webpack.js.org/configuration/resolve/) Modify scoped requires for webpack based projects.
- [babel-plugin-module-resolver](https://www.npmjs.com/package/babel-plugin-module-resolver) - A Babel plugin to add a new resolver for your modules when compiling your code using Babel.

---
_Source: https://npm.io/package/auto-plugin-understood · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._