ngr

CLI for building Angular with Rollup and Closure Compiler

Main Features

• Extends @angular/cli. Run ng and ngr commands in the same project

• Generates highly optimized bundle using Closure Compiler

• Builds library packages formatted with Angular Package Format

• Includes Express server for ramping up backend NodeJS production

• Stylesheets with SASS and PostCSS

• Follows Angular Styleguide

• Pretty printed error reporting with TSLint and Codelyzer

Table of Contents

• Getting Started

  • Install
  • Scaffold
  • Help

• Development

  • Build
  • Production
  • Hooks
  • Config
  • Server
  • Libraries
  • Schematics, Testing, and i18n

• FAQ

• License

Getting Started

Install

• Install dependencies

Install the Java JDK

• Install the cli and global npm dependencies

$ npm install -g angular-rollup @angular/cli

• Apps are scaffolded just like the @angular/cli. Use ngr instead of ng.

$ ngr new my-app

Scaffold

To scaffold a new app run ngr new my-app. This command will copy required files into the a new directory called my-app and run npm install. Use the --yarn flag to install with it instead.

Migrate existing angular-rollup and @angular/cli projects with --src.

ngr new my-new-app --src /path/to/old/src

Help

ngr --help will list all commands and arguments provided in the cli.

Options:

  -V, --version              output the version number
  new [string]               scaffold new development environment in directory by name, i.e. ngr new my-app
  --src [string]             specify a path to an existing src folder
  --skip-install [bool]      prevents install during scaffold
  --yarn [bool]              use yarn instead of npm to install
  --prettier [bool]          scaffold a new workspace with prettier installed
  --ssl [bool]               scaffold a new workspace with https express server
  --angularVersion [string]  scaffold a new workspace with a specific version of angular
  build [env]                build the application
  --env [string]             use that particular environment.ts during the build, just like @angular/cli
  --clean [bool]             destroy the build folder prior to compilation, default for prod
  --watch [bool]             listen for changes in filesystem and rebuild
  --config [string]          path to configuration file for library build
  --deploy [bool]            call deploy build hook for library build
  --verbose [bool]           log all messages in list format
  --closure [bool]           bundle and optimize with closure compiler (default)
  --rollup [bool]            bundle with rollup and optimize with closure compiler
  --webpack [bool]           use @angular/cli to build
  g, generate [string]       generate schematics packaged with angular-rollup
  serve, --serve [bool]      spawn the local express server
  -h, --help                 output usage information

Development

Build

ng serve to build for development using @angular/cli.

Production

• $ ngr build prod

You can choose to bundle with Rollup instead and simplify Closure Compiler's configuration, at the expense of bundle size.

• $ ngr build prod --rollup

Use native ng commands for webpack.

• $ ng build --prod

To build an application for production and serve it locally:

• $ ngr build prod --serve

Build Hooks

Hooks are points in the build where you can inject custom functionality. Each build has a pre and post hook. All hooks except post require that you return a Promise. There is a watch hook for the development build that takes two parameters: dist and src. There is a deploy hook for the library build to run additional scripts for deployment.

    hooks: {
        prod: {
            pre: () => {
                return new Promise((res, rej) => {
                    // do something
                    res();
                })
            },
            post: () => {
              // do something
            }
        }
    }

ngr.config.js

Config is shared with angular.json but for non Webpack builds the following files allow you configure filepaths, SASS options, and includes callbacks for steps in each build.

Server

Express is used mainly to provide a development server, but it could also boilerplate for a MEAN stack.

server.js and router.js are stored in the backend folder.

ngr serve will start up the Express server, so will --serve with any build.

Configure Server

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

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

Libraries

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

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

Generate A Library Package

Generate library packages with ngr generate lib my-lib-name.

This will generate a library package in the current folder with the necessary configuration set in ngr.config.js.

Tips For Developing A Library

• Keep your code strictly typed.
• Do not create monolithic @NgModule. Separate modules by discrete functionality. This allows the library to be treeshaken.
• In each module.ts export public components, directives, services, etc.
• Update the library index.ts with export for each module.

Build Library

After you have generated some components for the library, use ngr build lib to build the library in the dist folder.

ngr build lib my-lib-name

Use @angular/cli for Schematics, Testing, and i18n

ng generate works in angular-rollup!

Use ng test and ng e2e for unit and end to end tests, respectively.

FAQ

How do I include third party libraries?

