Lesson Tuesday

Now that Angular CLI is installed and ready to go, we can use it to automatically generate new projects. This lesson will walk through all the files that Angular CLI creates automatically. There are a lot of files, so this lesson may seem overwhelming at first. However, we won't actually be making changes to most of these files. For that reason, having a general overview of what these files do is enough for now. You can always use this lesson as a reference and return to it later if you want more context about various Angular files.

The setup instructions we cover here are general enough to re-use for any future application you may create, not just a to-do app!

Creating a New Angular Application

Navigate to the directory you'd like your new Angular application to reside in and run the following command. We'll go ahead and call our project to-do.

$ ng new to-do

ng stands for Angular. With this command, we instruct Angular to create the following files for the project:

installing ng2
  create .editorconfig
  create README.md
  create src/app/app.component.css
  create src/app/app.component.html
  create src/app/app.component.spec.ts
  create src/app/app.component.ts
  create src/app/app.module.ts
  create src/assets/.gitkeep
  create src/environments/environment.prod.ts
  create src/environments/environment.ts
  create src/favicon.ico
  create src/index.html
  create src/main.ts
  create src/polyfills.ts
  create src/styles.css
  create src/test.ts
  create src/tsconfig.json
  create angular-cli.json
  create e2e/app.e2e-spec.ts
  create e2e/app.po.ts
  create e2e/tsconfig.json
  create .gitignore
  create karma.conf.js
  create package.json
  create protractor.conf.js
  create tslint.json
Successfully initialized git.
Installing packages for tooling via npm.

Once the process is finished, you should see this message in the console: "Project 'to-do' successfully created."

Project Directory

Let's take a look at our file directory:

new-angular-cli-project-directory-in-atom

We'll walk through the files and directories Angular CLI has generated for us.

e2e

This is a directory for tests. e2e stands for "end-to-end". End-to-end testing is similar to integration testing. It explores the application as users experience it and simulates user behavior to confirm the application functions as expected. You may remember that we briefly discussed e2e testing in Week 1 of JavaScript. Angular automatically uses Protractor for e2e testing.

This directory contains app.po.ts and app.e2e-spec.ts files with starter tests and a tsconfig.json file with configurations. We have a lot to cover with Angular so we won't be going over testing in depth. If you'd like to explore Angular testing further, check out the Testing section of the Angular documentation.

node_modules

Angular CLI has already created a node_modules directory for us. If we open the directory, we'll see that many packages are already installed. We can check our package.json file in the top-level of our directory to see included packages:

package.json
  "name": "to-do",
  "version": "0.0.0",
  "license": "MIT",
  "angular-cli": {},
  "scripts": {
    "ng": "ng",
    "start": "ng serve",
    "lint": "tslint \"src/**/*.ts\" --project src/tsconfig.json --type-check && tslint \"e2e/**/*.ts\" --project e2e/tsconfig.json --type-check",
    "test": "ng test",
    "pree2e": "webdriver-manager update --standalone false --gecko false",
    "e2e": "protractor"
  },
  "private": true,
  "dependencies": {
    "@angular/common": "^2.3.1",
    "@angular/compiler": "^2.3.1",
    "@angular/core": "^2.3.1",
    "@angular/forms": "^2.3.1",
    "@angular/http": "^2.3.1",
    "@angular/platform-browser": "^2.3.1",
    "@angular/platform-browser-dynamic": "^2.3.1",
    "@angular/router": "^3.3.1",
    "core-js": "^2.4.1",
    "rxjs": "^5.0.1",
    "ts-helpers": "^1.1.1",
    "zone.js": "^0.7.2"
  },
  "devDependencies": {
    "@angular/compiler-cli": "^2.3.1",
    "@types/jasmine": "2.5.38",
    "@types/node": "^6.0.42",
    "angular-cli": "1.0.0-beta.25.5",
    "codelyzer": "~2.0.0-beta.1",
    "jasmine-core": "2.5.2",
    "jasmine-spec-reporter": "2.5.0",
    "karma": "1.2.0",
    "karma-chrome-launcher": "^2.0.0",
    "karma-cli": "^1.0.1",
    "karma-jasmine": "^1.0.2",
    "karma-remap-istanbul": "^0.2.1",
    "protractor": "~4.0.13",
    "ts-node": "1.2.1",
    "tslint": "^4.3.0",
    "typescript": "~2.0.3"
  }
}

Many of the dev-dependencies should look familiar to you now, especially those related to Jasmine and Karma. You'll also see that there are a number of scripts we can run from the command line, including start, lint and test. These provide very similar functionality to what we've been doing with npm scripts the last two weeks.

src

src stands for "source." This is the directory that will contain our source code. We'll do most of our development in these files (just as we've been doing with vanilla JS projects using webpack).

