runas-plugin-npm/README.md

Runas plugin for npm

## Main Index:

- [Available Commands](#available-commands)
  - [Flows](#flows)
  - [Steps](#steps)
- [Plugins](#plugins)
  - [npm](#npm-manage-npm-in-steps)
  - [npmRegistry](#npmregistry-check-npm-registry-configuration)


## Available Commands:

### FLOWS

### STEPS

## PLUGINS

#### npm (Manage npm in steps)
[[Index]](#main-index)

npm commands wrapper for runas

### Hook (stages: check, run)

Any step can ensure that **npm install** or **npm update** are correctly executed:

#### 1. Install plugin in your recipe

 **Add package dependency**:

    npm install runas-plugin-npm --save

 **Add plugin on steps/$stepName/config.json plugins**:

```
{
  "plugins": [
    [...]
    "npm"
  ]
}
```

#### 3. Configure plugin in config.json of your step


```
{
  "npmDependencies": {
    "installed": true,
    "updated": true,
    "baseDir" : "any", (default is '.')
    "directory" : "node_modules" (default is 'node_modules')
  }
}
```

  - **installed** _(default: false)_ Ensure that npm install is executed if ${npm.directory} doesn't exists execute npm install.
  - **updated** _(default: false)_ Ensure that `npm update` and `npm prune` are executed. Detect if there are symbolics links and ask user to delete
  - **directory** _(default: 'node_modules')_ must to be the same value of `directory` in .npmrc file.
  - **baseDir** _(default: '.')_ path to npm.json file relative.

#### 4. Configure the stages for the hook (could be check or run)

**By default the hook is set on check stage**

In config.json of your step

```
{
  "stages" : ["check","run"],
  "npmDependencies": {
    [...]
  }
}
```


#### Examples:

Normal use, ensure npm install was executed:

```
{
  "npmDependencies": {
    "installed": true
  }
}
```

Check if there are symbolics links and ask user to update:

```
{
  "npmDependencies": {
    "updated": true
  }
}
```

### this.npmList

Execute **npm list ${opts}**

| Param | Description |
| --- | --- |
| opts | array with command options to append to npm list for example [ '--offline', '--json' ]  |
| returns | a Promise with the complete child_process object result of the execution |



#### npmRegistry (Check npm registry configuration)
[[Index]](#main-index)

### Description

Plugin used to registry npm modules into a public npm registry

How to use this plugin:

- 1. Implicit: Calling public addons.
- 2. Explicit: By configuration. Checks if npm Registry is well configured.

configure this.params.stages with an array of the stages you want to check if the npm registry is ok.

```
  "stages" : ["check", "run"]
```

### Transitive parameters

This parameters should be set on the step:

- **--registryUrl**: [String], default: 'undefined' : Url of the npm registry. by default use what is configured on .npmrc

Note: you can change the repository that artifacts is going to be published by adding a .runas/runas.json file like this:

```
{
  "params" : {
    "registryUrl" : "https://registry.npmjs.org/"
  }
}
```

### Addons

#### this.publishNpm

Return: 0 if everything is Ok or status of the command executed.