Angular Librarian

An Angular 2+ scaffolding setup. Generates AOT-compliant code using similar paradigms to the Angular CLI.

To Use the ngl Command

The ngl command does not install globally by default. To get it working there are some additional steps. To learn how to install it on your system, take a look at CLI.md .

If you do not want to use the ngl command, please see the commands in "Generative Commands" and "Project Commands" for the alternative usage.

Usage

Create a new folder and initialize an NPM project:

> mkdir my-lib > cd my-lib > npm init -f

Install this package to your project:

> npm i -D angular-librarian

The following command ( ngl ) is not available out of the box. To set it up, see "To Use the ngl Command".

Then initialize your project:

> ngl i Library name: my-lib README Title: My Library Repository URL: https://github.com/me/my-lib Reinitialize Git project ( y/N ) ? Installing Node modules ...NPM install occurs Node modules installed

Generative Commands

Generative commands create files for different parts of your library. There are multiple ways to execute commands:

ngl < command_name > [ < args > ]

or

npm run g < command_name > [ < args > ]

or

node ./node_modules/angular-librarian < command_name > [ < args > ]

The ngl command-line tool and npm run g are both aliases for calling node ./node_modules/angular-librarian . Note that all arguments are optional.

Command Purpose initial Sets up the project component Creates a component directive Creates a directive pipe Creates a pipe service Creates a service

initialize (aliases: i, init)

Sets up the project. Can also be run to update a project to the latest Angular Librarian configuration.

Call signature

ngl i < options > ngl init < options > ngl initialize < options > npm run g i < options > npm run g init < options > npm run g initialize < options >

Options

--no-install / --ni : Skip installing Node modules

Prompts

Library name: a dash-cased name that is used in constructing the package.json and *.module.ts file. It is also used to create the class name of the module.

a dash-cased name that is used in constructing the and file. It is also used to create the class name of the module. Prefix (component/directive selector): an optional prefix to prepend to any components and directives in your library; leave blank to use no prefix

an optional prefix to prepend to any components and directives in your library; leave blank to use no prefix README Title: the string to insert in the README.md file

the string to insert in the file Repository URL: the repository where the code will be held

the repository where the code will be held Reinitialize Git project (y/N)? : if left blank, defaults to no. If yes or y are entered, it will reinitialize a git project.

Output

Creates the project structure and a slew of files:

|__examples/ |__example.component.html |__example.component.ts |__example.main.ts |__example.module.ts |__index.html |__node_modules/ |__... |__src/ |__<library name>.module.ts |__index.ts |__test.ts |__webpack/ |__webpack.dev.js |__webpack.test.js |__.gitignore |__.npmignore |__index.ts |__karma.conf.js |__package.json |__README.md |__tsconfig.json |__tslint.json

examples/ : where the example usage of the library can be shown

: where the example usage of the library can be shown examples/example.component.html : the example application's root component template

: the example application's root component template examples/example.component.ts : the example application's root component

: the example application's root component examples/example.main.ts : the example application's main file

: the example application's main file examples/example.module.ts : the example application module

: the example application module examples/index.html : the example application's main HTML file

: the example application's main HTML file node_modules/ : where the dependencies installed via NPM are stored

: where the dependencies installed via NPM are stored src/ : where the bulk of application & test code is.

: where the bulk of application & test code is. src/<library name>.module.ts : the main module of the library

: the main module of the library src/index.ts : a barrel file for easy exporting of classes; makes it easier on consumers to access parts of the code for importing.

: a barrel file for easy exporting of classes; makes it easier on consumers to access parts of the code for importing. webpack/ : contains the Wepack configuration files

: contains the Wepack configuration files webpack/webpack.dev.js : this file is used when running the webpack-dev-server

: this file is used when running the webpack-dev-server webpack/webpack.test.js : used when running unit tests

: used when running unit tests .gitignore : the list of file & folder patterns to not commit to git

: the list of file & folder patterns to not commit to git .npmignore : the list of file & folder patterns to not publish to NPM

: the list of file & folder patterns to not publish to NPM index.ts : another barrel file

: another barrel file karma.conf.js : the testing setup for the project

: the testing setup for the project package.json : holds the list of dependencides for the project, scripts, and other metadata about the library

: holds the list of dependencides for the project, scripts, and other metadata about the library README.md : a markdown file best used for providing users with an overview of the library

: a markdown file best used for providing users with an overview of the library test.ts : contains code needed to get the Angular test environment bootstrapped

: contains code needed to get the Angular test environment bootstrapped tsconfig.json : the TypeScript configuration for the project

: the TypeScript configuration for the project tslint.json : the linting rules for the project

: the linting rules for the project vendor.ts : contains a list of dependencies that Angular needs loaded before the application is loaded

component (alias: c)

Generates a component

Call signatures

