Table of contents:
- π Quick Start (local development)
- π Continuous Delivery
- βWhat is done when executing
nx deploy
- π¦ Options
- π Configuration File
- π§ Essential considerations
- π Do you Want to Contribute?
- License
- Recognitions
Note: all the examples are focused on Nx; if you don't see an explicit command for an Angular workspace change
nx
forng
.Also, when you find references to
workspace.json
, you can find your file under the nameangular.json
.
-
Add
ngx-deploy-npm
to your project. It will configure all your publishable libraries present in the project:-
Nxπ¬
npm install --save-dev ngx-deploy-npm nx generate ngx-deploy-npm:install
-
Angular
π °οΈ ng add ngx-deploy-npm
-
-
Deploy your library to NPM with all default settings.
nx deploy your-library --dry-run
-
When you are happy with the result, remove the
--dry-run
option
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
-
Set the env variable
- On your project setting the env variable. Let's call it
NPM_TOKEN
- On your project setting the env variable. Let's call it
-
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
- Before publishing, we must indicate to npm how to find that token,
do it by creating a step with
-
(Optional) check that you are logged
- Creating a step with
run: npm whoami
- The output should be the username of your npm account
- Creating a step with
-
Deploy your package
- Create a step with:
Nxπ¬ Angular π °οΈ nx deploy your-library
ng deploy your-library
-
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
- Will build the application using the target
build
- This will be omitted if the parameter
--no-build
is set
- This will be omitted if the parameter
- Execute
npm publish
The following is the activity diagram.
- optional
- Example:
nx generate ngx-deploy-npm:install --projects=lib-1,lib-2
β Onlylib-1
andlib-2
are going to configure
Specify which libraries should be configured. Useful when you have a workspace with several libraries and don't want to overwrite existing configuration
Should be ,
separated, without spaces.
- optional
- Default:
public
- Example:
nx generate ngx-deploy-npm:install --access=restricted
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.
- optional
- Example:
nx deploy --build-target=production
β The configurationproduction
is being used to build your package
The buildTarget
points to an existing target configuration on your project,
as specified in the configurations
section of workspace.json
.
This option is equivalent to calling the command nx build --configuration=XXX
.
This command has no effect if the option --no-build
option is active.
- optional
- Default:
false
(string) - Example:
nx deploy
β The library is built in production mode before the deploymentnx deploy --no-build
β The library is NOT built, but the deployment process is being made
Skip build process during deployment.
This option is useful when the building process is handled by something else.
This command causes the --build-target
setting to have no effect.
- 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.
- 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.
- 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.
- 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.
- optional
- Example:
nx deploy --registry http://localhost:4873
Configure npm to use any compatible registry you like, and even run your own registry.
- 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.
- optional
- Example:
nx deploy --dist-folder-path 'dist/my-unsupported-project'
Indicate a custom dist folder path. The path must relative to project's root. Especially useful when ngx-deploy-npm can not detect your library dist folder path automatically. Write us an issue if you think we should support the library you are trying to publish
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.
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
For an Nx workspace, only publishable libraries are going to be configured.
We create a unique document for you to give you through this path.
Code released under the MIT license.
- π Initially Powered By ngx-deploy-starter