angular2-rollup

angular2-rollup

A complete, yet simple, starter for Angular 2 using AOT Compile and Rollup. Supports RC.7 and now 2.0.0!

This repo serves as an Angular 2 starter for anyone looking to get up and running fast with Angular 2 and TypeScript and Ahead Of Time (AOT) compilation. We're using ngc for compiling AOT and Rollup for bundling our files for production. The development server compiles just in time (JIT) using Typescript and SystemJS for fast and efficient development.

node scripts written with ShellJS allow for cross platform support for the dev environment. A boilerplate Express server is also included with support for livereload.

We're also using Protractor for our end-to-end story and Karma for our unit tests.

• Best practices in file and application organization for Angular 2.
• Ready to go build system using ngc and Rollup.
• Testing Angular 2 code with Jasmine and Karma.
• Coverage with Istanbul
• End-to-end Angular 2 code using Protractor.
• Stylesheets with SASS and PostCSS.
• Error reporting with TSLint and Codelyzer.

Warning: Make sure you're using the latest version of Node.js and NPM

Quick start

Clone/Download the repo then edit app.ts inside /src/app/app.component.ts

clone the repo

$ git clone https://github.com/steveblue/angular2-rollup my-app

change directory to your app

$ cd my-app

install the dependencies with npm

$ npm install

Install the server config

Change the host and/or port in /conf/config.local.js if needed. This config is used for the Express Server.

{
   origin: 'localhost',
   port: 4200
};

Build, start the server and watchers

$ npm start

Optionally, set environment variables

$ NODE_ENV=prod npm start

In a second tab, start the Express Server

$ node server

Table of Contents

• Getting Started
  • Dependencies
  • Installing
  • Developing
  • Testing
  • Production
• Frequently asked questions
• TypeScript
• License

Getting Started

Dependencies

What you need to run this app:

• node and npm (Use NVM)
• Ensure you're running Node (v5.x.x+) and NPM (3.x.x+)

Installing

• fork this repo
• clone your fork
• npm install to install all dependencies

###Configure Server

Server configuration happens per environment. Currently two environments are supported: dev and prod. Create config files for each environment in the conf/ directory called config.local.js and config.prod.js.

The configuration file only takes two arguments for now: origin and port. server.js uses this configuration to initialize an Express Server either for development or production. A basic config looks like this:

const config = {
                 origin: 'localhost',
                 port: 4200
               };

module.exports = config;

When everything is setup correctly, you should be able to visit http://localhost:4200 in your browser.

Developing

After you have installed all dependencies you can now build the project:

• npm start && node server
• node server

build.js will build the application for development. server.js will start a local server using Express and liveserver will watch for changes in the /dist directory.

Testing

NOTE: If you find issues scaling the test environment, please submit a Pull Request with bug fixes and feature requests.

1. Unit Tests

• single run: npm test

2. End-to-End Tests (aka. e2e, integration)

• single run:
  • in a tab: npm start
  • in a new tab if not already running!: npm run webdriver:start
  • in a new tab: npm run dev:server
  • in another new tab: npm run e2e
• interactive mode:
  • instead of the last command above, you can run: npm run e2e:live
  • when debugging or first writing test suites, you may find it helpful to try out Protractor commands without starting up the entire test suite. You can do this with the element explorer.
  • you can learn more about Protractor Interactive Mode here

Production

The production build is quite different than development. While the development server uses Angular Just In Time (JIT) compilation in conjunction with tsc, the production build uses ngc to compile the Angular 2 application Ahead of Time (AOT).

1. ngc has compiles the files in /src to /tmp,

2. Rollup bundles the files and their dependencies into dist/bundle.es2015.js.

3. Closure Compiler optimizes the bundle and outputs ES5 for the browser.

Since the bundle is still ES2015, we need to transpile the bundle into ES5. For this purpose, we tested multiple solutions and found the best option to either be Typescript (which failed after the update to RC.6) and Closure Compiler.

In order to build for production, you need to install Closure Compiler. Closure Compiler is the only tool that we found would transpile the ES2015 Rollup Bundle to ES5 with 100% reliability after it was processed with ngc. Closure Compiler is also a great solution because it optimizes the bundle and does code checking after Rollup tree shakes the application. Google uses Closure Compiler internally to optimize JavaScript files for production.

To run Closure Compiler, you need to install the Java SDK and the application file found at the bottom of this page. Rename the .jar file (ex: closure-compiler-v20160822.jar ) to compiler.jar and copy it into the project root directory (./compiler.jar). This file is in the .gitignore, which is why you have to manually install it. We tested the JavaScript version of Closure Compiler and found it resulted in out of process memory issues with multiple versions of node, which is why the Java application is necessary.

To build your application, run:

• NODE_ENV=prod npm start

You can now go to /dist and deploy that to your server!

FAQ

Do I need to add script / link tags into index.html ?

Yes, as of right now this starter package will not handle this for you. The typical Angular 2 dependencies have been added already. Configure more dependencies to be included in your web app in paths.config.js. A script runs that copies each dependency from node_modules into /dist/lib (or wherever you specify in the config). You can then reference the library in src/public/index.html like so:

    <script src="/lib/zone.js/dist/zone.js"></script>
    <script src="/lib/reflect-metadata/Reflect.js"></script>

or with SystemJS like so:

<script>

   Promise.all([
      System.import('firebase'),
      System.import('app')
   ]);

</script>

How to include external libraries?

It's simple, just install the lib via npm, add the library to the build in paths.config.js and inject the library via SystemJS in src/public/system.config.js and index.html for development and src/public/system.config.prod.js and system.import.js for production.

How do I bundle external libraries for production?

You can bundle external dependencies with Rollup. Out of the box there is support for projects that use ES2015 modules in rollup.config.js. For instance, we alias the ES2015 version of rxjs when bundling like so:

plugins: [
  alias({ rxjs: __dirname + '/node_modules/rxjs-es' }),
  replace({ 'ENVIRONMENT': JSON.stringify( 'production' ) }),
  resolve({ module: true }),
  cleanup()
]

A Rollup plugin does exist that will transform commonjs modules to ES2015 for the bundle called rollup-plugin-commonjs and it is included in package.json by default. If someone gets this working with the current build we'd love to see examples!

TypeScript

To take full advantage of TypeScript with autocomplete you would have to use an editor with the correct TypeScript plugins.

Use a TypeScript-aware editor

We have good experience using these editors:

• Visual Studio Code
• Webstorm 11+
• Atom with TypeScript plugin
• Sublime Text with Typescript-Sublime-Plugin

License

MIT