angular-library-set

An Angular 2+ scaffolding setup using erector-set. The intention was to keep creation of an Angular 2+ library as simple and concise as possible.

Important Note

This library is currently under heavy development and you should use it with caution. To get the latest point your package.json to this repository using:

git://github.com/gonzofish/angular-library-set.git**

Usage

Install this package to your project:

npm i -D angular-library-set

Then add it as the "g" command in your package.json:

{
    "scripts": {
        "g": "node ./node_modules/angular-library-set"
    }
}

Then initialize your project:

> npm run g 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

Commands

All commands are run by doing:

npm run g <command_name> [<args>]

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-library-set configuration.

Call signature

npm run g i

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.
• README Title: the string to insert in the README.md file
• Repository URL: 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
• examples/example.component.html: the example application's root component template
• examples/example.component.ts: the example application's root component
• examples/example.main.ts: the example application's main file
• examples/example.module.ts: the example application module
• examples/index.html: the example application's main HTML file
• node_modules/: where the dependencies installed via NPM are stored
• src/: where the bulk of application & test code is.
• src/<library name>.module.ts: 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.
• webpack/: contains the Wepack configuration files
• webpack/webpack.dev.js: this file is used when running the webpack-dev-server
• webpack/webpack.test.js: used when running unit tests
• .gitignore: the list of file & folder patterns to not commit to git
• .npmignore: the list of file & folder patterns to not publish to NPM
• index.ts: another barrel file
• karma.conf.js: the testing setup for the project
• package.json: 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
• test.ts: contains code needed to get the Angular test environment bootstrapped
• tsconfig.json: the TypeScript configuration for the project
• tslint.json: 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

npm run g c
npm run g c <selector>

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

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

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

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

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

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

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) g | Generate code files (see above) lint | Verify code matches linting rules start | Run Webpack's dev-server on project test | Execute tests in Chrome test:headless | Execute tests in PhantomJS tagVersion | Creates tag for new version and publishes

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 two following command is provided by default:

npm test

This command calls 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 Chrome & PhantomJS with files being watched & tests automatically re-run headless| Run through PhantomJS with files being watched & tests automatically re-run single | Run through PhantomJS one time with no file watching watch | 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.

Packaging

Packaging is as simple as publishing to NPM by doing

npm run tagVersion

To test your packages output before publishing, you can run

npm pack

Which will generate a compressed file containing your library as it will look when packaged up and published to NPM. The basic structure of a published library is:

|__examples/
   |__example.component.html
   |__example.component.ts
   |__example.main.ts
   |__example.module.ts
   |__index.html
|__src/
   |__<library name>.module.ts
   |__index.ts
|__.npmignore
|__index.ts
|__package.json
|__README.md

As you can see, the packaging removes any files specific to developing your library.