The contents of this folder should look like this:

src
├── app
│   ├── app.component.css
│   ├── app.component.html
│   ├── app.component.spec.ts
│   ├── app.component.ts
│   └── app.module.ts
├── assets
├── environments
│   ├── environment.prod.ts
│   └── environment.ts
├── favicon.ico
├── index.html
├── main.ts
├── polyfills.ts
├── styles.css
├── test.ts
└── tsconfig.json

Let's start by walking through the files in the top-level of the src directory:

  • favicon.ico contains the small icon that will appear on the browser tab of the running application. You can replace this with your own icon if you'd like. The code to load the icon is in our index.html file.

  • index.html is the index of our page. We'll be covering its contents more in the next lesson.

  • main.ts is the entry point for our application. By this point, you should have a general understanding of what an entry point is based on previous webpack lessons. This file provides instructions for assembling our application when we launch it. It will load our root module, which will then load our root component.

  • polyfills.ts: A polyfill is code that implements a feature on web browsers that don't technically support that feature. This code compensates for any issues older browsers may experience while running an Angular application. Angular CLI imports polyfills in this TypeScript file and then loads the file into main.ts.

  • styles.css is our application-wide stylesheet.

  • test.ts is a configuration file for testing. It's responsible for declaring variables used throughout tests and loading the necessary modules when tests are run.

  • tsconfig.json: This file contains our configuration for the TypeScript compiler. We can leave it as is.

src/assets

Within src, we also have an assets directory. Any images and outside scripts can be placed in this file.

src/environments

The src directory also contains a subdirectory called environments. It contains two files: environment.prod.ts and environment.ts

  • Our development environment includes all tools, packages, and configurations necessary for development. This includes any testing suites and test files as well as the packages listed in the devDependencies section of our package.json.

  • Our production environment includes only tools, packages, modules, and code necessary in the final, deployed version of the app. This prevents apps from shipping with unnecessary code.

If you'd like to learn more about environments in Angular CLI, check out this blog post by Shayne Boyer: "Angular 2: Application Settings using the CLI Environment Option".

Top-Level Files

Let's discuss the files in the uppermost level of our project directory before returning to the src/app directory where we'll complete most of our coding.

  • .editorconfig: This file helps developers maintain consistent coding style across text editors. For instance, one developer on a team may use Atom while another may use Sublime. These developers can ensure their code is formatted similarly by adding configurations to the .editorconfig file. We won't make any changes to this file but you can check out the EditorConfig entry in the Atom Documentation for more info .

  • .gitignore: Just like the past few weeks, there are many files we don't want to push to our Git and GitHub repositories. Angular CLI has already created a .gitignore file in the top level of our project directory. We'll add a few more things to this file over the next few weeks.

  • angular-cli.json: This contains Angular CLI configurations for building and serving a project. We'll look at this file a little closer in upcoming lessons.

  • karma.conf.js: This contains configuration settings Karma. This should be pretty familiar to you after Week 1!

  • package.json: This contains our npm packages and scripts.

  • protractor.conf.js: This contains configurations for a testing tool called Protractor.

  • README.md: An automatically-generated README. If we open it, we can see some content is already in place. Even though there's an automated README, don't forget to add your own author name, description of the project, and any additional setup instructions in your own projects.

  • tslint.json: This contains configurations for the TypeScript linter. Angular CLI includes a built-in linting tool to help notify us of any errors in our code. We'll explore how to use it in an upcoming lesson.

src/app

Finally, let's visit the src/app directory where source code resides. It contains the following:

  • An app.module.ts file for our root module. It already has both a decorator and import statements for the most common portions of Angular in place. We'll explore this further in the next lesson.

  • An app.component.ts file for our root component. We'll be covering this in much more depth, too, since components are such a big part of Angular! We'll be writing most of our code in components.

  • app.component.html is an external HTML template. We could add our HTML directly inside our components but this wouldn't be very clean.

  • Each component also has its own stylesheet: for this component, it's app.component.css. This is in addition to the global stylesheet provided in the src directory. This is very useful for keeping styles modular and contained to pages where they are needed. We can even link a component to multiple stylesheets if we wish!

Testing Files

Additionally, you'll notice a file in the app directory named app.component.spec.ts. This is where any tests for the root AppComponent would reside. This file includes configurations and a few starter tests for our root component. Students interested in exploring testing should check out the Testing Section of the Angular Guides.

Now that we know how to create a new project with Angular CLI and are familiar with the files and directories it generates for us, we're almost ready to begin developing our project.

In the next lesson, we'll take a closer look at components; specifically, the root component of our application. Components are the building blocks of an Angular application, so let's start building out our application one block at a time!