ngx-deploy-npm

    2.1.0 • Public • Published

    ngx-deploy-npm 🚀

    NPM version The MIT License Conventional Commits

    Discord Server

    Cover Image

    Publish your libraries to NPM with one command on an Angular🅰️ or Nx🐬 workspace


    Table of contents:


    Note: all the examples are focused on Angular, if you don't see an explicit command for an Nx workspace just change ng for nx.

    Also, you may find references to angular.json, if you are in a Nx workspace you can change it for workspace.json

    🚀 Quick Start (local development)

    This quick start assumes that you already have an existing Angular or a Nx workspace with a publishable package created and you already are logged in on npm using npm login

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

      Angular🅰️ Nx🐬
       ng add ngx-deploy-npm 
       nx generate ngx-deploy-npm:init 
    2. Deploy your library to NPM with all default settings.

      ng deploy your-library
    3. Your library should be published on npm. So go and check npmjs.com/YOUR-PACKAGE

    🚀 Continuous Delivery

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

    CircleCI

    1. Set the env variable

      • On your project setting ser 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:
      Angular🅰️ Nx🐬
       ng deploy your-library 
       nx deploy your-library 
      • NOTE: You may want to execute a script that executes some pre-steps before publishing and inside that script executeng/nx deploy YOUR_LIBRARY. If you want to make that script on JavaScript and put it on the package.json, execute it using npm not with yarn, there is an issue associated with that
    5. Enjoy your just released package 🎉📦

    The job full example is for an Angular project 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 ng deploy YOUR_PACKAGE
    You can check the steps suggested in the CircleCI's guide

    📦 Options

    --build-target

    • optional
    • Default: Doesn't have any default value (string)
    • Example:
      • ng deploy --build-target=production – The configuration production is being used to build your package

    The buildTarget simply points to an existing build configuration for your project, as specified in the configurations section of angular.json.

    This is equivalent to calling the command ng build --configuration=XXX. This command has no effect if the option --no-build option is active.

    --no-build

    • optional
    • Default: false (string)
    • Example:
      • ng deploy – Angular project is build in production mode before the deployment
      • ng deploy --no-build – Angular project is NOT build

    Skip build process during deployment. This can be used when you are sure that you haven't changed anything and want to deploy with the latest artifact. This command causes the --build-target setting to have no effect.

    --package-version

    • optional
    • Default: Doesn't have any default value (string)
    • Example:
      • ng 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:
      • ng 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:
      • ng deploy --access public

    Tells the registry whether this package should be published 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
    • Default: Doesn't have any default value (string)
    • Example:
      • ng deploy --otp TOKEN

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

    --dry-run

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

    For testing: Run through without making any changes. Execute with --dry-run and nothing will happen. A list of options will be printed

    📁 Configuration File

    To avoid all these command-line cmd options, you can write down your configuration in the angular.json file in the options attribute of your deploy project's architect. Just change the kebab-case to lower camel case. This is the notation of all options in lower camel case:

    • access
    • buildTarget
    • dryRun
    • packageVersion
    • otp
    • tag

    A list of all available options is also available here.

    Example:

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

    becomes

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

    Now you can just run ng 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 right.

    🧐 Essential considerations

    README, LICENCE, and CHANGELOG

    Those files must be in the root of the library. They are being copied by the builder at the moment of deployment.

    If you have those files outside the project's root, you can create a symbolic link to solve that problem.

    See symbolic links on git to know how to create them properly.

    Version bumping

    This deployer doesn't bump or generates a new version of the package, it just builds the package/library, take the package.json as it and publish it. You can use --package-version option to change it.

    Only publishable libraries are being configured

    For Nx workspace, only publishable libraries are going to be configured

    🏁 Next milestones

    We are looking forward to the following features:

    • Implement Continuous Everything:
      • Integration
      • Inspection
      • Delivery
    • Specify which library add the deployer on the ng add
    • Add all the RFC proposals of ngx-deploy-starter
    • Custom README, LICENCE, and CHANGELOG paths

    Your feature that's not on the list yet?

    We look forward to any help. PRs are welcome! 😃

    🎉 Do you Want to Contribute?

    We create a special document for you to give you through this path

    Readme for Contributors

    License

    Code released under the MIT license.

    🚀 Powered By ngx-deploy-starter

    Install

    npm i ngx-deploy-npm

    DownloadsWeekly Downloads

    1,520

    Version

    2.1.0

    License

    MIT

    Unpacked Size

    55.3 kB

    Total Files

    31

    Last publish

    Collaborators

    • dianjuar