[Feature] Create boilerplate for library

[ritz078]

This is a feature request.

It will be great if we can create a basic boilerplate for creating libraries for pipes, components etc. This is the time when people may be willing to create components for angular 2 but due to the lack of this, it's tough. angular-cli already has a build system in place so it will be easier to integrate it here.

For example, If making a pipe, I won't need the whole src folder. A single file and a page where I can see the preview will do. This will make it easier for a lot of people.

[filipesilva]

We have this feature on the backlog, but it's probably only going to happen post v1 release.

[DxCx]

Hi,

I've found a Yeoman biolerplate that might be used until this one is resolved: https://github.com/jvandemo/generator-angular2-library (Haven't tested it yet, but will, soon..)

Hope it will help, and take down the pressure from ng2-cli team ;)

[jaumard]

Can't wait to use this in angular-cli :) @DxCx did you test this generator finally ? Because doesn't seems up to date with last angular version :/

[DxCx]

@jaumard I tested it long time ago, yes i agree it's totally not up to date :\

[jaumard]

Is there any resources about this for angular 2.0 ? I found for beta, alpha but nothing for the stable release...

[DxCx]

i think now that the final is out, they might want to implement this soon.. @Brocco is there any near plans about this feature?

[tomwanzek]

Would love to see this feature rather sooner than later. I understand that the wonderful heroes 👍 behind the cli have to manage their scope, but I am crossing my finger that it does not take too long.

It is becoming somewhat of a bottleneck w.r.t. reusability of developed code. An ETA, even it broad strokes, would be most appreciated.

[Brocco]

@DxCx This is on the roadmap, but not in the immediate future.

[vinaysoni]

It is sad to see that such an important feature is not being taken up as a priority. Angular2 is all about components but cli doesn't allow for making lib out of components, so that these can be reused across projects. Strange.

[Brocco]

@vinaysoni I understand that this may be higher on your priority list, but there are more pressing issues for the team to focus on, such as build and test performance. Rest assured that this is something that will be supported by the CLI.

[vinaysoni]

Hi @Brocco

Thanks for your reassurance on this. However, let me explain my perception of the situation and why I thought that this feature (support for library development) is a vital part that should not have been missing in angular-cli .

Let me begin by saying that my comment was not motivated because of my immediate personal need for building libraries.

I tend to think of cli as a tool similar to Maven Archetypes. A tool which can provide me scaffold of different kinds/pieces of applications - so that one can get started quickly - without having to do plumbing and with the best blueprints/practices. angular-cli, along the same lines, generates project, modules, components, pipes, enums etc.

In the Java world, we have had Maven Archetypes, to generate different kind of projects (java command line app, a Jar file, a J2EE app, a web app, a Spring Camel App - and the list is virtually endless). But the most important part of Maven Archetypes - which is the closest parallel to angular-cli is generation of libraries.

We live in the world of libraries. Maven generated Java jar, war, ear, zip files to NPM packages. In an enterprise environment, everything is broken down into libraries. Now, when I think about - did anyone spend time in performance testing the Archetype for J2EE app or it's Unit tests, the answer is No. I feel that it is a minute piece in a much larger effort. If your blueprints are correct, and you are generating the code according to the blueprints, why do you need to do performance tests? angular-cli is not a full blown code generation tool. It generates only a starting point in code - with the right plumbing/blueprints/best practices.

On the other hand, what angular-cli should have had from the day one, was the ability to generate a Library. Even before "ng new project" came into place, there should have been "ng new lib datepicker"

This is because, there won't be a single Angular 2 project, worth the salt, within the enterprise, in real world, that would be composed of one single monolithic application. Only amatures, or Angular2 students, or a small time web developer would build such a monolithic application (without breaking it down into components). They may do it as a proof of concept, and therefore could be the use case for "ng new project" and the rest of what angular-cli has to offer today.

For corroboration, you may look at Angular2 itself. It acknowledges the assertion I am making by providing modules and components. The idea, the spirit and the very purpose of Modules was that when a module is created, it should be packaged in its own library. This is what we have done for years in the java eco system on the Swing based UIs for many years. But where is the support to do this in angular-cli?

Also, Modules were introduced late. Angular-cli should have been nimble to include "Support for Libraries" as soon as Modules surfaced. The current variance between angular-2 and angular-cli doesn't reflect nicely on angular-cli. Without support for libraries, I can't see enterprise applications adopting angular-cli.

