An Angular 2+ scaffolding setup. Generates AOT-compliant code using similar paradigms to the Angular CLI.
The library is available as angular-librarian on NPM.
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.
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 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 |
Sets up the project. Can also be run to update a project to the latest angular-librarian configuration.
ngl i
ngl init
ngl initialize
npm run g i
npm run g init
npm run g initialize
Library name:
a dash-cased name that is used in constructing thepackage.json
and*.module.ts
file. It is also used to create the class name of the module.README Title:
the string to insert in theREADME.md
fileRepository URL:
the repository where the code will be heldReinitialize Git project (y/N)?
: if left blank, defaults to no. If yes or y are entered, it will reinitialize a git project.
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 shownexamples/example.component.html
: the example application's root component templateexamples/example.component.ts
: the example application's root componentexamples/example.main.ts
: the example application's main fileexamples/example.module.ts
: the example application moduleexamples/index.html
: the example application's main HTML filenode_modules/
: where the dependencies installed via NPM are storedsrc/
: where the bulk of application & test code is.src/<library name>.module.ts
: the main module of the librarysrc/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 fileswebpack/webpack.dev.js
: this file is used when running the webpack-dev-serverwebpack/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 NPMindex.ts
: another barrel filekarma.conf.js
: the testing setup for the projectpackage.json
: holds the list of dependencides for the project, scripts, and other metadata about the libraryREADME.md
: a markdown file best used for providing users with an overview of the librarytest.ts
: contains code needed to get the Angular test environment bootstrappedtsconfig.json
: the TypeScript configuration for the projecttslint.json
: the linting rules for the projectvendor.ts
: contains a list of dependencies that Angular needs loaded before the application is loaded
Generates a component
ngl c
ngl component <selector>
npm run g c
npm run g component <selector>
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 providesn
,no
, or a blank, the component is set up with non-inline styles. If the user providesy
oryes
, the component is set up with inline styles.Use inline template (y/N)?
: if the user providesn
,no
, or a blank, the component is set up with a non-inline template. If the user providesy
oryes
, 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
, andoninit
.
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
Generates a directive
ngl d
ngl directive <directive-name>
npm run g d
npm run g directive <directive-name>
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.
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
Generates a service
ngl s
ngl service <service-name>
npm run g s
npm run g service <service-name>
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.
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
Generates a pipe
ngl p
ngl p <pipe-name>
npm run g p
npm run g p <pipe-name>
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.
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
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 |
Build the library's code. This will run the code through
the ngc
compiler and compile the code for distribution.
ngl build
ngl b
npm run build
Lint code through TSLint
ngl lint
ngl l
npm run lint
Create a tag and publish the library code using the
np
library. Note that the version
argument utilizes the version
arguments of the np
library.
ngl publish <version>
ngl p <version>
npm run tagVersion <version>
Start the webpack dev server and run the library code through it.
ngl serve
ngl v
npm start
We use start
for direct npm
commands to keep the command as
concise as possible.
Run unit tests on code. For unit test types, see the unit testing section below.
ngl test <type>
ngl t <type>
npm test <type>
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:
ngl test
ngl t
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.
To test your packages output before publishing, you can run the specified publish commands above.
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:
|__dist/
|__index.d.ts
|__index.js
|__index.js.map
|__index.metadata.json
|__<library name>.bundle.js
|__<library name>.bundle.js.map
|__<library name>.module.d.ts
|__<library name>.module.js
|__<library name>.module.js.map
|__<library name>.module.metadata.json
|__examples/
|__example.component.html
|__example.component.ts
|__example.main.ts
|__example.module.ts
|__index.html
|__package.json
|__README.md
As you can see, the packaging removes any files specific to developing your library. It, more importantly, creates distribution files for usage with many different module systems.