angular-rollup

angular-rollup

CLI for bundling Angular with Rollup and Closure Compiler.

Main Features

• ngr cli for running builds, code generation, scaffolding and more

• Fast dev environments use JIT Compiler or ngc in --watch mode

• Highly optimized bundle for production using Closure Compiler

• Lazyload optimized bundles with SystemJS and Closure Compiler

• Build library packages that follow Angular Package Format 4.0

• Follows Angular Styleguide

• Ready to go build system using ngc, Rollup, and Closure Compiler

• Test 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

Quick start

NOTE: This package requires python and java JDK to be installed prior to installion. Several dependencies require these services.

• Install the cli and global dependencies

$ npm install -g angular-rollup webdriver-manager codelyzer rimraf

• Scaffold a new project and install dependencies

$ mkdir my-new-app && cd my-new-app
$ ngr scaffold && npm install

• Run development build, start up Express Server with LiveReload

$ ngr build dev --jit --serve --watch pre 5.0.0

$ ngr build dev --serve --watch post 5.0.0

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

Table of Contents

• Getting Started
  • Dependencies
  • Install
  • Server
  • Config
  • Scaffold
  • Update
• Develop
  • Build
  • Testing
• CLI
• Frequently Asked Questions
• License

Getting Started

Dependencies

What you need to run this app:

• node and npm (Use NVM)
• Ensure you're running Node (v6.5.x+)

Install

Read the Quick Start

• Install dependencies

To run Closure Compiler, you need to install the Java SDK. Selenium Webdriver requires Python. This project requires node ~6.9.0 to be installed.

• Install the cli and global npm dependencies

$ npm install -g angular-rollup webdriver-manager codelyzer rimraf

• Scaffold a new project and install project dependencies

$ mkdir my-new-app && cd my-new-app
$ ngr scaffold && npm install

Configure Server

Change the host and/or port in /server.config.dev.js if needed. This config is used for the Express Server. /server.config.prod.js is used for production.

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

Server

Express is used mainly to provide a development server, but it could also be configured for production to run over https.

node server.js is run as a parallel process to the build when using the --serve flag

router.js configures the routes of the Express server

Config

There is a lot of config in this project to allow finetuning each build to developer specifications. build.config.js lets you configure filepaths, SASS options, and includes callbacks for steps in each build.

Script	Description
build.config.js	Project filepaths, dev, lib, and prod builds
karma.conf.js	Karma
postcss.*.js	PostCSS (prod,lib)
rollup.config.*.js	Rollup (prod,lib)
closure.conf	Closure Compiler (prod) when using the --closure flag
closure.lazy.conf	Closure Compiler (prod) when using the --closure and --lazy flags
server.config.*.js	Express Server
jsconfig.json	VSCode editor
tsconfig.*.json	Configures TypeScript (dev) or @angular/compiler (lib,prod)

build.config.js

Property	Description
dep	Files and folders that should be copied to /build/lib
clean	Paths of files and folders to clean in the /build directory after /src/public is copied to /build
style	Options passed to SASS
src	Path to src folder
build	Path to build folder
dist	Path to dist directory for the library build
lib	Path to library root folder
libFilename	filename used for bundles created during library build
classPrefix	Prefix used when declaring Class
componentPrefix	Prefix used when declaring selector for Components
directivePrefix	Prefix used when declaring selector for Directives

Scaffold

To scaffold a new app run ngr scaffold. This will copy required files into the same directory.

To scaffold at a specific version of @angular use --angularVersion i.e. ngr scaffold --angularVersion 4.2.2

If you want access to the library build, use ngr scaffold --lib

Update

To update to specific version of @angular use --angularVersion i.e. ngr update --angularVersion 4.2.2

Develop

Build

To build the app for development, enable livereload, and start up the server:

• $ ngr build dev --watch --serve -jit

ngr will build the application for development. Using --jit bootstraps Angular with JIT Compiler.

Once your work has been validated with the development build, you can also test the production build.

It is recommended to bundle with Closure Compiler in ADVANCED_OPTIMIZATIONS mode.

• $ ngr build prod --closure --serve

The production build also supports lazy loading with Closure Compiler.

• $ ngr build prod --closure --lazy --serve

You can also bundle with Rollup and then optimize with ClosureCompiler, but only with SIMPLE_OPTIMIZATIONS

• $ ngr build prod --serve

Production Builds

While the development build 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).

AOT is more secure than JIT and should always be used in a production environment.

Here's how is works:

1. The @angular/compiler package uses ngc to AOT compile the files in /src to /ngfactory,

2. Closure Compiler optimizes any bundles and outputs ES5 for the browser.

Package Spec 4.0 Library Build

• $ ngr build lib

ngr provides a build for developing Angular libraries that conforms to the Angular Package Spec 4.0.

Jason Aden gave a presentation about Angular Package Spec 4.0 at ng-conf 2017. Packaging Angular.

To develop component libraries, scaffold an app with the --lib flag.

tsconfig.lib.json and tsconfig.lib.es5.json configure ngc during the library build.

