ngx-deploy-npm
TypeScript icon, indicating that this package has built-in type declarations

8.0.1 • Public • Published

ngx-deploy-npm 🚀

NPM version NPM donwoads The MIT License Conventional Commits

Reliability Rating Security Rating Maintainability Rating

Linux macOS Windows

Publishment Status Test nx@next

Cover Image

Publish your libraries to NPM with one command

Table of contents:


🚀 Quick Start (local development)

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

    npm install --save-dev ngx-deploy-npm
    nx generate ngx-deploy-npm:install
  2. Deploy your library to NPM with all default settings.

    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.

CircleCI

  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:

      nx deploy your-library
  5. Enjoy your just-released package 🎉📦

The complete job example is:

# .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

install

--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.

deploy

--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.

--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
v8.0.0 ^16.0.0 || ^17.0.0
v7.1.0 ^16.0.0 || ^17.0.0
v7.0.1 ^16.0.0

📁 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:

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

becomes

"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

Version Generation

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

Only publishable libraries are being configured

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

Package Sidebar

Install

npm i ngx-deploy-npm

Weekly Downloads

21,179

Version

8.0.1

License

MIT

Unpacked Size

432 kB

Total Files

68

Last publish

Collaborators

  • dianjuar