npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

ha-confirmation

v0.0.3

Published

[![Build Status](https://travis-ci.org/robisim74/angular-library-starter.svg?branch=master)](https://travis-ci.org/robisim74/angular-library-starter) >Build an Angular library compatible with AoT compilation & Tree shaking like an official package.

Downloads

1

Readme

angular-library-starter

Build Status

Build an Angular library compatible with AoT compilation & Tree shaking like an official package.

This starter allows you to create a library for Angular v5 apps written in TypeScript, ES6 or ES5. The project is based on the official Angular packages.

Get the Changelog.

Contents

1 Project structure

  • Library:
    • src folder for the classes
    • public_api.ts entry point for all public APIs of the package
    • package.json npm options
    • rollup.config.js Rollup configuration for building the umd bundles
    • rollup.es.config.js Rollup configuration for building the es2015 bundles
    • tsconfig-build.json ngc compiler options for AoT compilation
    • build.js building process using ShellJS
  • Testing:
    • tests folder for unit & integration tests
    • karma.conf.js Karma configuration that uses webpack to build the tests
    • spec.bundle.js defines the files used by webpack
  • Extra:
    • tslint.json Angular TSLint Preset (TypeScript linter rules with Codelyzer)
    • travis.yml Travis CI configuration

2 Customizing

  1. Update Node & npm.

  2. Rename angular-library-starter and angularLibraryStarter everywhere to my-library and myLibrary.

  3. Customize the license-banner.txt file with your library license.

  4. Update in package.json file:

    • version: Semantic Versioning
    • description
    • urls
    • packages (optional): make sure you use a version of TypeScript compatible with Angular Compiler (@angular/[email protected] requires a peer of typescript@>=2.4.2 <2.5)

    and run npm install.

  5. Create your classes in src folder, and export public classes in my-library.ts: if you have components, note that this starter supports only inline templates & styles as the official Angular building process.

  6. You can create only one module for the whole library: I suggest you create different modules for different functions, so that the host app can only import the modules it uses, and optimize its Tree shaking.

  7. Update in rollup.config.js file globals external dependencies with those that actually you use to build the umd bundle.

  8. Create unit & integration tests in tests folder, or unit tests next to the things they test in src folder, always using .spec.ts extension: note that Karma is configured to use webpack only for *.ts files.

3 Testing

The following command runs unit & integration tests that are in the tests folder (you can change the folder in spec.bundle.js file):

npm test 

It also reports coverage using Istanbul.

4 Building

The following command:

npm run build
  • starts TSLint with Codelyzer using Angular TSLint Preset
  • starts AoT compilation using ngc compiler
  • creates dist folder with all the files of distribution, following Angular Package Format (APF) v5.0:
└── dist
    ├── bundles
    |   ├── my-library.umd.js
    |   ├── my-library.umd.js.map
    |   ├── my-library.umd.min.js
    |   └── my-library.umd.min.js.map
    ├── esm5
    |   ├── my-library.js
    |   └── my-library.js.map
    ├── esm2015
    |   ├── my-library.js
    |   └── my-library.js.map
    ├── src
    |   └── **/*.d.ts
    ├── my-library.d.ts
    ├── my-library.metadata.json
    ├── LICENSE
    ├── package.json
    ├── public_api.d.ts
    └── README

To test locally the npm package before publishing:

npm run pack:lib

Then you can install it in an app to test it:

npm install [path]my-library-[version].tgz

5 Publishing

Before publishing the first time:

npm run publish:lib

6 Documentation

To generate the documentation, this starter uses compodoc:

npm run compodoc
npm run compodoc:serve 

7 Using the library

Installing

npm install my-library --save 

Loading

Using SystemJS configuration

System.config({
    map: {
        'my-library': 'node_modules/my-library/bundles/my-library.umd.js'
    }
});

Angular-CLI

No need to set up anything, just import it in your code.

Rollup or webpack

No need to set up anything, just import it in your code.

Plain JavaScript

Include the umd bundle in your index.html:

<script src="node_modules/my-library/bundles/my-library.umd.js"></script>

and use global ng.myLibrary namespace.

AoT compilation

The library is compatible with AoT compilation.

8 What it is important to know

  1. package.json

    • "main": "./bundles/angular-library-starter.umd.js" legacy module format
    • "module": "./esm5/angular-library-starter.js" flat ES module, for using module bundlers such as Rollup or webpack: package module
    • "es2015": "./esm2015/angular-library-starter.js" ES2015 flat ESM format, experimental ES2015 build
    • "peerDependencies" the packages and their versions required by the library when it will be installed
  2. tsconfig.json file used by TypeScript compiler

    • Compiler options:
      • "strict": true enables TypeScript strict master option
  3. tsconfig-build.json file used by ngc compiler

    • Compiler options:

      • "declaration": true to emit TypeScript declaration files
      • "module": "es2015" & "target": "es2015" are used by Rollup to create the ES2015 bundle
    • Angular Compiler Options:

      • "skipTemplateCodegen": true, skips generating AoT files
      • "annotateForClosureCompiler": true for compatibility with Google Closure compiler
      • "strictMetadataEmit": true without emitting metadata files, the library will not be compatible with AoT compilation: it is intended to report syntax errors immediately rather than produce a .metadata.json file with errors
  4. rollup.config.js file used by Rollup

    • format: 'umd' the Universal Module Definition pattern is used by Angular for its bundles
    • moduleName: 'ng.angularLibraryStarter' defines the global namespace used by JavaScript apps
    • external & globals declare the external packages
  5. Server Side Rendering

    If you want the library will be compatible with Server Side Rendering:

    • window, document, navigator and other browser types do not exist on the server
    • don't manipulate the nativeElement directly

9 Inlining of templates and stylesheets

From Angular Package Format v5.0:

Component libraries are typically implemented using stylesheets and html templates stored in separate files. While it's not required, we suggest that component authors inline the templates and stylesheets into their FESM files as well as *.metadata.json files by replacing the stylesheetUrls and templateUrl with stylesheets and template metadata properties respectively. This simplifies consumption of the components by application developers.

ngc compiler still does not support inlining of templates & styles. But if you want, you can follow this suggestion: Inlining of templates and stylesheets.

Built with this starter

Previous versions

License

MIT