The library build is configured in build.config.js.

Testing

1. Unit Tests

Unit tests use Karma and can be run with the --watch flag.

For single run ngr --test

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

e2e tests use Protractor and Selenium Webdriver. The process requires multiple tabs to run locally.

1. In a new tab: if not already running! npm run webdriver:start
2. In a new tab: ngr build dev --serve

• Single run: 3. In a new tab: npm run e2e

• Interactive mode: 3. In a new tab: 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. Learn more about Protractor Interactive Mode here.

CLI

This starter code includes a CLI that allows you to build and start up an Express Server without npm run. The CLI includes commands for generating new code snippets similar to Angular CLI.

To use the CLI run the command npm install -g while in the root directory of the project, then npm link. webdriver-manager should also be installed globally if it isn't already.

npm install -g npm link

CLI Commands

ngr --help

Displays the help documentation for using ngr

generate

ngr generate, g

The easiest way to generate code is to use the wizard.

ngr generate wizard

Example of output from the wizard:

$ ngr generate wizard
$ ngr codegen wizard
$ filename: kabab-case filename i.e. global-header
$ directory: path/to/folder i.e. src/app/shared/components/global-header
$ type: module, component, directive, enum, e2e, guard, interface, pipe, service
$ Follow the prompts after selecting a type
filename:  global-header
directory:  src/app/shared/components/global-header
type:  module
component:  y
directive:  n
routes:  n
unit:  y
e2e:  n
[15:38:18] LOG global-header.component.html copied to global-header
[15:38:18] LOG global-header.component.scss copied to global-header
[15:38:18] LOG global-header.component.ts copied to global-header
[15:38:18] LOG global-header.module.spec.ts copied to global-header
[15:38:18] LOG global-header.module.ts copied to global-header

Optionally, you can trigger codegen via the CLI with arguments.

You can pass the following types to generate:

• class
• component
• directive
• enum
• e2e
• guard
• interface
• module
• pipe
• service

EXAMPLE: ngr generate service --name todo-list --dir path/to/folder

When generating a module, there is an optional --include flag what will auto import various other types into the Module, scaffold spec and e2e tests.

• ngr generate module --name todo-list --include route,component,route,directive

This example generates files for configuring routes, component, and directive and then auto imports those files into the module.

You can configure prefixes for Classes, Component and Directive selector in build.config.js. Omit the properties from the config to operate without prefixes. Defaults are included that follow the Angular Styleguide.

--serve & --watch

You can choose to run an Express server in parallel with build tasks, with or without Livereload enabled

• ngr build dev --watch --serve Builds development environment, runs Express server with livereload
• ngr serve Runs Express server, make sure you have built beforehand!

Production builds do not require the CLI, just the package.json

• NODE_ENV=prod node server.js --https Run Express server with SSL for production, requires ./conf/ssl/key.pem and ./conf/ssl/cert.pem.

FAQ

How do I include third party libraries?

Follow this step by step questionaire to figure out which method to use.

• Does the library conform to Angular Package Spec 4.0? YES: Will be bundled by ngc, inject the NgModule into your application NO: See next question

• Is the library compatible with ClosureCompiler in ADVANCED_OPTIMIZATIONS? YES: Bundle without Rollup using the --closure flag. NO: See next question

• Is the library written in ES2015? YES: Can most likely be bundled with Rollup NO: See next question

• Is the library formatted with UMD modules? YES: Edit rollup.config.js so Rollup can bundle the library NO: You must include the library globally via <head> or SystemJS. Examples of both are in /src/public/index.html

RxJS is bundled as UMD module. In rollup.config.js, use the rollup-plugin-commonjs to bundle it via the Rollup build step.

   commonjs({
    include: 'node_modules/rxjs/**'
   }),

Configure SystemJS for the dev build

You must configure system.config.js in order to inject third party libaries for development. An example is below:

   map: {
      // angular bundles
      '@angular/core': 'lib:@angular/core/bundles/core.umd.js',
      '@angular/common': 'lib:@angular/common/bundles/common.umd.js',
      '@angular/compiler': 'lib:@angular/compiler/bundles/compiler.umd.js',
      '@angular/platform-browser': 'lib:@angular/platform-browser/bundles/platform-browser.umd.js',
      '@angular/platform-browser-dynamic': 'lib:@angular/platform-browser-dynamic/bundles/platform-browser-dynamic.umd.js',
      '@angular/http': 'lib:@angular/http/bundles/http.umd.js',
      '@angular/router': 'lib:@angular/router/bundles/router.umd.js',
      '@angular/forms': 'lib:@angular/forms/bundles/forms.umd.js',
      // other libraries
      'rxjs': 'lib:rxjs',
      'firebase': 'lib:firebase/firebase.js',
      'firebase/app': 'lib:firebase/firebase.js',
      'firebase/database': 'lib:firebase/firebase.js',
      'firebase/auth': 'lib:firebase/firebase.js'
    }

You can include third party dependencies with SystemJS instead of the <head>.