ngl c < options > ngl component < selector > < options > npm run g c < options > npm run g component < selector > < options >

Options

--defaults / -d : Create a component with file-based templates & styles, no lifecycle hooks

/ : Create a component with file-based templates & styles, no lifecycle hooks --examples / -x : Generate the component in the examples directory

/ : Generate the component in the directory --hooks=<list of hooks> / --h=<list of hooks> : Use the provided lifecycle hooks.

/ : Use the provided lifecycle hooks. --inline-styles / --is : Use inline styles

/ : Use inline styles --inline-template / --it : Use an inline template

Prompts

What is the component selector (in dash-case)? : the selector for the component. This prompt is skipped if a selector is provided when the command is made. The selector is used to generate the component filenames and class name.

: the selector for the component. This prompt is skipped if a selector is provided when the command is made. The selector is used to generate the component filenames and class name. Use inline styles (y/N)? : if the user provides n , no , or a blank, the component is set up with non-inline styles. If the user provides y or yes , the component is set up with inline styles.

: if the user provides , , or a blank, the component is set up with non-inline styles. If the user provides or , the component is set up with inline styles. Use inline template (y/N)? : if the user provides n , no , or a blank, the component is set up with a non-inline template. If the user provides y or yes , the component is set up with an inline template.

: if the user provides , , or a blank, the component is set up with a non-inline template. If the user provides or , the component is set up with an inline template. Lifecycle hooks (comma-separated): users can pass a list of lifecycle hooks in a comma-separated list which will then be added to the component. Understood values are: changes , check , destroy , init , onchanges , docheck , ondestroy , and oninit .

Output

In the src directory, a sub-directory will be created with the selector name and a component.ts , component.spec.ts , and, if necessary, component.html and component.scss files.

| __src | __ < selector > | __ < selector > .component.html | __ < selector > .component.scss | __ < selector > .component.spec.ts | __ < selector > .component.ts

directive (alias: d)

Generates a directive

Call signatures

ngl d < options > ngl directive < directive-name > < options > npm run g d < options > npm run g directive < directive-name > < options >

Options

--examples / -x : Generate the directive in the examples directory

Prompts

Directive name (in dash-case): this prompt is asking for the name of the directive, in dash-case. If the directive name is provided when the command is executed, this prompt is skipped. The directive name is used to generate the directive's filenames, class name and the actual directive used in templates.

Output

In the src directory, under a directives sub-directory, two files will be added for a service--a directive.ts and directive.spec.ts file.

| __src | __directives | __ < directive-name > .directive.spec.ts | __ < directive-name > .directive.ts

service (alias: s)

Generates a service

Call signatures

ngl s < options > ngl service < service-name > < options > npm run g s < options > npm run g service < service-name > < options >

--examples / -x : Generate the service in the examples directory

Prompts

Service name (in dash-case): this prompt is asking for the name of the service, in dash-case. If the service name is provided when the command is executed, this prompt is skipped. The service name is used to generate the service's filenames and class name.

Output

In the src directory, under a services sub-directory, two files will be added for a service--a service.ts and service.spec.ts file.

| __src | __services | __ < service-name > .service.spec.ts | __ < service-name > .service.ts

pipe (alias: p)

Generates a pipe

Call signatures

ngl p < options > ngl p < pipe-name > < options > npm run g p < options > npm run g p < pipe-name > < options >

--examples / -x : Generate the pipe in the examples directory

Prompts

Pipe name (in dash-case): this prompt is asking for the name of the pipe, in dash-case. If the pipe name is provided when the command is executed, this prompt is skipped. The pipe name is used to generate the pipe's filenames, class name and the actual pipe used in templates.

Output

In the src directory, under a pipes sub-directory, two files will be added for a service--a pipe.ts and pipe.spec.ts file.

| __src | __pipes | __ < pipe-name > .pipe.spec.ts | __ < pipe-name > .pipe.ts

Project Commands

There are commands provided out of the box, as NPM scripts. They are:

Command Purpose build Runs code through build process via Angular compiler (ngc) lint Verify code matches linting rules publish Creates tag for new version and publishes serve Run Webpack's dev-server on project test Execute unit tests upgrade Upgrade current project to latest Angular Librarian

build (alias: b)

Build the library's code. This will run the code through the ngc compiler and compile the code for distribution.

Call signatures

ngl build ngl b npm run build

lint (alias: l)

Lint code through TSLint

Call signatures

ngl lint ngl l npm run lint

publish (alias: pub)

Create a tag and publish the library code using the np library. Optionally, arguments can be passe to make the build work faster.

Note: only use the optional arguments if you are 100% confident your code works with the current dependencies & passes all tests!

Important! To use Librarian's publishing capabilities, you need to have np installed globally. This is required because Angular & np require separate versions of RxJS. Using the Angular-required version of RxJS will break np and using np 's will raise a peerDependency warning. You can install np by running the following command: npm install -g np

