June 19, 2016

Angular 2: Official tutorial projects in ES6 + TypeScript + seed! (part 1 of 3)



I created a complete project skeleton based on Angular 2’s official “QuickStart” and “Tour of Heroes” tutorial code samples, and ported them to ECMAScript 6 / 7. Feel free to download them, or read on for Angular 2 project setup instructions.

As an AngularJS developer, I am naturally interested in what is branded as its successor and “the future of web development”. So I started my journey with the official tutorials.

Although these are accompanied by brilliant code samples, what I really wanted was seeing them integrated in a complete project setup as one would see it in a real world project. That’s why I decided to build the official tutorial code samples into an actual project skeleton.

This article discusses:
Feel free to skip to the section which interests you.

Nomenclature note: As in the official documentation, I will refer to the former 1.0 version of Angular as AngularJS, and to the future release 2.0 as Angular 2. Furthermore, I will use ES6 to refer to ECMAScript 6 + experimental features of ECMAScript 7, and ES5 as an abbreviation of ECMAScript 5 (i.e. current browser JavaScript).

Also note that I use the term “official” here to refer to the “official” Angular 2 tutorials which provide parts of the source code of the project setup I am presenting here. I am not affiliated with the Angular 2 project.

The official tutorials, revised

Note that the following are improvement suggestions which I subsequently realized. It’s not my intention to suggest that Angular 2’s original tutorials are bad, much in the contrary, but they didn’t fulfill all my expectations.

ECMAScript and TypeScript

Although Angular 2 proudly (and rightfully) states that their framework works in both plain JavaScript and TypeScript (and Dart), and with the official release date approaching, they have so far neglected to port their official tutorial applications to ECMAScript 6.

Why would I care about ECMAScipt? The Angular 2 website really suggests that TypeScript is the successor of current JavaScript (ECMAScript 5). But it is not. That’s what ECMAScript 6, and 7 is. That’s the official standard. TypeScript is an implementation, and an extension, of that standard. Most importantly and famously, it adds static typing. But that’s just an optional addition.

I believe in gradual adaptation. I think when coming from AngularJS’s pure JavaScript world, ECMAScript 6 should be the next step in order to understand why and when it makes sense to leap even further towards TypeScript. That’s why I decided to port the examples to ECMAScript 6 / 7.

(But I created a complete skeleton with TypeScript as well.)

A build tool

As desribed in the “QuickStart” tutorial GitHub README: “This is not the perfect arrangement for your application. It is not designed for production.”, and “We are unlikely to accept suggestions about how to grow this QuickStart into something it is not.”

This clearly refers to the fact that unlike typical real-world projects, as the average AngularJS developer is expecting to see them, the official tutorial setup comes without a build tool. Rather, the TypeScript compiler is invoked directly via npm, and the code is published to a small “development only” local server.

This, I think, is unfortunate also as it increases coupling between the TypeScript environment and the build process.

Instead, I introduced Grunt, well-known to most AngularJS developers, to handle build and deployment of the application. Of course, you could replace it with the build tool of your choice.

Directory structure

Again: The official tutorial is not set up with production-readiness in mind. I really wanted to bring some structure to the file organization in this project. Most importantly, user-written and transpiled code should be clearly separated.

A clean setup

Finally, I found that due to the fast pace of Angular 2’s development, and the quick succession of new releases, some of which introduce breaking changes, the demo project’s setups (plural, as there are a few of them) aren’t quite up to date, and their configuration doesn’t seem consistent. Therefore, it was my aim as well to present an up-to-date project configuration. (At the time of writing, this is 2.0.0-rc.2 (2016-06-15).)

The official tutorials as a project setup seed

I have built two versions of a complete Angular 2 project setup, based on the source code of two of Angular 2’s official tutorials:
  • The 5 min “QuickStart” tutorial, as discussed here and referred to as the starting point for other official tutorials.
  • The “Tour of Heroes” tutorial, as discussed here, presenting the most important components of Angular 2.
Indeed, there are in general no other changes from one project to another than the actual example business JavaScript / HTML / CSS source code.

According to above reasoning about building a project seed, I have been following roughly these steps to setup the project:
  • Run the Yeoman generator to create an empty AngularJS (sic!) project.
  • Set up the Grunt build tool.
  • Set up the necessary transpilation tasks (see below).
  • Upgrade everything to the newest version (build tools, libraries).
  • Integrate the official tutorial’s source code, as presented in its live Plunker version, into the project.
For each of these projects, I have created a version written in ECMAScript 6 / 7 (which transpiles to ES5 during build time) (i.e. an ES6 port of the original version) and a version written in TypeScript (i.e. a copy of the original version). The separate versions are put in different branches of their respective Git repository.

You can download the sources from their GitHub repositories:
Note that these projects are by no means perfect samples of a very-best-practices Angular 2 project setup. Rather, my aim was to concentrate on the most important parts, keeping the setup clear and comprehensible even for Angular 2 “newbies”.

Most importantly, I have neglected:
  • Testing
  • Code validation / linting
  • Packing / minification
  • Plus potentially some other characteristics of a typical “production-ready” build
The current project setup of course also reflects the current state of my own Angular 2 knowledge. I’m still learning. I’m planning to actually develop these projects further as my knowledge grows. If you have expert knowledge in any of the associated technologies, feel free to contribute to these repositories. Note however that it’s a goal of mine to keep these projects seeds minimalistic and lean.

For now, if you want a more production-ready (however potentially more complex) Angular 2 seed, I recommend you take a look at the repositories linked in the Awesome Angular 2 repository: ES6 seeds, TypeScript seeds.

How is that useful?

I think these two projects might be of great help as you try to follow Angular 2’s official tutorials. Their main advantage over starting with the official QuickStart repository or the inofficial “Tour of heroes” repository is that you get a sound “ready to go” project setup, including an actual build server and a clean directory structure. Still, in contrast to many more advanced Angular 2 project skeletons (see above), they are very minimalistic and easily understandable with at least prior AngularJS knowledge.

You can use one of these projects as a seed to build your own clean Angular 2 project on top of. All you need to do is to delete the example business JavaScript / HTML / CSS source code to get a clean project setup.

However, if you really want to know what is going on under the hood, you should read on to find out how to set up an Angular 2 project, and how it is different from an AngularJS project setup. I highly encourage you to read on, as understanding the way Angular 2 projects work may save you from future project configuration worries.

Pages: 1 2 3