The Angular CLI

The Angular CLI tool, ng, is an official Angular project to ensure that newly created Angular applications have a uniform architecture, following the best practices perfected by the community over time. This means that any Angular application you encounter going forward should have the same general shape.

Setting up your development directory

Setting up a dedicated dev directory is a lifesaver. Since all the data under this directory is backed up using GitHub, you can safely configure your antivirus, cloud sync, or backup software to ignore it. This helps significantly reduce CPU, disk, and network utilization. As a full-stack developer, you're likely to be multitasking a lot, so avoiding unnecessary activity has a net positive impact on performance, power, and data consumption daily, especially if your development environment is a laptop that is resource-starved or you wish to squeeze as much battery life as possible when you're on the move.

Create your dev folder using the following commands:

For Windows:

PS> mkdir c:\dev 
PS> cd c:\dev

For macOS:

$ mkdir ~/dev
$ cd ~/dev

Now that your development directory is ready, let's start with generating your Angular application.

Generating your Angular application

The Angular CLI is an official Angular project to ensure that newly created Angular applications have a uniform architecture, following the best practices perfected by the community over time. This means that any Angular application you encounter going forward should have the same general shape. The Angular CLI goes beyond initial code generation; you'll use it frequently to create new components, directives, pipes, services, modules, and more. The Angular CLI also helps during development, with live-reloading features so that you can quickly see the results of your changes. The Angular CLI can also test, lint, and build optimized versions of your code for a production release. Furthermore, as new Angular versions are released, the Angular CLI helps you upgrade your code by automatically rewriting portions of it so that it remains compatible with potential breaking changes.

Installing the Angular CLI

The documentation at https://angular.io/guide/quickstart guides you on how to install @angular/cli as a global npm package. Do not do this. Over time, as the Angular CLI is upgraded, it is a constant irritant to have to keep the global and the in-project version in sync. If you don't, the tool complains endlessly. Additionally, if you are working on multiple projects, you end up with varying versions of the Angular CLI over time. As a result, your commands may not return the results you expect or the results your team members get.

The strategy detailed in the next section makes the initial configuration of your Angular project a bit more complicated than it needs to be; however, you'll more than make up for this pain if you have to return to a project a few months or a year later. In that case, you could use the version of the tool that you last used on the project, instead of some future version that may require upgrades that you're not willing to perform. In the next section, you'll use this best practice to initialize your Angular app.

Initializing your Angular app

The main way to initialize your app is by using the Angular CLI. Let's initialize the application for development using npx, which is already installed on your system from when you installed the latest version of Node LTS, from PowerShell/Terminal:

1. Under your dev folder, execute npx @angular/cli new local-weather-app
2. Select No, when asked Would you like to add Angular routing?
3. Select CSS, when asked Which stylesheet format would you like to use?
4. On your terminal, you should see a success message similar to this:

   $ npx @angular/cli new local-weather-app
   ...
   CREATE local-weather-app/src/environments/environment.ts (662 bytes)
   CREATE local-weather-app/src/app/app-routing.module.ts (245 bytes) CREATE local-weather-app/src/app/app.module.ts (393 bytes)
   CREATE local-weather-app/src/app/app.component.html (1152 bytes) CREATE local-weather-app/src/app/app.component.spec.ts (1086 bytes) CREATE local-weather-app/src/app/app.component.ts (207 bytes) CREATE local-weather-app/src/app/app.component.css (0 bytes)
   CREATE local-weather-app/e2e/protractor.conf.js (752 bytes) CREATE local-weather-app/e2e/tsconfig.e2e.json (213 bytes) CREATE local-weather-app/e2e/src/app.e2e-spec.ts (632 bytes) CREATE local-weather-app/e2e/src/app.po.ts (251 bytes)
   added 1076 packages from 1026 contributors and audited 42608 packages in 62.832s
   found 0 vulnerabilities Successfully initialized git.
   Project 'local-weather-app' successfully created.
   

Your project folder—local-weather-app—has been initialized as a Git repository and scaffolded with the initial file and folder structure, which should look like this:

local-weather-app
├── .editorconfig
├── .git
├── .gitignore
├── angular.json
├── e2e
│ ├── protractor.conf.js
│ ├── src
│ │ ├── app.e2e-spec.ts
│ │ └── app.po.ts
│ └── tsconfig.e2e.json
├── package.json
├── README.md
├── src
│ ├── app
│ │ ├── app-routing.module.ts
│ │ ├── app.component.css
│ │ ├── app.component.html
│ │ ├── app.component.spec.ts
│ │ ├── app.component.ts
│ │ └── app.module.ts
│ ├── assets
│ │ └── .gitkeep
│ ├── browserslist
│ ├── environments
│ │ ├── environment.prod.ts
│ │ └── environment.ts
│ ├── favicon.ico
│ ├── index.html
│ ├── karma.conf.js
│ ├── main.ts
│ ├── polyfills.ts
│ ├── styles.css
│ ├── test.ts
│ ├── tsconfig.app.json
│ ├── tsconfig.spec.json
│ └── tslint.json
├── tsconfig.json
└── tslint.json