"Support for Libraries" would be the most important Use Case for angular-cli within an enterprise software development environment. This may be a bit hard for traditional Java Script developer to grasp. But with a first class Object Oriented programming language (Typescript) it won't be JS developers but C# and Java developers who would be building the next generation of reusable components and apps using Angular2. GUI applications, with Typescript and Ng2 will be larger than the JS apps of the past and will have much greater element of reuse.

In contrast, generating a route, or a component, or Enum are nice to have features but are relatively simpler and pale in front of the need for "Support for Libraries".

Thanks Vinay Soni

[BernhardRode]

Hi,

i'm really appreciating the work on angular cli. i agree to what @vinaysoni wrote.

I want to get involved and make this feature come to life. Does somebody want to join and/or do a brainstorming session?

[piernik]

Here is temprorary workaround

I've managed to publish my project to npm. Here's what I did.

In angular-cli project my module went to single folder (component-warpper). In that folder I've added index.ts with list of modules and components to export. I also added package.json file. Then in command line go to this folder and npm publish. Now I can import it as node_modules in other projects.

[randyaa]

I wholeheartedly agree. We've been using Angular-CLI to manage a component library since alpha 0.0.34 but the webpack upgrade killed it.

The crawl phase of this kind of support really just needs:

• to allow declarations to be emitted (maybe its possible now but with the first webpack release it threw all sorts of weird errors if you turned this on in tsconfig)
• the ability to generate barrels that make the API surface obvious.
• compile the barrels for distribution rather than build a single bundle.

We are still using Angular-CLI to build the demo app within our component library but have resorted to an NPM script like the following to build the library:

del-cli ./dist && tsc --outDir ./dist -p src/app && node-sass --include-path scss src/app -o ./dist && cp ./public/package.json ./dist && cp -R ./src/assets ./dist && cd src/app && find . -name '*.html' -exec cp --parents \\{\\} ../../dist \\; && cd ../.. && npm run inline-resources

which is clunky at best.

Material2 switching back to gulp should be a good indication that this support is needed.

[piernik]

I hope this feature will be implemented very soon because my temprorary solution has issue with code completion in IDE (PhpStorm in my case).

[BenjaminBrandmeier]

Thanks for all the work so far, I'm a huge fan of angular-cli!

This issue is idle for about 2 months now. Any plan on when this will be implemented? For the time being I will also try to come up with something on my own.

[nsmolenskii]

I have a live example, how to use angular cli for creating angular component library (with own dependencies, in that case @angular/material). It does not provides custom templates for code generation, but it's really no so many effort to setup a library (how often is it needed). It also will receive a benefits from angular-cli project:

• Default angular-cli application, that could be used for documentation or sandbox experiments reasons.
• Default test setup from angular-cli support
• Easy migrations for a new version of cli by ng init command.
• I expect no effort to migrate to an official library template, when it will be present.

You could have a look into: app, lib, app-demo.

⚠️ For non angular-cli projects, those do not use typescript, you might need to configure additional typescript loader. For angular-cli project it works out from the box.

[Brocco]

There are some things that will need tackled within the CLI project in order to support libraries (not just applications). The first issue will be to support multiple applications within a project, this will allow for multiple build paths not just a single application. Then in order to support libraries a separate , non-application, build process will need to be implemented as there are additional build concerns when building a library than when building an application.

This is a high priority item for the community and for the team and is most certainly on the roadmap, just not sure of the timeframe at this point. Thanks for your input and patience.

[BenjaminBrandmeier]

Thanks for the heads up Brocco. After building some simple mechanisms for my publishing process on my own I wondered if the angular-cli project would have really helped, because when publishing a library in certain cases you want to be very deterministic on what happens during the preparation and in the end be part of the package. I got a grasp on how much work this would be for the team to implement this in general in a smooth way.

Regarding libraries I assume this is one of the points where every CLI user has to think about the building process on their own if straightforward solutions like @nsmolenskii 's approach (thanks!) can't be used.

[maxkoretskyi]

@nsmolenskii, hey, I've taken a look at your lib example. It seems to me that it's a simple angular module, without any build process on it's own. Is it correct, or am I missing something? We're looking into building a library using angular-cli without including angular sources into the build

