trekhleb / angular-library-seed

🌾 Seed project for Angular libraries that are AOT/JIT compatible and that use external SCSS-styles and HTML-templates

angular-library-seed - the starter for Angular libraries

Seed project for Angular libraries that are AOT/JIT compatible and that use external SCSS-styles and HTML-templates.

This project contains TickTock library example. The library itself is small and the only thing it does is displaying current time (Plunker example). But what most important is that the project contains reusable environment for the libraries that allows to build, test, lint, document, explore and publish them.

Read more about architectural challenges and solutions used in this repository.

You might find this project helpful if

• You want to create library for Angular 4.
• You want your library to be ready for further AOT or JIT compilation.
• You want your library to be ready for further usage directly in browsers (let's say UMD bundle loaded by SystemJS).
• You want to write component styles in external SCSS files.
• You want to write component templates in external HTML files.
• You want to have watch-mode for library builds (including AOT build).

Main Features

• AOT/JIT compatible library build via Angular Compiler (ngc).
• UMD build via Webpack that allows you to use your library for browser builds. You may play with it on Plunker.
• Testing with Karma and Jasmine.
• Test coverage report via Istanbul.
• Watch modes for building and testing procedures that makes developing process easier.
• Linting with TSLint and Codelyzer for static code analysis.
• Exploring your build via Sourcemap Explorer that shows you a treemap visualization to help you debug where all the code is coming from.
• Documentation generation via Compodoc. Take a look at documentation example.
• Documentation hosting via GitHub Pages.
• AOT/JIT/UMD demos via Webpack and SystemJS that allows you to test library builds.
• Continuous integration with Travis CI.
• Code coverage badge via Codecov as a reminder to cover code with tests.

Quick Start

# Clone the repository
git clone https://github.com/trekhleb/angular-library-seed.git

# Go to repository folder
cd angular-library-seed

# Install all dependencies
yarn install

# Build the library
yarn build

File Structure

angular-library-seed
  ├─ demo                         * Folder for demo applications (MAY BE DELETED if not required) 
  |  ├─ esm                       * AOT/JIT demo project
  |  ├─ umd                       * UMD demo project
  |  └─ ...                       * More details about this folder may be found in demo folder README file.
  |
  ├─ src                          * Library sources home folder (THE PLACE FOR YOUR LIBRARY SOURCES)
  |  ├─ components                * Example of library components with tests
  |  ├─ services                  * Example of library services with tests
  |  ├─ index.ts                  * Library entry point that is used by builders
  |  └─ tick-tock.module.ts       * Example of library module
  |
  ├─ .editorconfig                * Common IDE configuration
  ├─ .gitignore	                  * List of files that are ignored while publishing to git repo
  ├─ .npmignore                   * List of files that are ignored while publishing to npm
  ├─ .travis.yml                  * Travic CI configuration
  ├─ LICENSE                      * License details
  ├─ README.md                    * README for you library
  ├─ gulpfile.js                  * Gulp helper scripts
  ├─ karma-test-entry.ts          * Entry script for Karma tests
  ├─ karma.conf.ts                * Karma configuration for our unit tests
  ├─ package.json                 * NPM dependencies, scripts and package configuration
  ├─ tsconfig-aot.json            * TypeScript configuration for AOT build
  ├─ tsconfig.json                * TypeScript configuration for UMD and Test builds
  ├─ tslint.json                  * TypeScript linting configuration
  ├─ webpack-test.config.ts       * Webpack configuration for building test version of the library
  ├─ webpack-umd.config.ts        * Webpack configuration for building UMD bundle
  └─ yarn.lock                    * Yarn lock file that locks dependency versions

Getting Started

Dependencies

Node/NPM

Install latest Node and NPM following the instructions. Make sure you have Node version ≥ 7.0 and NPM ≥ 4.

• brew install node for Mac.

Yarn

Yarn package manager is optional but highly recommended. If you prefer to work with npm directly you may ignore this step.

Yarn installs library dependencies faster and also locks theirs versions. It has more advantages but these two are already pretty attractive.

Install Yarn by following the instructions.

• brew install yarn for Mac.

Installing

• fork this repository.
• clone your fork to your local environment.
• yarn install to install required dependencies (or npm i).

Replace TickTock library with your own library

This step may be optional at first since you might just want to play with existing library example.

Once you're ready to develop your own library you should do the following.

• Check and re-configure package.json fields like name, version, keywords, description etc. You may read about specifics of npm's package.json handling to do that.
• Replace the content of src folder with your library sources. Your library must have index.ts file as an entry point for further building.
• Update demo sources to make them consume your library in case if you want to keep the demo folder.

Build the library

• yarn build for building the library once (both ESM and AOT versions).
• yarn build:watch for building the library (both ESM and AOT versions) and watch for file changes.

You may also build UMD bundle and ESM files separately:

• yarn build:esm - for building AOT/JIT compatible versions of files.
• yarn build:esm:watch - the same as previous command but in watch-mode.
• yarn build:umd - for building UMD bundle only.
• yarn build:umd:watch - the same as previous command but in watch-mode.

Other commands

Lint the code

• yarn lint for performing static code analysis.

Test the library

• yarn test for running all your *.spec.ts tests once. Generated code coverage report may be found in coverage folder.
• yarn test:watch for running all you *.spec.ts and watch for file changes.

Generate documentation

• yarn docs for generating documentation locally.
• yarn gh-pages for generating documentation and uploading it to GitHub Pages. Documentation example.

Explore the bundle

• yarn explorer to find out where all your code in bundle is coming from.

Bump library version

• npm version patch to increase library version. More on bumping.

preversion script in this case will automatically run project testing and linting in prior in order to check that the library is ready for publishing.

Publish library to NPM

• npm publish to publish your library sources on npmjs.com. Once the library is published it will be available for usage in npm packages.

prepublishOnly script in this case will automatically run project testing and linting in prior in order to check that the library is ready for publishing.

Cleaning

• yarn clean:tmp command will clean up all temporary files like docs, dist, coverage etc.
• yarn clean:all command will clean up all temporary files along with node_modules folder.

Library development workflow

In order to debug your library in browser you need to have Angular project that will consume your library, build the application and display it. For your convenience all of that should happen automatically in background so once you change library source code you should instantly see the changes in browser.

There are several ways to go here:

• Use your real library-consumer project and link your library to it via yarn link command (see below).
• Use demo applications that are provided for your convenience as a part of this repository.
• Use Angular-CLI to generate library-consumer project for you and then use yarn link to link your library to it.

Using demo applications

You may take advantage of watch-modes for both library build and demo-projects builds in order to see changes to your library's source code immediately in your browser.

To do so you need to:

1. Open two console instances.
2. Launch library build in watch mode in first console instance by running yarn build:watch (assuming that you're in angular-library-seed root folder).
3. Launch demo project build (JIT version) in watch-mode by running yarn start in second console instance (assuming that you're in angular-library-seed/demo folder).

As a result once you change library source code it will be automatically re-compiled and in turn your JIT demo-project will be automatically re-built and you will be able to see that changes in your browser instantly.

For more details about demo projects, their folder structure and npm commands please take a look at demo projects README.

Using yarn link

In you library root folder:

# Create symbolic link
yarn link

# Build library in watch mode
yarn build:watch

In you project folder that should consume the library:

# Link you library to the project
yarn link "angular-library-seed"

# Build your project. In case of Angular-CLI use the following command.
ng serve --aot

Then you need to import your library into your project's source code.

Now, once you update your library source code it will automatically be re-compiled and your project will be re-built so you may see library changes instantly.

More information about yarn link command.

At the moment of publishing this project there is a bug exists when using yarn link in combination with Angular CLI. The issue is caused by having node_modules folder inside linked library. There is a workaround has been provided that suggests to add a paths property with all Angular dependencies to the tsconfig.json file of the Angular CLI project like it is shown below:

{
  "compilerOptions": {
    "paths": { "@angular/*": ["../node_modules/@angular/*"] }
  }
}

angular-library-seed's Issues

yarn build execute with error

Hello! I fork and clone repo to my machine do yarn install then yarn build.
After yarn build i get error

`
yarn run v1.2.1
$ rimraf dist tmp
$ npm run build:esm && npm run build:umd

[email protected] build:esm /home/anonymous/Projects/ngx-flipclock
gulp inline-templates && npm run ngcompile

Bus error (core dumped)
npm ERR! code ELIFECYCLE
npm ERR! errno 135
npm ERR! [email protected] build:esm: 'gulp inline-templates && npm run ngcompile'
npm ERR! Exit status 135
npm ERR!
npm ERR! Failed at the [email protected] build:esm script.
npm ERR! This is probably not a problem with npm. There is likely additional logging output above.

npm ERR! A complete log of this run can be found in:
npm ERR! /home/anonymous/.npm/_logs/2017-10-25T18_03_18_680Z-debug.log
error Command failed with exit code 135.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.

`
in log file

0 info it worked if it ends with ok
1 verbose cli [ '/usr/bin/node',
1 verbose cli '/home/anonymous/.npm-global/bin/npm',
1 verbose cli 'run',
1 verbose cli 'build:esm' ]
2 info using [email protected]
3 info using [email protected]
4 verbose run-script [ 'prebuild:esm', 'build:esm', 'postbuild:esm' ]
5 info lifecycle [email protected]prebuild:esm: [email protected]
6 info lifecycle [email protected]build:esm: [email protected]
7 verbose lifecycle [email protected]build:esm: unsafe-perm in lifecycle true
8 verbose lifecycle [email protected]build:esm: PATH: /home/anonymous/.npm-global/lib/node_modules/npm/bin/node-gyp-bin:/home/anonymous/Projects/ngx-flipclock/node_modules/.bin:/home/anonymous/Projects/ngx-flipclock/node_modules/.bin:/home/anonymous/.config/yarn/link/node_modules/.bin:/home/anonymous/Projects/ngx-flipclock/node_modules/.bin:/home/anonymous/.config/yarn/link/node_modules/.bin:/usr/lib/node_modules/npm/bin/node-gyp-bin:/usr/bin/node_modules/npm/bin/node-gyp-bin:/home/anonymous/Programms/WebStorm-172.3757.55/bin:/home/anonymous/Programms/PhpStorm-172.3317.83/bin:/home/anonymous/.composer/vendor/bin:/opt/lampp:/opt/lampp/bin:/home/anonymous/.npm-global/bin:/home/anonymous/bin:/home/anonymous/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/snap/bin
9 verbose lifecycle [email protected]build:esm: CWD: /home/anonymous/Projects/ngx-flipclock
10 silly lifecycle [email protected]build:esm: Args: [ '-c', 'gulp inline-templates && npm run ngcompile' ]
11 silly lifecycle [email protected]build:esm: Returned: code: 135 signal: null
12 info lifecycle [email protected]build:esm: Failed to exec build:esm script
13 verbose stack Error: [email protected] build:esm: 'gulp inline-templates && npm run ngcompile'
13 verbose stack Exit status 135
13 verbose stack at EventEmitter. (/home/anonymous/.npm-global/lib/node_modules/npm/node_modules/npm-lifecycle/index.js:280:16)
13 verbose stack at emitTwo (events.js:106:13)
13 verbose stack at EventEmitter.emit (events.js:191:7)
13 verbose stack at ChildProcess. (/home/anonymous/.npm-global/lib/node_modules/npm/node_modules/npm-lifecycle/lib/spawn.js:55:14)
13 verbose stack at emitTwo (events.js:106:13)
13 verbose stack at ChildProcess.emit (events.js:191:7)
13 verbose stack at maybeClose (internal/child_process.js:920:16)
13 verbose stack at Process.ChildProcess._handle.onexit (internal/child_process.js:230:5)
14 verbose pkgid [email protected]
15 verbose cwd /home/anonymous/Projects/ngx-flipclock
16 verbose Linux 4.10.0-37-generic
17 verbose argv "/usr/bin/node" "/home/anonymous/.npm-global/bin/npm" "run" "build:esm"
18 verbose node v6.11.5
19 verbose npm v5.5.1
20 error code ELIFECYCLE
21 error errno 135
22 error [email protected] build:esm: 'gulp inline-templates && npm run ngcompile'
22 error Exit status 135
23 error Failed at the [email protected] build:esm script.
23 error This is probably not a problem with npm. There is likely additional logging output above.
24 verbose exit [ 135, true ]

Please help resolve my problem

error: unknown option `--disablePrivateOrInternalSupport'

As of compodoc/compodoc@9e4222e

option disablePrivateOrInternalSupport where splitted in
provide flags : --disablePrivate , --disableProtected, --disableInternal, --disableLifeCycleHooks

Cannot use the seed for two plugins

I used the seed to create 2 plugins. But for some reasons they cannot be together in the same project. If I install the first one, NPM deletes the other and visa versa.

Coverage report folder isn't being created on Windows 10 after running tests

How can I include assets like images in library, and use them for img src ?

How can I include assets like images in library, and use them for img src ?

Webpack only watching the first time

Hi,

First i would like to THANK YOU for this project because all the other I founded are old, obsolete, not-working ...

I have a problem when I use a link (with npm link) of my library app in my consumer app (angular cli basic app). The first time I make a change in the library, which is builded in watch mode, my consumer app is automatically recompiled.

But when i make a new change in library, my consumer app is no more recompiling again ? Why ???

As suggested in your tuto: i have to consoles:

. one for the library app running with npm run build:watch

. one for the consumer app running with ng serve --aot

Unexpected value 'TickTockModule' imported by the module 'Feature1RoutingModule'. Please add a @NgModule annotation

Description

I'm facing this error when trying to import TickTockModule in a Angular CLI project, via a lazy-loaded module:

Unexpected value 'TickTockModule' imported by the module 'Feature1RoutingModule'. Please add a @NgModule annotation (happens when I navigate the lazy route)

Feature1RoutingModule was created via CLI and is defined as follows:

import { NgModule } from '@angular/core';
import { Routes, RouterModule } from '@angular/router';

import { TickTockComponent, TickTockModule } from "@unsafecode/feature1";

const routes: Routes = [
  {
    path: '',
    component: TickTockComponent
  }
];

@NgModule({
  imports: [RouterModule.forChild(routes), TickTockModule],
  exports: [RouterModule]
})
export class Feature1RoutingModule { }

Where @unsafecode/feature1 is the library package, cloned from this repo and linked with npm link (no changes).

I also checked the Angular CLI project tsconfig.json has the paths: {...} options configured as described.

Configuration

[email protected]
[email protected]
@angular/[email protected]

Demo project's failing after upgrading all `@angular/*` packages to `^5.0.3`

After upgrade of all @angular related packages to v5.0.3, demo project started to throw following error into dev tools console:
Uncaught Error: Unexpected value '[object Object]' imported by the module 'AppModule'. Please add a @NgModule annotation.

[object Object] is basically return of .forRoot() method, of library's root module, AppModule is a demo app root module.

Any ideas on how to deal with this?

When publishing library with Yarn it ignores 'dist' folder

When yarn publish is run it ignores dist folder and publishes package to npmjs.org without it. This happens because yarn take .gitignore file into consideration even if .npmignore file exists.

Expected behavior
When publishing with yarn publish command the dist folder must be published as well.

Current workaround
Use npm version and npm publish instead.

Can't Find Source Maps

I've cloned the repo and proceeded to include it in an angular-cli new project. However when I run the app I can't find any sourceMaps. I look in the dist folder and I don't see them listed anywhere.

What am I missing?

Procedure:
git clone
yarn install
yarn build
check dist and no source maps.

Q: UMD Bundle

I'm having trouble figuring out why in your UMD config, you set tsconfig.json's module prop to commonjs instead of umd.

In my case, setting it to umd breaks the build, yet commonjs works. Why is this happening?

The only other place I can see a reference to UMD in this setup is in the webpack.umd.config.js file, in the libraryTarget: 'umd' part.

What's going on? In my case at least, this is the only setting combination that "works" but what's going on? Why commonjs in tsconfig.json? Why umd in webpack's libraryTaget? I thought I got everything before but I kinda lost it on this.

Thank You!

You have the only decent angular library seed project that exists. All others are lacking, broken, outdated, or over-complicated in some way. I hope you keep up with this project because the world needs it.

Question: How to make library with multiple entry points?

I am using your seed for a library I am building that is going to be kind of large. I am trying to set up my library source so that I can have multiple entry points like...

@mylib/security
@mylib/logging
@mylib/ui
...

This way consumers of the lib will be able to import modules and components from the appropriate location in the library.

ionic library

I have added ionicModules in packages but it is not compiling ionic related packages. I always get template parse error that ion-label not found. So how to include those 3rd parties libraries here.

Double menu items at documentation

At the result of compodoc, some menu items are repeating.

Suggestion: add support to @angular/cli

It maybe helpful to change the project into angular-cli project.

It may add complexity here but it can be ejected if not applicable.

Custom paths not working

When setting custom paths they don't seem to work, I think it's because of AOT but I'm not sure. It breaks both when I build the project and when I test it. I use the same paths in my CLI project and it works fine so I guess there's some config missing in this project but I haven't been able to figure out what.

I use this tsconfig:

{
  "compilerOptions": {
    "baseUrl": ".",
    "target": "es5",
    "module": "commonjs",
    "moduleResolution": "node",
    "noEmit": true,
    "sourceMap": true,
    "declaration": false,
    "noImplicitAny": false,
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "lib": [
      "es2015",
      "dom"
    ],
    "typeRoots" : [
      "./node_modules/@types"
    ],
    "types": [
      "jasmine",
      "karma",
      "node",
      "webpack",
      "webpack-env"
    ],
    "paths": {
      "@shared/*": ["src/*"],
      "@components/*": ["src/components/*"],
      "@directives/*": ["src/directives/*"],
      "@modules/*": ["src/modules/*"],
      "@pipes/*": ["src/pipes/*"],
      "@validators/*": ["src/validators/*"]
    }
  },
  "include": [
    "src/**/*.ts"
  ],
  "exclude": [
    "src/**/*.spec.ts",
    "node_modules",
    "demo",
    "dist"
  ]
}