The alias for @angular/cli is ng. If you were to install the Angular CLI globally, you would execute ng new local-weather-app, but we didn't do this. So, it is essential to remember that, going forward, you execute the ng command, but this time under the local-weather-app directory. The latest version of the Angular CLI has been installed under the node_modules/.bin directory so that you can run ng commands such as npx ng generate component my-new-component and continue working efficiently.

Publishing a Git repository using GitHub Desktop

GitHub Desktop allows you to create a new repository directly within the application:

1. Open GitHub for Desktop
2. File | Add local repository...
3. Locate the local-weather-app folder by clicking on Choose...
4. Click on Add repository
5. Note that the Angular CLI already created the first commit for you in the History tab
6. Finally, click on Publish repository, marked in the following screenshot as 6:

Figure 2.4: GitHub Desktop

Inspecting and updating package.json

Package.json is the single most important configuration file that you should be keenly aware of at all times. Your project's scripts, runtime, and development dependencies are stored in this file.

1. Open package.json and locate the name and version properties:

   package.json
   {
     "name": "local-weather-app", 
     "version": "0.0.0",
     "license": "MIT",
   ...
   

2. Rename your app to whatever you wish; I used localcast-weather
3. Set your version number to 1.0.0

   npm uses semantic versioning (semver), where version number digits represent Major.Minor.Patch increments. Semver starts version numbers at 1.0.0 for any published API, though it doesn't prevent 0.x.x versioning. As the author of a web application, the versioning of your app has no real impact on you, outside of internal tooling, team, or company communication purposes. However, the versioning of your dependencies is critical to the reliability of your application. In summary, patch versions should just be bug fixes. Minor versions add functionality without breaking the existing features, and major version increments are free to make incompatible API changes. However, any update is risky to the tested behavior of your application. Therefore, the package-lock.json file stores the entire dependency tree of your application, so the exact state of your application can be replicated by other developers or CI servers. For more information, visit: https://semver.org/.

   In the following code block, observe that the scripts property contains a collection of helpful starter scripts that you can expand on. The start and test commands are npm defaults, so they can just be executed by npm start or npm test. However, the other commands are custom commands that must be prepended with the run keyword. For example, in order to build your application, you must use npm run build:

   package.json
   ...
   "scripts": { 
     "ng": "ng",
     "start": "ng serve",
     "build": "ng build",
     "test": "ng test",
     "lint": "ng lint",
     "e2e": "ng e2e"
   },
   ...
   

   Before the introduction of npx, if you wanted to use the Angular CLI without a global install, you would have to run it with npm run ng -- g c my-new-component. The double-dashes are needed to let npm know where the command-line tool name ends and the options begin. For example, in order to start your Angular application on a port other than the default 4200, you need to run npm start -- --port 5000.

4. Update your package.json file to run your development version of the app from a little-used port like 5000 as the new default behavior:

   package.json
   ...
     "start": "ng serve --port 5000",
   ...
   

   Under the dependencies property, you can observe your runtime dependencies. These are libraries that get packaged up alongside your code and shipped to the client browser. It's essential to keep this list to a minimum:

   package.json
   ...
     "dependencies": { 
       "@angular/animations": "~9.0.0",
       "@angular/common": "~9.0.0",
       "@angular/compiler": "~9.0.0",
       "@angular/core": "~9.0.0",
       "@angular/forms": "~9.0.0",
       "@angular/platform-browser": "~9.0.0",
       "@angular/platform-browser-dynamic": "~9.0.0",
       "@angular/router": "~9.0.0",
       "rxjs": "~6.5.3",
       "tslib": "^1.10.0",
       "zone.js": "~0.10.2"
     },
   ...
   

Your development dependencies are stored under the devDependencies property. When installing new tools for your project, you must take care to append the command with --save-dev so that your dependency is correctly categorized. Dev dependencies are only used during development and not shipped to the client browser. You should familiarize yourself with every single one of these packages and their specific purpose. If you are unfamiliar with a package shown as we move on, your best resource to learn more about them is https://www.npmjs.com/:

package.json
...
  "devDependencies": {
    "@angular-devkit/build-angular": "~0.900.0",
    "@angular/cli": "~9.0.0",
    "@angular/compiler-cli": "~9.0.0",
    "@angular/language-service": "~9.0.0",
    "@types/node": "^12.11.1",
    "@types/jasmine": "~3.4.0",
    "@types/jasminewd2": "~2.0.3",
    "codelyzer": "^5.1.2",
    "jasmine-core": "~3.5.0",
    "jasmine-spec-reporter": "~4.2.1",
    "karma": "~4.3.0",
    "karma-chrome-launcher": "~3.1.0",
    "karma-coverage-istanbul-reporter": "~2.1.0",
    "karma-jasmine": "~2.0.1",
    "karma-jasmine-html-reporter": "^1.4.2",
    "protractor": "~5.4.2",
    "ts-node": "~8.3.0",
    "tslint": "~5.18.0",
    "typescript": "~3.6.4"
  }
...

The characters in front of the version numbers have specific meanings in semver:

• The tilde, ~, enables tilde ranges when all three digits of the version number are defined, allowing patch version upgrades to be automatically applied
• The up-caret character, ^, enables caret ranges, allowing minor version upgrades to be automatically applied
• A lack of any character signals npm to install that exact version of the library on your machine

You may notice that major version upgrades aren't allowed to happen automatically. In general, updating packages can be risky. In order to ensure no package is updating without your explicit knowledge, you may install exact version packages by using npm's --save-exact option. Let's experiment with this behavior by installing an npm package that I published called dev-norms, a CLI tool that generates a markdown file with sensible default norms for your team to have a conversation about, as shown here:

1. Under the local-weather-app directory, execute npm install dev-norms --save-dev --save-exact. Note that "dev-norms": "1.7.0" or similar has been added to package.json with package-lock.json automatically updated to reflect the changes accordingly.
2. After the tool is installed, execute npx dev-norms create. A file named dev-norms.md has been created containing the developer norms mentioned previously.

3. Save your changes to package.json.

Working with stale packages comes with its risks. With npm 6, the npm audit command has been introduced to make you aware of any vulnerabilities discovered in packages you're using. During npm install, if you receive any vulnerability notices, you may execute npm audit to find out details about any potential risk.

In the next section, you'll commit the changes you have made to Git.

Committing code using VS Code

To commit your changes to Git and then synchronize your commits to GitHub, you can use VS Code:

1. Switch over to the Source Control pane, marked as 1 here:

   

   Figure 2.5: Visual Studio Code Source Control pane

2. Enter a commit message in the box marked as 2
3. Click on the check-mark icon, marked as 3, to commit your changes
4. Finally, synchronize your changes with your GitHub repository by clicking on the refresh icon, marked as 4

If you have two-factor authentication enabled, as you should, GitHub may ask for your credentials. In this case, you need to create a personal access token. Follow the instructions below to get this done:

1. Go to the page https://github.com/settings/tokens
2. Generate a new token and copy it
3. Attempt to re-sync your change within VS Code
4. Ignore the GitHub authentication window, which presents you with VS Code's credential input bar
5. Enter your GitHub username, not your email
6. Paste in the token as your password
7. The sync should succeed, and subsequent syncs shouldn't prompt for a password

Going forward, you can do most Git operations from within VS Code.

Running your Angular app

Run your Angular app to check whether it works. During development, you can execute npm start through the ng serve command; this action transpiles, packages, and serves the code on localhost with live-reloading enabled:

1. Execute npm start
2. Navigate to http://localhost:5000
3. You should see a rendered page similar to this:

   

   Figure 2.6: Default Angular CLI landing page

4. Stop your application by pressing Ctrl + C in the integrated terminal

Congrats! You're ready to start developing your web application. If you ran into any trouble during your setup, see the next section on how you can verify your code against the sample project on GitHub.

Verifying your code

The most up-to-date versions of the sample code for the book are on GitHub at the repository linked following. The repository contains the final and completed state of the code. You can verify your progress at the end of a chapter by looking for the end-of-chapter snapshot of code under the projects folder.

For Chapter 2:

1. Clone the repo https://github.com/duluca/local-weather-app
2. Execute npm install on the root folder to install dependencies
3. The code sample for this chapter is under the sub-folder:

   projects/ch2
   

4. To run the Angular app for this chapter, execute:

   npx ng serve ch2
   

5. To run Angular Unit Tests for this chapter, execute:

   npx ng test ch2 --watch=false
   

In the next section, I'll cover how you can optimize VS Code for Angular for the best possible development experience.