ngx-deploy-npm 🚀

[![NPM version][npm-image]][npm-url]
[![NPM donwoads][downloads-image]][npm-url]
[![The MIT License][mit-licence-image]][mit-licence-url]
[![Conventional Commits][conventional-commits-image]][conventional-commits-url]

[![Reliability Rating][sonar-reliability-image]][sonar-link]
[![Security Rating][sonar-security-image]][sonar-link]
[![Maintainability Rating][sonar-maintainability-image]][sonar-link]

![Linux][linux-image]
![macOS][macos-image]
![Windows][windows-image]

[![Publishment Status][publishment-image]][publishment-link]
[![Test nx@next][next-tests-image]][next-tests-link]

[sonar-reliability-image]: https://sonarcloud.io/api/project_badges/measure?project=bikecoders_ngx-deploy-npm&metric=reliability_rating
[sonar-security-image]: https://sonarcloud.io/api/project_badges/measure?project=bikecoders_ngx-deploy-npm&metric=security_rating
[sonar-maintainability-image]: https://sonarcloud.io/api/project_badges/measure?project=bikecoders_ngx-deploy-npm&metric=sqale_rating
[publishment-image]: https://github.com/bikecoders/ngx-deploy-npm/actions/workflows/publishment.yml/badge.svg?branch=main
[npm-image]: https://badge.fury.io/js/ngx-deploy-npm.svg
[mit-licence-image]: https://img.shields.io/badge/license-MIT-orange.svg?color=blue&style=flat
[conventional-commits-image]: https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg
[downloads-image]: https://img.shields.io/npm/dm/ngx-deploy-npm
[supported-nx-versions]: https://img.shields.io/badge/nx%20supported%20versions-v16-143055
[next-tests-image]: https://github.com/bikecoders/ngx-deploy-npm/actions/workflows/test-nx-next.yml/badge.svg
[linux-image]: https://img.shields.io/badge/Linux-FCC624?style=flat&logo=linux&logoColor=black
[macos-image]: https://img.shields.io/badge/mac%20os-000000?style=flat&logo=macos&logoColor=F0F0F0
[windows-image]: https://img.shields.io/badge/Windows-0078D6?style=flat&logo=windows&logoColor=white

[sonar-link]: https://sonarcloud.io/summary/new_code?id=bikecoders_ngx-deploy-npm
[publishment-link]: https://github.com/bikecoders/ngx-deploy-npm/actions/workflows/publishment.yml
[npm-url]: https://www.npmjs.com/package/ngx-deploy-npm
[mit-licence-url]: http://opensource.org/licenses/MIT
[conventional-commits-url]: https://conventionalcommits.org
[next-tests-link]: https://github.com/bikecoders/ngx-deploy-npm/actions/workflows/test-nx-next.yml

!Cover Image

Publish your libraries to NPM with one command

Table of contents:

- 🚀 Quick Start (local development)
- 🚀 Continuous Delivery
- 📦 Options
- install
- --dist-folder-path
- --project
- --access
- deploy
- --check-existing
- --package-version
- --tag
- --access
- --otp
- --dry-run
- --dist-folder-path
- Compatibility overview with Nx
- 📁 Configuration File
- 🧐 Essential considerations
- Version Generation
- 🎉 Do you Want to Contribute?
- License
- Recognitions

---

🚀 Quick Start (local development)

1. Add ngx-deploy-npm to your project. It will configure all your publishable libraries present in the project:

``bash
npm install --save-dev ngx-deploy-npm
nx generate ngx-deploy-npm:install
`

2. Deploy your library to NPM with all default settings.

`sh
nx deploy your-library --dry-run
`

3. When you are happy with the result, remove the --dry-run option

🚀 Continuous Delivery

Independently of the CI/CD you are using, you need an NPM token. To do so, you have two methods.

- Via NPM web page
- Using npm token create

$3

1. Set the env variable
- On your project setting the env variable. Let's call it NPM_TOKEN
2. Indicate how to find the token
- Before publishing, we must indicate to npm how to find that token,
do it by creating a step with run: echo '//registry.npmjs.org/:_authToken=${NPM_TOKEN}' > YOUR_REPO_DIRECTORY/.npmrc
- Replace YOUR_REPO_DIRECTORY for the path of your project,
commonly is /home/circleci/repo
3. (Optional) check that you are logged
- Creating a step with run: npm whoami
- The output should be the username of your npm account
4. Deploy your package

- Create a step with:

`sh
nx deploy your-library
`

5. Enjoy your just-released package 🎉📦

The complete job example is:

`yml


.circleci/config.yml


