Table of contents:
β οΈ Prerequisites- π Quick Start (local development)
- π Continuous Delivery
- π¦ Options
- π Configuration File
- π§ Essential considerations
- π Next milestones
- License
- π Powered By ngx-deploy-starter
This command has the following prerequisites:
- Angular project created via Angular CLI v8.3.0 or greater (execute
ng update @angular/cli @angular/core
to upgrade your project if necessary)
This quick start assumes that you already an existing Angular project with a publishable package created and you already are logged in in npm using npm login
-
Add
ngx-deploy-npm
to your project. It will configure all your publishable libraries present in the projectng add ngx-deploy-npm
-
Deploy your library to NPM with all default settings. Your library will be automatically built in production mode.
ng deploy your-library
-
Your library should be published on npm. So go and check npm.js
Independently of the CI/CD that you are using you must create 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 ser the env variable. Let's call it
NPM_TOKEN
- On your project setting ser 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
run: npx ng deploy YOUR_LIBRARY
- NOTE: You may want to execute an script that execute some pre steps before publishing and inside that script execute
ng deploy YOUR_LIBRARY
. If you want to make that script on JavaScript and put it on the package.json, execute it usingnpm
not with yarn, there is an issue associated with that
- Create a step with
- Enjoy your just released package ππ¦
The job full 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: ngx ng deploy YOUR_PACKAGE
You can check the steps suggested in the CircleCI's guide
- optional
- Alias:
-c
- Default:
production
(string) - Example:
ng deploy
β Angular project is build in production modeng deploy --configuration=test
β Angular project is using the configurationtest
(this configuration must exist in theangular.json
file)
A named build target, as specified in the configurations
section of angular.json
.
Each named target is accompanied by a configuration of option defaults for that target.
Same as ng build --configuration=XXX
.
- 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.
- Default:
public
(string) - Example:
ng deploy --access public
Tells the registry whether this package should be published as public or restricted. 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
- Default:
public
(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.
- 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
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
- configuration
- dryRun
- 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"
}
}
And just run ng deploy
π.
βΉοΈ You can always use the --dry-run option to verify if your configuration is right.
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.
This deployer do not bumps or creates a new version of the package, it just build the package/library, take the package.json as it and publish it.
A publishable library is one that can be built. Here we detect that if the library in the angular.json
has the architect build with the builder @angular-devkit/build-ng-packagr:build
.
The angular.json
look like
{
"publishable-library": {
"projectType": "library",
"root": "libs/publishable-library",
"sourceRoot": "libs/publishable-library/src",
"prefix": "myworkspace",
"architect": {
"build": {
"builder": "@angular-devkit/build-ng-packagr:build",
"options": {
"tsConfig": "libs/publishable-library/tsconfig.lib.json",
"project": "libs/publishable-library/ng-package.json"
}
}
}
}
}
This take special context in NX environment.
You must take care about the version by yourself. Maybe using a script that sets the version
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! π
Code released under the MIT license.