This article has been updated for Angular v4 and Angular CLI v1.4
If you've ever gone through the Angular 2 Quickstart or our Angular v4+ Getting Started Course over the past year, you'll know that a big part of getting started with Angular 2 is the setup.
It included things like:
Table of Contents
- Installing the Angular CLI
- Starting a New Application
- Initialize a New Application in an Existing Folder
- Serving Our Application
- Generate Parts of Your Application
- Generating a New Component
- Generating a New Module with Routing
- Creating a Component in a Module
- Generating Other Things
- Building Our App
- More Commands
- Common Scenarios
- Conclusion
- Creating our app files
- Configuring TypeScript and Typings
- Adding script tags for
- Angular 2
- Rx.js
- System.js
- Configuring System.js
- Creating our Angular 2 app component
- Bootstrapping our Angular 2 application
Talk about a lot! Thankfully, at ng-conf 2016, the Angular team announced a tool that will make creating and scaffolding Angular 2 applications incredibly easy.
The Angular CLI cli.angular.io
The Angular CLI effectively takes all those configuration and setup steps shown above and condenses it down into one quick line:
ng new scotchy-scotch
There are many things that the CLI can do so let's get it installed and walk through some features.
Installing the Angular CLI
To install the CLI, we'll use Node and npm.
npm install -g @angular/cli
That's it! Now we can start using the CLI to build out our applications.
Starting a New Application
To start a new application, just run the command we saw earlier:
ng new scotchy-scotch
So what exactly does this do for us? Let's take a look at the newly generated folders and files:
// end-to-end-tests
|- e2e/
|----- app.e2e-spec.ts
|----- app.po.ts
|----- tsconfig.e2e.json
// npm dependencies
|- node_modules/
// public facing app. built things go here. this wont show until we run a build
|- dist/
// where most of the work will be done
|- src/
|----- app/
|----- app.component.css|html|spec.ts|ts
|----- app.module.ts
|----- assets/
|----- environments/
|----- environment.prod.ts|ts
|----- favicon.ico
|----- index.html
|----- main.ts
|----- polyfills.ts
|----- styles.css
|----- test.ts
|----- tsconfig.app.json
|----- tsconfig.spec.json
|----- typings.d.ts
// overall configuration
|- .angular-cli.json // the main configuration file
|- .editorconfig // editorconfig which is used in some VS Code setups
|- .gitignore
|- karma.conf.js
|- package.json
|- protractor.conf.js
|- README.md
|- tsconfig.json
|- tslint.json
It's important to take note of this directory structure and where the files are located because the application that the Angular CLI generates follows the recommended app structure and style guide.
The majority of our application is under src/app
. This is where we will be working and everything that gets compiled and is available to our final application will be built to the public
folder.
Learn from this stucture and style guide and incorporate these things into your own development. The Angular CLI will not only create the files and folders, it will also install any npm
dependencies required.
Here is the default package.json
that gets created:
{
"name": "scotchy-scotch",
"version": "0.0.0",
"license": "MIT",
"scripts": {
"ng": "ng",
"start": "ng serve",
"build": "ng build",
"test": "ng test",
"lint": "ng lint",
"e2e": "ng e2e"
},
"private": true,
"dependencies": {
"@angular/animations": "^4.0.0",
"@angular/common": "^4.0.0",
"@angular/compiler": "^4.0.0",
"@angular/core": "^4.0.0",
"@angular/forms": "^4.0.0",
"@angular/http": "^4.0.0",
"@angular/platform-browser": "^4.0.0",
"@angular/platform-browser-dynamic": "^4.0.0",
"@angular/router": "^4.0.0",
"core-js": "^2.4.1",
"rxjs": "^5.1.0",
"zone.js": "^0.8.4"
},
"devDependencies": {
"@angular/cli": "1.2.1",
"@angular/compiler-cli": "^4.0.0",
"@angular/language-service": "^4.0.0",
"@types/jasmine": "~2.5.53",
"@types/jasminewd2": "~2.0.2",
"@types/node": "~6.0.60",
"codelyzer": "~3.0.1",
"jasmine-core": "~2.6.2",
"jasmine-spec-reporter": "~4.1.0",
"karma": "~1.7.0",
"karma-chrome-launcher": "~2.1.1",
"karma-cli": "~1.0.1",
"karma-coverage-istanbul-reporter": "^1.2.1",
"karma-jasmine": "~1.1.0",
"karma-jasmine-html-reporter": "^0.2.2",
"protractor": "~5.1.2",
"ts-node": "~3.0.4",
"tslint": "~5.3.2",
"typescript": "~2.3.3"
}
}
All those dependencies are added and included in our src/index.html
file. All of the setup that was in the Angular quickstart are now taken care of for us.
Notice that there's packages for testing with Karma and Protractor and it's great that the CLI handles the beginning setup for testing for us. (We all know adding in testing isn't the first thing on our list when starting new projects).
Check out the src/index.html
file and you'll see the beginning of our application with <app-root></app-root>
. Our entire Angular app will get injected here.
System.js vs webpack
In previous CLI versions, we would also find the script tags for our dependencies here. Since the CLI is now using webpack, all of the following will be injected for us when serving (developing) or building (production) our application.
<script src="vendor/es6-shim/es6-shim.js"></script>
<script src="vendor/reflect-metadata/Reflect.js"></script>
<script src="vendor/systemjs/dist/system.src.js"></script>
<script src="vendor/zone.js/dist/zone.js"></script>
ng new
options
Creating a new application has a few different options we can use. There are many options that can be seen by typing ng help
. I'll show off a few of the important ones here:
--directory
: Specify the directory you want to create this project in--style
: (Default: css) The style file default extension. Possible values: css, scss, less, sass, styl(stylus). You can later change the value in ".angular-cli.json" (defaults.styleExt).--prefix
(Default: app) The prefix to use for all component selectors. You can later change the value in ".angular-cli.json" (apps[0].prefix)--routing
(Default: false) Generate a routing module.
Initialize a New Application in an Existing Folder
Let's say you already have a folder that you've started working in. The ng init
command is here so that you can use the current folder you're already working in.
In the folder you are working in, run:
ng init scotchy-scotch
Serving Our Application
Another really cool thing that our CLI allows us to do is to serve our application in the browser. Previously, we would have to create a server using lite-server or create our own Node (or other) server.
The Angular CLI let's us do this with one simple command:
ng serve
Just like that, the Angular CLI will build a server for us with webpack and we can view it in browser at http://localhost:4200
Angular CLI Serve Features
What features are given to us with our new server?
- Built with webpack: Reloads on saves
- Automatically routed for us
- Found in the browser at http://localhost:4200
- Simplicity and ease-of-mind
- Shows sizes of bundles needed for our app
Generate Parts of Your Application
This is where things get interesting. So far we've just created and instantiated a new project. The ng generate
command can do so much for us:
- Create a new component
- Create a new directive
- Create a new route
- Create a new pipe
- Create a new service
That's a ton of functionality and helps speed up development. First let's talk about the options that we can use for all of the above.
ng generate
options
--flat
: Don't create the code in it's own directory. Just add all files to the current directory.--route=<route>
: Specify the parent route. Only used for generating components and routes.--skip-router-generation
: Don't create the route config. Only used for generating routes.--default
: The generated route should be a default route.--lazy
: Specify if route is lazy.default true
Now we can run through each and see exactly what gets created and how the Angular CLI makes life easier.
Generating a New Component
Components are the foundation of Angular development. Let's generate a new component:
ng generate component hello
# also can be simplified to
ng g component hello
Note: It's important to name your component simply. If a component is created with the name hello
, these are the corresponding naming schemes:
- Folder:
hello
- Files: `hello.component.[css,html,spec.ts,ts]
- Class:
HelloComponent
If you use ng generate component HelloComponent
, then your component class will be an undesirable HelloComponentComponent
.
Here are the files that get created:
|- src/
|----- app/
|----- hello/
|----- hello.component.css|html|spec.ts|ts
Our new component is relegated to its own folder within the src/app
folder. We have all the parts (including tests) that we need for our new component.
Generating a New Module with Routing
In addition to generating components, we can generate modules. Modules are a way we can encapsulate similar functionality into a section of our app.
By separating parts out into their own section, we can treat that module as its own compartment of our app with routing. This will become child routing for our app and then we can even lazy load it!
To generate a module, we can use ng generate module
. To add routing to it, we can add the --routing
flag.
ng generate module about --routing
We now have a brand new AboutModule
that we can include in our main AppModule
.
// about.module.ts
import { NgModule } from '@angular/core';
import { CommonModule } from '@angular/common';
import { AboutRoutingModule } from './about-routing.module';
@NgModule({
imports: [
CommonModule,
AboutRoutingModule
],
declarations: []
})
export class AboutModule { }
We also have the routing for this module:
// src/app/about/about-routing.module.ts
import { NgModule } from '@angular/core';
import { Routes, RouterModule } from '@angular/router';
const routes: Routes = [];
@NgModule({
imports: [RouterModule.forChild(routes)],
exports: [RouterModule]
})
export class AboutRoutingModule { }
Creating a Component in a Module
So far we've only created a module. Let's say we wanted to build out components within this module. This AboutModule
could have a UserComponent
to display owner profiles for Scotch.
Let's generate the component with a little trick. We can generate a component to be part of a module.
ng g component about/user
We now have our new UserComponent
and it lives inside the about
folder. We can now use it and route to it using the provided files.
Generating Other Things
The generate command comes with many other things we can generate:
Scaffold | Usage |
---|---|
Component | ng g component my-new-component |
Directive | ng g directive my-new-directive |
Pipe | ng g pipe my-new-pipe |
Service | ng g service my-new-service |
Class | ng g class my-new-class |
Guard | ng g guard my-new-guard |
Interface | ng g interface my-new-interface |
Enum | ng g enum my-new-enum |
Module | ng g module my-module |
Building Our App
When we want to prepare our Angular app for deployment, we only need to run one command.
ng build
The build will take all of our files and bundle them into five main files. It will also generate everything into a dist
folder. Go ahead and take a look in there and you'll see your deployment ready files. You'll even notice the index.html
file that has all those scripts already injected for you.
Open that index.html
file in browser and your Angular app works!
Building for Production
We can also build for production to get some more efficiently sized bundles. Tree shaking goodness and more!
ng build --prod
Building with Ahead-of-Time Compilation
We can also build with AOT to make sure our Angular app is compiled during build-time instead of in browser at run-time. This can help reduce the size of our app by more than half!
ng build --prod --aot
Once you do that, notice the difference in bundle sizes from the previous non-aot build.
1.89MB vs 849kb! AOT FTW
More Commands
As the CLI get's more hashed out and more information, we'll be filling out this section with more commands and what they do. Some of these commands were a little buggy when we first tested out the CLI since it's in v1.0.0-beta.1
at the time of this writing.
Here's the list of commands that we can also run:
- ng test: Run unit tests with karma
- ng e2e: Run end-to-end tests with protractor
- ng get: Gets values for project
- ng set: Sets values for project
- ng version: Get the version of the CLI
- ng lint: Run codelyzer to analyze code
- ng doc: Generate docs for your project
- ng eject: Get access to the webpack configuration files
Common Scenarios
The Angular CLI team has put together a section of the site called Stories that runs through popuplar real-life scenarios. Give it a look!
https://github.com/angular/angular-cli/wiki/stories
Conclusion
The Angular CLI is an amazing tool and one that comes at a time when more and more people are getting into Angular 2 development. After all the announcments at ng-conf 2016, now is the time to dive in.
The CLI makes diving in that much more accessible since setup, which took up the majority of the time for first-time developers is now handled for us.