jobs:
init-deploy:
executor: my-executor
steps:
- attach_workspace:
at: /home/circleci/repo/
# Set NPM token to be able to publish
- run: echo '//registry.npmjs.org/:_authToken=${NPM_TOKEN}' > /home/circleci/repo/.npmrc
- run: npm whoami
- run: npx nx deploy YOUR_PACKAGE
`

> You can check the steps suggested in the CircleCI's guide

📦 Options

$3

#### --dist-folder-path

- required
- Example:
- nx generate ngx-deploy-npm:install --project=lib-1 --dist-folder-path="dist/libs/lib-1"

Indicates the dist folder path. The path where is located the bundle of your library. The path should be relative to the project's root.

#### --project

- required
- Example:
- nx generate ngx-deploy-npm:install --project=lib-1 --dist-folder-path="dist/libs/lib-1" – lib-1 will be configured. It will create the target deploy with the default options on the project lib-1.

Specify which library should be configured.

#### --access

- optional
- Default: public
- Example:
- nx generate ngx-deploy-npm:install --access=restricted --project=lib-1 --dist-folder-path="dist/libs/lib-1"

Tells the registry whether to publish the package as public or restricted. It only applies to scoped packages, which default to restricted. If you don't have a paid account, you must publish with --access public to publish scoped packages.

$3

#### --dist-folder-path

- required
- Example:
- nx deploy --dist-folder-path='dist/libs/my-project'

Indicate the dist folder path.
The path must relative to project's root.

#### --check-existing

- optional
- Example:
- nx deploy --check-existing=warning
- nx deploy --check-existing=error

Check if the package version already exists before publishing.
If it exists and --check-existing=warning, it will skip the publishing and log a warning.
If it exists and --check-existing=error, it will throw an error.

#### --package-version

- optional
- Example:
- nx deploy --package-version 2.3.4

It's going to put that version on your package.json and publish the library with that version on NPM.

#### --tag

- optional
- Default: latest (string)
- Example:
- nx deploy --tag alpha – Your package will be available for download using that tag, npm install your-package@alpha useful for RC versions, alpha, betas.

Registers the published package with the given tag, such that npm install @ will install this version. By default, npm publish updates and npm install installs the latest tag. See npm-dist-tag for details about tags.

#### --access

- Default: public (string)
- Example:
- nx deploy --access public

Tells the registry whether to publish the package as public or restricted. It only applies to scoped packages, which default to restricted. If you don't have a paid account, you must publish with --access public to publish scoped packages.

#### --otp

- optional
- Example:
- nx deploy --otp TOKEN

If you have two-factor authentication enabled in auth-and-writes mode, you can provide a code from your authenticator.

#### --registry

- optional
- Example:
- nx deploy --registry http://localhost:4873

Configure npm to use any compatible registry you like, and even run your own registry.

#### --dry-run

- optional
- Default: false (boolean)
- Example:
- nx deploy --dry-run

For testing: Run through without making any changes. Execute with --dry-run, and nothing will happen. It will show a list of the options used on the console.

Compatibility overview with Nx

| Version | Nx Workspace Version |
| ------- | -------------------- |
| v9.0.0 | >=19.x <21.x |
| v8.4.0 | >=16.x <20.x |
| v8.2.0 | >=16.x <19.x |
| v8.1.0 | >=16.x <18.x |
| v8.0.0 | >=16.x <17.x |
| v7.1.0 | >=16.x <17.x |
| v7.0.1 | 16.x |

📁 Configuration File

To avoid all these command-line cmd options, you can write down your
configuration in the workspace.json file in the options attribute
of your deploy project's executor.
Just change the option to lower camel case.

A list of all available options is also available here.

Example:

`sh
nx deploy your-library --tag alpha --access public --dry-run
`

becomes

`json
"deploy": {
"executor": "ngx-deploy-npm:deploy",
"options": {
"tag": "alpha",
"access": "public",
"dryRun": true
}
}
`

Now you can just run nx deploy YOUR-LIBRARY without all the options in the command line! 😄

> ℹ️ You can always use the --dry-run option to verify if your configuration is correct.

🧐 Essential considerations

$3

This deployer doesn't bump or generate a new package version; here, we care about doing one thing well, publish your libs to NPM. You can change the version package at publishment using the --package-version option.

We strongly recommend using @jscutlery/semver to generate your package's version based on your commits automatically. When a new version is generated you can specify to publish it using ngx-deploy-npm.

For more information go to semver's documentation

We use @jscutlery/semver here on ngx-deploy-npm to generate the package's next version, and we use ngx-deploy-npm` to publish that version to NPM. Yes, it uses itself, take a look by yourself ngx-deploy-npm/project.json

$3

Only publishable libraries are going to be configured.

🎉 Do you Want to Contribute?

We create a unique document for you to give you through this path.

Readme for Contributors

License

Code released under the MIT license.

Recognitions

- 🚀 Initially Powered By ngx-deploy-starter