Call signatures

ngl publish < option > ngl pub < option > npm run tagVersion < option >

no-cleanup / nc : publishes but does not do a cleanup of node_modules

/ : publishes but does not do a cleanup of yolo / y : publishes but does not do a cleanup of node_modules nor does it run tests.

serve (alias: v)

Start the webpack dev server and run the library code through it.

Call signatures

ngl serve ngl v npm start

We use start for direct npm commands to keep the command as concise as possible.

test (alias: t)

Run unit tests on code. For unit test types, see the unit testing section below.

Call signatures

ngl test < type > ngl t < type > npm test < type >

upgrade (alias: u, up)

Upgrades the current project to the latest Angular Librarian (if necessary) and update managed files to the latest versions.

Managed files are:

.gitignore *

* .npmignore *

* karma.conf.js

package.json *

* tsconfig.es2015.json

tsconfig.es5.json

tsconfig.json

tsconfig.test.json

tslint

src/test.js

tasks/

webpack/

Any files with a asterisk (*) next to their name have a merge strategy associated with them:

.gitignore and .npmignore will take any custom lines (case-sensitive) and add them to the new file

and will take any custom lines (case-sensitive) and add them to the new file package.json will ensure any dependencies you've added are kept in the dependencies and devDependencies attributes, as necessary.

Call signatures

ngl upgrade ngl up ngl u npm run g upgrade npm run g up npm run g u

Unit Testing

Unit testing is done using Karma and Webpack. The setup is all done during the initialize command. The provided testing commands will watch your files for changes.

The following commands are described in the test command section.

These commands call the script at tasks/test.js and runs the Karma test runner to execute the tests. Prior to running Karma, the test command looks for a command line argument, if the argument is known, it will run the associated configuration, otherwise it will run the default configuration.

Configurations:

Command Testing TypeScript default Run through PhantomJS one time with no file watching headless (aliases: hl, h) Run through PhantomJS with files being watched & tests automatically re-run watch (alias: w) Run through Chrome with files being watched & tests automatically re-run

Note that Chrome still requires a manual refresh on the Debug tab to see updated test results.

Custom Configurations

Some configurations can be extended with custom properties. These configurations should be placed in a configs directory under the project's root directory with the corresponding name:

Karma Configuration

A custom Karma configuration should be a Node module that exports a function. The exported function will be relay the Karma config variable. If provided, any supported attributes provided will be merged.

Those attributes and their merge strategies are:

Array attributes will create an array of unique values for that attribute and append the existing attribute; these fields are: browsers files plugins reporters

Objects will append new keys, but keep any existing ones--making it so values provided by Angular Librarian can not be overridden: preprocessors

Primitive values will be replaced: color logLevel port



Rollup Configuration

The rollup configuration will append the provided attributes to create a new attribute of unique values. The attributes supported:

commonjs : a list of CommonJS dependencies to pull in. Will always include node_modules/rxjs/** to properly rollup RxJS.

: a list of CommonJS dependencies to pull in. Will always include to properly rollup RxJS. external : creates a new array of unique values

: creates a new array of unique values globals : adds new attributes to the object

Note: there is no file provided named rollup.config.js like other configuration files--instead the configuration is maintained in tasks/rollup.js .

Webpack Configurations

Either of the Webpack configurations can be extended by providing a file with a matching name in configs . The configuration is applied using the webpack-merge library.

Packaging

To test your packages output before publishing, run the following commands:

ngl build cd dist npm pack

These commands will build the output files into a dist directory, change into the dist directory, and generate a compressed file containing your library as it will look when packaged up and published to NPM. The packaging process removes any files specific to developing your library, such as *.spec.ts files and .npmignore .

Unscoped Structure

The basic structure of a published, unscoped library is:

|__bundles/ |__<library name>.umd.js |__<library name>.umd.js.map |__<library name>.umd.min.js |__<library name>.bundle.min.js.map |__index.d.ts |__package.json |__README.md |__*.d.ts |__<library name>.d.ts |__<library name>.es5.js |__<library name>.es5.js.map |__<library name>.js |__<library name>.js.map |__<library name>.metadata.json |__<library name>.module.d.ts

Scoped Structure

For a scoped package, the structure will appear slightly different:

|__@<scope name>/ |__<library name>.es5.js |__<library name>.es5.js.map |__<library name>.js |__<library name>.js.map |__bundles/ |__<library name>.umd.js |__<library name>.umd.js.map |__<library name>.umd.min.js |__<library name>.bundle.min.js.map |__index.d.ts |__package.json |__README.md |__*.d.ts |__<library name>.d.ts |__<library name>.metadata.json |__<library name>.module.d.ts

Contributing

If you'd like to contribute to Angular Librarian, please see the contributing guide!