[nsmolenskii]

@maximusk yes, you are right. It is based on the distributing sources files(.ts, .html, .scss, etc) instead of compiled into .js + .d.ts. In case if you using any build system, that supports typescript loader (angular-cli as perfect example), this library will be loaded as normal module and will be bundled as part of your application based on your build configuration.

I assume, that as soon as angular-cli will support library mode, to migrate from current approach to a native one, it will require to:

• configure library mode (most probably some properties in angular-cli.json)
• change "main": "lib/index.ts" and "typings": "lib/index.ts" in package.json to new compiled output files.

[maxkoretskyi]

@nsmolenskii, got it, thanks for your reply

[oliverjanik]

I just want to reiterate that this is vitally needed. There is no good way to package an AOT ready library for angular 2 right now. Everything out there is a collosal mess.

Don't let this turn into another router fiasco.

[zpydee]

+1 , x 1,000 if i could :-)

[DxCx]

if someone from angular-cli can have a chat with me explaining what needs to be done i don't mind taking this and opening a PR. :)

[johnpapa]

It is important to remember that this is an OSS project and if a feature we want isn't being worked on as fast as we desire, we can always donate our own time to help create PRs.

:)

[DxCx]

exactly @johnpapa ;) i was creating libraries manually (mostly for myself and testing stuff), but Im not sure i was doing the right approach. that's why if i'm gonna open a PR i want to make sure it's being done properly.

[cgnunezbantics]

Hello @johnpapa, We like to make libraries too, do you have any pattern to show us.

[filipesilva]

Heya, I just wanted to give a small update regarding this feature.

It's not going to be there for 1.0, but it's definitely going to be there for 2.0. So the only question is if it's gonna be there for 1.x - I cannot answer this yet.

It's one of those big features that requires a fair bit of design upfront so it's not something we're looking for people to help out in right now. But it is something we're paying a lot of attention to.

It is true that there isn't a lot of guidance on how to build a library right now. I'm working on a cookbook for angular.io about this topic and hope to have it out soon.

I'm basing the upcoming cookbook heavily on @thelgevold's excellent work on https://github.com/angular/angular.io/pull/2758, which was never merged. It is a good starting point currently, if you want to have a look.

[BernhardRode]

Thank you so much @filipesilva

[Toilal]

Does it make sense to try using this typerscript boilerplate : https://github.com/alexjoverm/typescript-library-starter ?

[oliverjanik]

That is nice, but the main problem from my experience is the AOT + Webpack bit.

[nmorado]

Do we have any timeline on when to expect 2.0?

[danwulff]

Hey @filipesilva I am just starting to look at creating a component library for some upcoming Angular apps and was wondering how the cookbook might be coming along? If I told you that I could hold off on starting a component library for a week or two, would you be gracious enough to give me a recommendation whether to try tackling this now or later? I'm also somewhat new to the Angular (2+) world, if that knowledge is of much worth.

I also saw that you've been active recently in this: https://github.com/filipesilva/angular-quickstart-lib Is this usable atm? Or would you recommend first looking at thelgevolds work before that? angular/angular.io#2758 Let me know if I can help guinea pig anything related to library development.

[playground]

100% agree with @vinaysoni expressing the need of being able to create reusable/distributable libs with ng cli. @danwulff @filipesilva I'm also looking to start a project soon within a couple of weeks that will require the ability to create such shareable/distributable libs. Any recommendation between now and then will be appreciated. I'm vigorously search for solutions and alternatives, but I hope ng cli will be able to provide that.

[dherges]

From my experience, you need to set up a bunch of tools on your own.

• Getting your Angular 2 library ready for AoT
• Distributing an Angular Library - The Brief Guide

tl;dr:

• ngc to ES5 target, generating *.js + *.d.ts + *.metadata.json, exclude *.ngfactory.ts from distributable package, optionally: include *.js.map in distributable package
• inline templates and styles, compile pre-css languages to css, see angular/angular#15722
• create am UMD bundle referenced in "main" property of package.json
• create an ESM version (in ES2015 module format) referenced in "module" property of package.json
• (possibly more...)

[pedroapy]

We have made a library of components with gulp and webpack. The important part as mentioned @dherges is to generate the .d.ts and .metadata.json.