<script>

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

</script>

If a library must be loaded prior to bootstrap, add the folder name in build.config.js to have it copied into build/lib. It is optimal to only include the library files you need for production, not entire folders.

You must also edit public/index.html and the systemjs config files to load libraries prior to the app bootstrapping.

module.exports = {
    dep: {
        lib: [
          'core-js',
          'reflect-metadata',
          'zone.js',
          'systemjs',
          '@angular',
          'rxjs'
        ],
        prodLib: [
          'core-js/client/shim.min.js',
          'core-js/client/shim.min.js.map',
          'systemjs/dist/system.js',
          'zone.js/dist/zone.js'
        ],
        src: './node_modules',
        dist: './build/lib'
    },

Bundling libraries written in ES2105 Modules

It is a best practice to tree shake and bundle third party libraries for production, however this process only works with Rollup if the third party library is packaged with ES2015 modules. It is also not recommended to import an entire library that is treeshakable like so:

import Rx from "rxjs/Rx";

While you could do this, it is a best practice to only import the methods of the library your app requires.

import "rxjs/add/observable/interval";
import "rxjs/add/operator/take";
import "rxjs/add/operator/map";
import "rxjs/add/operator/bufferCount"

If you import an entire library using * for instance, the entire library will be bundled in your application, so import ONLY the methods your application requires for an optimal bundle.

import will only work with libraries packaged with ES2015 modules.

When bundling for production, you may need to also need to update the rollup.config.js file to properly bundle the third party library.

Typings

You may also need to inject typings for the ngc service to properly inject dependencies during AOT compilation.

"compilerOptions": {
  "typeRoots": [ "node_modules/@types" ],
  "types": [
     "node"
  ]
}

Editing index.html

ngr copies each dependency from node_modules into /build/lib (or wherever you specify in build.config.js). You can then reference the library in src/public/index.html like so:

    <script src="/lib/core-js/client/shim.min.js"></script>
    <script src="/lib/zone.js/dist/zone.js"></script>
    <!-- build:remove:prod -->
      <script src="/lib/reflect-metadata/Reflect.js"></script>
    <!-- /build -->

ngr uses htmlprocessor to only include the porttions of index.html the app requires for development and production. You can remove chucks of the file for each build.

The typical Angular 2 dependencies are already included in the <head> tag in index.html.

How can I write a custom build?

You could create a custom build to fit the specific needs of your project. It is recommended to duplicate an existing build and start from there.

build.env.js

In build.env.js:

const env = 'dev';

This build script includes a constant you should change to the new name of the environment if you also want to augment other settings for Rollup, TypeScript, or PostCSS. Otherwise, you can hijack the dev, prod environments. There is an example of how this could be done in build.lib.js.

When duplicating the development build, you can tweak the tsconfig or PostCSS settings.

tsconfig.env.json
postcss.env.json

Configuration for build services are in the specific files, while the config for Closure Compiler is found in package.json. If you are duplicating the production build and renaming the environment, you can augment the options for ClosureCompiler:

"transpile:env": "java -jar ./compiler.jar --warning_level=QUIET --language_in=ES6 --language_out=ES5 --js ./build/bundle.es2015.js --js_output_file ./build/bundle.js",

How do I update my project to the latest CLI?

npm install -g angular-rollup@latest

How do I update my project to the latest versions of Angular?

After you have finished updating the package.json, run the following commands:

• $ ngr update --angularVersion 5.0.0
• $ npm run clean:install

Can I run LiveReload with the Production build?

Livereload is still available in this mode, however you have to go an extra step to unlock this feature for the prod build. We recommend using ngr build dev for development, since the JIT Compiler or ngc in --watch mode allows for a faster workflow. In cases where you want to test the production build on a local machine with the watcher you can use the following command: ngr build dev --watch --serve

For livereload to work in the browser for the production build you currently you have to edit src/public/index.html.

Copy the livereload script to the build:remove:dev comment near the end of the file. It should look like the example below.

    <script>
      document.write('<script src="http://' + (location.host || 'localhost').split(':')[0] +
      ':35729/livereload.js?snipver=1"></' + 'script>')
    </script>
    <!-- /build -->
    <!-- build:remove:dev -->
    <script src="system.import.js"></script>
    <script>
      document.write('<script src="http://' + (location.host || 'localhost').split(':')[0] +
      ':35729/livereload.js?snipver=1"></' + 'script>')
    </script>
    <!-- /build -->

It is not recommended that you deploy the livereload script to production.

How do I take advantage of TypeScript in VSCode?

Configure the jsconfig.json file.

Install the following packages:

Angular Language Service : Editor services for Angular templates Angular Support : Go to / peek angular specific definitions angular2-inline : Syntax highlighting of inline html and css SCSS Intellisense: autocompletion and refactoring of SCSS Path Intellisense: Autocomplete for paths in the project TypeScript Hero: Additional tooling for the TypeScript language

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

Changelog

1.0.0-beta.9

• Fixed issue with update warning

---