With version 8.3 of the Angular CLI a new command has been released which has the potential to be a game changer. Now, deployments to any target (Firebase, Azure, GitHub pages...) are potentially only one CLI command away. In this article we will show you everything you need to know.

Table of contents:

Introduction

In Angular CLI version 8.3 the Angular team added a CLI command which invokes a so-called deployment builder for a project. This enables us to deploy the application to any potential provider or target with just one command: ng deploy. The amount of code added is relatively small, because builders have already been around for a longer time. Another reason is that the CLI itself does not have much to do, but passes the work on to other third-party code instead. So it's up to the community to breathe life into the command. And that's the reason for this article!

Background

In fact, the CLI already had this ability for a while. Angular CLI allows us to extend the set of functionality by implementing builders and invoking them with ng run [builder-name]. There is a very detailed guide about builders provided in the official docs.

However, until now deploy commands were not made on top of CLI builders. Those commands were usually hidden in their own CLI (e.g. firebase deploy) and had nothing to do with the Angular CLI. Our own deploy command (angular-cli-ghpages) was one of them. There was simply no requirement for us to implement a deeper integration into the CLI.

Up to now, builders have not yet achieved the necessary attention they deserve. The new command ng deploy is designed to change that!

It runs in the Angular CLI, so it's clear that an Angular App should be deployed and reasonable defaults can be set accordingly.
It is called ng deploy instead of the usual ng run [builder-name] which might be confusing otherwise.
It throws a meaningful message in case there is no deployment builder installed (Cannot find "deploy" target for the specified project. You should add a package that implements deployment capabilities for your favorite platform.).
It has a very short syntax, because by default it will deploy the default project in the workspace.
And the most important point: It is an invitation to the community to standardise deployments under the umbrella of the Angular CLI!

Command Line Call

Let's take a look at the semantics. How can a deploy builder be triggered? All this is hidden behind the new command which – of course – also has a shorter alias:

ng deploy [options]
ng d [options]

Without any further arguments, the CLI will try to execute the deploy builder for the default project of the workspace.

Since you can also manage several Angular applications (projects) in one workspace, the CLI accepts an optional project name to deploy. The name is used as specified in the angular.json configuration file.

ng deploy [PROJECT_NAME] [options]

So if you have created a project by calling ng new your-angular-project, the complete command could be:

ng deploy your-angular-project

No other options are necessary here for a simple deployment. However, all supplied command line options will automatically be passed to the deploy builder for the selected project. Thus, the builder itself can be further configured.

Existing providers

As for now, there is already a good adaptation for ng deploy. The following providers are currently available:

@angular/fire (Deployment to Firebase hosting)
@azure/ng-deploy (Deployment to Azure)
@netlify-builder/deploy (Deployment to Netlify)
@zeit/ng-deploy (Deployment to Now)
angular-cli-ghpages (Deployment to GitHub pages)

In the future you should be able to find more providers via the following search:
https://www.npmjs.com/search?q=ng%20deploy

You can try out those providers by executing the following commands.

Install the latest version of the Angular CLI.
```
npm install -g @angular/cli
```
Run ng version to make sure you have installed Angular CLI v8.3.0 or greater.
If your existing project doesn't run on Angular CLI v8.3.0 yet, update it using the command:
```
ng update @angular/cli @angular/core
```
Add one of the listed providers to your project.
```
ng add [provider]
```
Deploy your project via:
```
ng deploy
```

One example:

angular-cli-ghpages-deploy

Deploy to multiple targets

Right now, ng deploy only supports a single deploy target for a project. If we want to deploy a project to more than one provider, it is necessary to rewrite the angular.json file and step back to the old syntax to execute the builder.

Let's assume you want to use @angular/fire and angular-cli-ghpages together for one project. First, you need to install both packages via ng add @angular/fire and ng add angular-cli-ghpages. The last one will override the configuration of the first one.

Now open the angular.json file and locate the section projects > you-angular-project > architect > deploy. The trick is to create two sections with different names:

{
  "projects": {
    "your-angular-project": {
      "architect": {
        "deploy-ghpages": {
          "builder": "angular-cli-ghpages:deploy",
          "options": {}
        },
        "deploy-firebase": {
          "builder": "@angular/fire:deploy",
          "options": {}
        }
      }
    }
  },
  "defaultProject": "your-angular-project"
}

You can now call the two builders via the classic approach again with ng run:

ng run your-angular-project:deploy-ghpages
ng run your-angular-project:deploy-firebase

How to make your own deployment builder

As a cloud platform provider (or as a fan of that service), you should consider to implement a dedicated deployment builder, too. The spectrum of possibilities is wide: Let's think about a deployment via FTP, to AWS, to Heroku, to Rackspace etc. – it's up to YOU to launch the next rocket! 🚀

To make the start a bit smoother, we started a sample project to help on that way. The groundwork of this starter was provided by Minko Gechev's ngx-gh project.

The starter project has the following purposes:

Promote the adoption of ng deploy
Clarify various questions and standardise the experience of the various builders

Learn more at https://github.com/angular-schule/ngx-deploy-starter

You are free to customise this project according to your needs. Please keep the spirit of Open Source alive and use the MIT or a compatible license.

Summary

With the new deployment command of the Angular CLI, it will be even easier to manage the complete lifecycle of an Angular application with one single tool. In addition to code generation, build, testing and much more, we can now also conveniently deploy to any target like Azure, Firebase or Netlify. More providers should come soon. 🚀 If you developed another deployment builder: Please let us know and we're happy to add it to our list!

Thank you

Special thanks go to

Minko Gechev for guiding me through the new Angular CLI Architect API.
Ferdinand Malcher for revising this article and discussing things.

Header image: STS-126 Space Shuttle Endeavour Launch. This NASA still image is in the public domain.

Blog

All you need to know about `ng deploy`