If it helps someone, this is our library: https://github.com/stratio/egeo , the important part are the files:

• gulpfile.js
• tsconfig.gulp.json
• config/webpack-components.js
• tsconfig.lib.json

So far this is working for us. We are waiting for a "official/angular-cli" way to do a library.

[ddramone]

I suggest to check repo of material2 and spend some time how it's done

They're using gulp and systemjs for dev sanbox app, but you can use final library whenever you want. It also provides UMD bundle.

So, just a tip: spend some time and if you will reformat/reorganize everything depended your needs, you will come up with the most flexible solution

[playground]

@Brocco you mentioned above there will be to support for multiple applications within a project. Is this available yet?

[danwulff]

Thanks folks for the recommendations, I appreciate it a lot. I'm putting this off for a few weeks but I'll let you know how it goes when I get around to it.

[ritz078]

Till this feature is implemented here you guys can use https://github.com/jvandemo/generator-angular2-library. It seems it is in active development.

All thanks to @jvandemo

[jvandemo]

@ritz078 — Thank you, much appreciated. It will be great for the ecosystem if Angular CLI offers the ability to generate a library at some point. 👍

[Brocco]

@playground yes, multiple apps are currently supported by the CLI. There is a story that will be added to the wiki: #5737

[cankayacan]

That library starter from me might also work: https://github.com/cankayacan/ngx-library-starter

[achieverprince]

You can create a npm library from existing @angular/cli project itself.

Create a new project with ng new -projectname edit "package.json" Add "typings": "./index.d.ts" (change to any name you want)

in "index.d.ts" file export all the classes/interfaces you need to expose, you can even included a new ts file here which has a export (like a nested export)

in my case i used

export * from "./src/app/model";
export * from "./src/app/service";

model and service folders will have index.d.ts which exports the underlying classes/interfaces.

now login to npm from root folder

npm login

and publish the module

npm publish

How to use the published module in angular project

Just add a dependency and devDependencies in your project

"module-project": "^1.0.13"

[nsmolenskii]

@achieverprince, you are right, but this approach could not be an official one, caus it has some limitations. For example:

• it could not be used directly from es projects without extra typescript loader, because it based on typescript code distribution
• It contains files as index.htm, main.ts, etc. Those are redundant for library, but could be used as sandbox/live-demo purpose.
• test files are visible in library and it is wired.
• internal classes are visible too and it even more wired.

Even that, we using this approach inside of our team for half year already. It just works and compatible with aot-compilation out of the box (within another angular-cli project).

I just put link to example repository here.

[achieverprince]

@nsmolenskii , you are right. I am stuck in final stage with this error compiler.es5.js:1540 Uncaught Error: Encountered undefined provider! Usually this means you have a circular dependencies (might be caused by using 'barrel' index.ts files.

May be i will try your approach which is neater. But i also have few classes that has to be exposed and can be imported in main project.

[nsmolenskii]

Usually, such errors are happens when you doing some imports like:

import {something}from './';
import {something}from '../';

try to get rid of such imports and use at least one path segment explicit.

[achieverprince]

@nsmolenskii

It was not related to that. Changes i made make it work

i was using "module" property in package.json and referencing it to exported js file (This will not work as the exported js files will not have all the modules)

i removed "module" and not exporting any js file now using "main" property as your library project which points to same typing ts file "main": "src/index.ts"

1 more change i had to make is rename all index.d.ts > index.ts , which solved the issue. And i was using dependency as npm module itself (i need to publish to npm every time to get a new version), and my project is private code so now changed to local svn repository.

But i am not able to directly download the code from svn //DOESN'T WORK

"dependencies": {
"yl-angular": "http://****/svn/maven2/repo/trunk/yl-angular/yl-angular/"
}

//WORK - Local

"dependencies": {
"yl-angular": "D://JAVA_DEVELOPMENT//G2_NEW//yl-angular//yl-angular"
}

Do you have any idea to use svn repo for depencency?

[filipesilva]

@achieverprince @nsmolenskii I strongly discourage that way of publishing a library, it's not at all compliant with the Angular Package Format.

Meanwhile you can read a tentative guide to third party libraries in https://github.com/angular/angular/pull/16486, and a seed for it in https://github.com/filipesilva/angular-quickstart-lib.