The production build relies heavily on Closure Compiler, which optimizes the bundle far better than other tools. Closure Compiler relies on annotations in JavaScript to optimize the bundle. Third party libraries are often not annotated. If a library package follows the Angular Package Format it will be closure annotated because when configured, the angular compiler will convert TypeScript annotations to closure annoations using a tool called tsickle. Luckily for third party libraries that are not annotated, Closure Compiler can be configured to leave variables found in external scripts unmangled. Follow this step by step to figure out which method to use.

• Does the library conform to Angular Package Format? YES: Will be bundled by ngc, inject the NgModule into your application, add to closure.conf NO: See next question

• Is the library written in ES2015? YES: Include the necessary library files in closure.conf NO: See next question

• Is the library formatted with UMD modules? YES: Include the necessary library files in closure.conf NO: You must include the library globally via <head> or SystemJS. Add the necessary externs to closure.externs.js

How do I load a library in index.html?

If a library must be loaded prior to bootstrap, add the folder name in ngr.config.js to have it copied into dist directory during the build.

Add the script in the <head> or you can include third party dependencies with SystemJS.

<script>

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

</script>

For production, ngr will concatenante library packages into vendor.js. For development, all libarary files are copied to the dist folder.

Vendor files are configured in ngr.config.js like in this example:

lib: {
    dev: [
        'core-js/client/shim.min.js',
        'core-js/client/shim.min.js.map',
        'zone.js/dist/zone.min.js',
        'systemjs/dist/system.js',
        'systemjs/dist/system.js.map',
        'reflect-metadata/Reflect.js',
        'reflect-metadata/Reflect.js.map',
        'tslib/tslib.js',
        '@angular',
        'rxjs'
    ],
    prod: [
        'core-js/client/shim.min.js',
        'zone.js/dist/zone.min.js',
        'systemjs/dist/system.js'
    ],
    src: 'node_modules',
    dist: 'dist/path/to/lib'
}

Why are there 2 different index.html?

angular-rollup uses htmlprocessor to manipulate index.html while webpack works it's magic with the index.html provided by @angular/cli.

src/index.html is used by @angular/cli and webpack. src/public/index.html is used by angular-rollup.

For more information about htmlprocessor; src/public/index.html is manipulated by htmlprocessor. dev and prod environment variables declared via inline comments include chunks of the index.html per environment.

How do I configure SystemJS for dev for jit builds?

You must configure system.config.js in order to inject third party libaries for development. All JavaScript in the development build is compiled into commonjs modules, however the source code is pointing to files packaged with ES2105 modules. In system.config.js map each request for a library script to the umd bundle for the library. The build places each library in the dist/path/to/project/lib folder. SystemJS needs to know where the library is located in the dist/path/to/project/lib folder.

Here is an example of mapping requests for library bundles to umd bundles in system.config.js.

   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/Observable': 'lib:rxjs/Observable',
      'tslib': 'lib:tslib/tslib.js'
    }

How do I import libraries the most optimal way for treeshaking?

It is a best practice to treeshake and bundle third party libraries for production, however this process only works if the third party library is packaged with a module pattern such as ES2015 modules.

It is NOT recommended to import an entire library that is treeshakable.

DON'T DO THIS : import * from 'rxjs'; DO THIS : import { Observable, Observer } from 'rxjs';

It should be noted Closure Compiler relies on named ES2015 modules and cannot handle libraries that import with *. If you want a third party library to be compatible with closure compiler, it is recommended to contribute named imports and exports to the open source project.

How do I provide typings for external libraries?

Type definitions are typically packaged with the @types scope. Install type definitions for third party libraries with npm and list them in the tsconfig.json file in the types Array.

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

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?

• $ ng update

How do I deploy?

The build command has an optional --deploy flag.

Use the post build hook in ngr.config.json to deploy a build. The following example is for a library, but you could use a similar hook for a production build.

Below is an example of copying the dist folder to a sibling directory that also is a git repository. The example uses shelljs.

    hooks: {
        lib: {
            post: (args) => {
                cp('-R', './dist/.', '../'+folderName);
                rm('-rf', './dist');

                if (args.indexOf('deploy=true')) {
                    cd('../'+folderName);
                    exec('git add --all .');
                    exec('git commit -a -m "version bump"');
                    exec('git push origin master');
                }
            }
        }
    }

VSCode Extensions

We like Visual Studio Code. Below are some VS Code Extensions we find useful when developing Angular applications.

License

MIT