Let's start from zero and build a super simple Angular 2 application in TypeScript.
See It Run!
Running the live example is the quickest way to see an Angular 2 app come to life.
Clicking that link fires up a browser, loads the sample in plunker, and displays a simple message:
Here is the file structure:
Functionally, it's an
index.html and two TypeScript files in an
We can handle that!
Of course we won't build many apps that only run in plunker. Let's follow a process that's closer to what we'd do in real life.
- Set up our development environment
- Write the Angular root component for our app
- Bootstrap it to take control of the main web page
- Write the main page (
We really can build the QuickStart from scratch in five minutes if we follow the instructions and ignore the commentary.
Most of us will be interested in the "why" as well as the "how" and that will take longer.
We'll need a place to stand (the application project folder), some libraries, some TypeScript configuration and the TypeScript-aware editor of your choice.
Create a new project folder
Add the libraries we need
We recommend the npm package manager for acquiring and managing our development libraries.
Don't have npm? Get it now because we're going to use it now and repeatedly throughout this documentation.
Add a package.json file to the project folder and copy/paste the following:
Itching to know the details? We explain in the appendix below
Install these packages. Open a terminal window (command window in Windows) and run this npm command.
Scary error messages in red may appear during install. Ignore them. The install will succeed. See the appendix below for more information.
We must guide the TypeScript compiler with very specific settings.
Add a tsconfig.json file to the project folder and copy/paste the following:
We explore the
tsconfig.json in an appendix below
We're all set. Let's write some code.
Our First Angular Component
The Component is the most fundamental of Angular concepts. A component manages a view - a piece of the web page where we display information to the user and respond to user feedback.
Technically, a component is a class that controls a view template. We'll write a lot of them as we build Angular apps. This is our first attempt so we'll keep it ridiculously simple.
Create an application source sub-folder
We like to keep our application code in a sub-folder off the root called
Execute the following command in the console window.
Add the component file
Now add a file named app.component.ts and paste the following lines:
Let's review this file in detail, starting at the bottom where we define a class.
The Component class
At the bottom of the file is an empty, do-nothing class named
When we're ready to build a substantive application,
we can expand this class with properties and application logic.
AppComponent class is empty because we don't need it to do anything in this QuickStart.
Angular apps are modular. They consist of many files each dedicated to a purpose.
Most application files export one thing such as a component.
app.component file exports the
The act of exporting turns the file into a module. The name of the file (without extension) is usually the name of the module. Accordingly, 'app.component' is the name of our first module.
A more sophisticated application would have child components that descended from
AppComponent in a visual tree.
A more sophisticated app would have more files and modules, at least as many as it had components.
Quickstart isn't sophisticated; one component is all we need. Yet modules play a fundamental organizational role in even this small app.
Modules rely on other modules. In TypeScript Angular apps, when we need something
provided by another module, we import it.
When another module needs to refer to
AppComponent, it imports the
AppComponent symbol like this:
Angular is also modular. It is a collection of library modules. Each library is itself a module made up of several, related feature modules.
When we need something from Angular, we import it from an Angular library module. We need something from Angular right now to help us define metadata about our component.
A class becomes an Angular component when we give it metadata. Angular needs the metadata to understand how to construct the view and how the component interacts with other parts of the application.
We define a component's metadata with the Angular
We access that function by importing it from the primary Angular library,
In TypeScript we apply that function to the class as a decorator by prefixing it with the @ symbol and invoking it just above the component class:
@Component tells Angular that this class is an Angular component.
The configuration object passed to the
@Component method has two
selector and a
selector specifies a simple CSS selector for a host HTML element named
Angular creates and displays an instance of our
wherever it encounters a
my-app element in the host HTML.
my-app selector! We'll need that information when we write our
template property holds the component's companion template.
A template is a form of HTML that tells Angular how to render a view.
Our template is a single line of HTML announcing "My First Angular App".
Now we need something to tell Angular to load this component.
Give it the boot
Add a new file ,
boot.ts, to the
app/ folder as follows:
We need two things to launch the application:
- Angular's browser
- The application root component that we just wrote.
We import both. Then we call
bootstrap, passing in the root component type,
Learn why we import
and why we create a separate boot.ts file in the appendix below.
We've asked Angular to launch the app in a browser with our component at the root. Where will Angular put it?
Angular displays our application in a specific location on our
It's time to create that file.
We won't put our
index.html in the
We'll locate it up one level, in the project root folder.
Now create the
index.html file and paste the following lines:
There are three noteworthy sections of HTML:
Rx.jsare needed by Angular 2.
We configure something called
Systemand ask it to import the boot file we just wrote.
We add the
<my-app>tag in the
<body>. This is where our app lives!
Something has to find and load our application modules. We're using SystemJS to do that. There are other choices and we're not saying SystemJS is the best. We like it and it works.
The specifics of SystemJS configuration are out of bounds. We'll briefly describe this particular configuration in the appendix below.
When Angular calls the
bootstrap function in
boot.ts, it reads the
metadata, finds the
my-app selector, locates an element tag named
and loads our application between those tags.
Compile and run!
Open a terminal window and enter this command:
That command runs two parallel node processes
- The TypeScript compiler in watch mode
- A static server called lite-server that loads
index.htmlin a browser and refreshes the browser when application files change
In a few moments, a browser tab should open and display
Congratulations! We are in business.
If you see
Loading... displayed instead, see the
Browser ES6 support appendix.
Make some changes
Try changing the message to "My SECOND Angular 2 app".
The TypeScript compiler and
lite-server are watching.
refresh the browser, and display the revised message.
It's a nifty way to develop an application!
We close the terminal window when we're done to terminate both the compiler and the server.
Our final project folder structure looks like this:
And here are the files:
Our first application doesn't do much. It's basically "Hello, World" for Angular 2.
We kept it simple in our first pass: we wrote a little Angular component,
index.html, and launched with a
static file server. That's about all we'd expect to do for a "Hello, World" app.
We have greater ambitions.
The good news is that the overhead of setup is (mostly) behind us.
We'll probably only touch the
package.json to update libraries.
We'll likely open
index.html only if we need to add a library or some css stylesheets.
We're about to take the next step and build a small application that demonstrates the great things we can build with Angular 2.
Join us on the Tour of Heroes Tutorial!
The balance of this chapter is a set of appendices that elaborate some of the points we covered quickly above.
There is no essential material here. Continued reading is for the curious.
Appendix: Browser ES6 support
Angular 2 relies on some ES2015 features, most of them found in modern
browsers. Some browsers (including IE 11) require a shim to support the
the needed functionality.
Try loading the following shim above the other scripts in the
npm is a popular package manager and Angular application developers rely on it to acquire and manage the libraries their apps require.
We specify the packages we need in an npm package.json file.
The Angular team suggests the packages listed in the
sections listed in this file:
There are other possible package choices. We're recommending this particular set that we know work well together. Play along with us for now. Feel free to make substitutions later to suit your tastes and experience.
package.json has an optional scripts section where we can define helpful
commands to perform development and build tasks.
We've included a number of such scripts in our suggested
We've seen how we can run the compiler and a server at the same time with this command:
We execute npm scripts in that manner:
npm run + script-name. Here's what these scripts do:
npm run tsc- run the TypeScript compiler once
npm run tsc:w- run the TypeScript compiler in watch mode; the process keeps running, awaiting changes to TypeScript files and re-compiling when it sees them.
Appendix: Npm errors and warnings
All is well if there are no console messages starting with
npm ERR! at the end of an npm install.
There might be a few
npm WARN messages along the way — and that is perfectly fine.
We often see an
npm WARN message after a series of
gyp ERR! messages.
Ignore them. A package may try to re-compile itself using
If the re-compile fails, the package recovers (typically with a pre-built version)
and everything works.
We are in good shape as long as there are no
npm ERR! messages at the very end of
Appendix: TypeScript configuration
We added a TypeScript configuration file (
tsconfig.json) to our project to
Get details about
tsconfig.json from the official
The options and flags in the file we provided are essential.
We'd like a moment to discuss the
TypeScript developers disagree about whether it should be
There is no correct answer and we can change the flag later.
But our choice now can make a difference in larger projects so it merits
noImplicitAny flag is
the compiler silently defaults the type of a variable to
any if it cannot infer
the type based on how the variable is used. That's what we mean by "implicitly
noImplicitAny flag is
true and the TypeScript compiler cannot infer
it also reports an error.
In this QuickStart and many of the other samples in this Developer Guide
we set the
noImplicitAny flag to
Developers who prefer stricter type checking should set the
noImplicitAny flag to
We can still set a variable's type to
that seems like the best choice. We'd be doing so explicitly after
giving the matter some thought.
If we set the
noImplicitAny flag to
true, we may get implicit index errors as well.
If we feel these are more annoying than helpful,
we can suppress them with the following additional flag.
Appendix: SystemJS Configuration
The QuickStart uses SystemJS to load application and library modules. There are alternatives that work just fine including the well-regarded webpack. SystemJS happens to be a good choice but we want to be clear that it was a choice and not a preference.
All module loaders require configuration and all loader configuration becomes complicated rather quickly as soon as the file structure diversifies and we start thinking about building for production and performance.
We suggest becoming well-versed in the loader of your choice.
Learn more about SystemJS configuration here.
With those cautions in mind, what are we doing here?
packages node tells SystemJS what to do when it sees a request for a
module from the
Our QuickStart makes such requests when one of its application TypeScript files has an import statement like this:
Notice that the module name (after
from) does not mention a filename extension.
We see compiler warnings and errors that are hidden from us in the browser.
Pre-compilation simpifies the module loading process and it's much easier to diagnose problem when this is a separate, external step.
Pre-compilation means a faster user experience because the browser doesn't waste time compiling.
We iterate development faster because we only re-compile changed files. We notice the difference as soon as the app grows beyond a handful of files.
pre-compilation fits into a continuous integration process of build, test, deploy.
System.import call tells SystemJS to import the
boot.js ... after transpiling
boot is where we tell Angular to launch the application.
We also catch and log launch errors to the console.
All other modules are loaded upon request either by an import statement or by Angular itself.
Bootstrapping is platform-specific
We import the
bootstrap function from
angular2/core. There's a good reason.
We only call "core" those capabilities that are the same across all platform targets. True, most Angular applications run only in a browser and we'll call the bootstrap function from this library most of the time. It's pretty "core" if we're always writing for a browser.
But it is possible to load a component in a different enviroment. We might load it on a mobile device with Apache Cordova We might wish to render the first page of our application on the server to improve launch performance or facilitate SEO.
These targets require a different kind of bootstrap function that we'd import from a different library.
Why do we create a separate boot.ts file?
The boot.ts file is tiny. This is just a QuickStart.
We could have folded its few lines into the
and spared ourselves some complexity.
We didn't for what we believe to be good reasons:
- Doing it right is easy
- Separation of concerns
- We learned about import and export
Sure it's an extra step and an extra file. How hard is that in the scheme of things?
We'll see that a separate
boot.ts is beneficial for most apps
even if it isn't critical for the QuickStart.
Let's develop good habits now while the cost is low.
We should be thinking about testability from the beginning even if we know we'll never test the QuickStart.
It is difficult to unit test a component when there is a call to
bootstrap in the same file.
As soon as we load the component file to test the component,
bootstrap function tries to load the application in the browser.
It throws an error because we're not expecting to run the entire application,
just test the component.
bootstrap function to
boot.ts eliminates this spurious error
and leaves us with a clean component module file.
We refactor, rename, and relocate files as our application evolves.
We can't do any of those things while the file calls
we can't move it.
We can't reuse the component in another application.
We can't pre-render the component on the server for better performance.
Separation of concerns
A component's responsibility is to present and manage a view.
Launching the application has nothing to do with view management. That's a separate concern. The friction we're encountering in testing and reuse stems from this unnecessary mix of responsibilities.
While writing a separate
boot.ts file we learned an essential Angular skill:
how to export from one module and import into another.
We'll do a lot of that as we learn more Angular.