[Feature] Create boilerplate for library
ritz078 opened this issue · 73 comments
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.
We have this feature on the backlog, but it's probably only going to happen post v1 release.
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 ;)
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 :/
Is there any resources about this for angular 2.0 ? I found for beta, alpha but nothing for the stable release...
i think now that the final is out, they might want to implement this soon..
@Brocco is there any near plans about this feature?
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.
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.
@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.
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
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?
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.
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.
I hope this feature will be implemented very soon because my temprorary solution has issue with code completion in IDE (PhpStorm in my case).
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.
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-cliapplication, that could be used for documentation or sandbox experiments reasons. - Default test setup from
angular-clisupport - Easy migrations for a new version of cli by
ng initcommand. - 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.
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.
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.
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.
@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
@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"inpackage.jsonto new compiled output files.
@nsmolenskii, got it, thanks for your reply
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.
+1 , x 1,000 if i could :-)
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. :)
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.
:)
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.
Hello @johnpapa, We like to make libraries too, do you have any pattern to show us.
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 angular/angular.io#2758, which was never merged. It is a good starting point currently, if you want to have a look.
Thank you so much @filipesilva
Does it make sense to try using this typerscript boilerplate : https://github.com/alexjoverm/typescript-library-starter ?
That is nice, but the main problem from my experience is the AOT + Webpack bit.
Do we have any timeline on when to expect 2.0?
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.
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.
From my experience, you need to set up a bunch of tools on your own.
tl;dr:
ngcto ES5 target, generating*.js+*.d.ts+*.metadata.json, exclude*.ngfactory.tsfrom distributable package, optionally: include*.js.mapin distributable package- inline templates and styles, compile pre-css languages to css, see angular/angular#15722
- create am UMD bundle referenced in
"main"property ofpackage.json - create an ESM version (in ES2015 module format) referenced in
"module"property ofpackage.json - (possibly more...)
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.
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
@Brocco you mentioned above there will be to support for multiple applications within a project. Is this available yet?
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.
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
@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. 👍
@playground yes, multiple apps are currently supported by the CLI. There is a story that will be added to the wiki: #5737
That library starter from me might also work:
https://github.com/cankayacan/ngx-library-starter
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"
@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.
@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.
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.
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?
@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 angular/angular#16486, and a seed for it in https://github.com/filipesilva/angular-quickstart-lib.
@filipesilva, thanks for a really reasonable comment.
I'm not pretend, that my suggestion is a proper way to manage components libraries, it is just workaround until official support by angular-cli finished.
I have to admit, that such suggestions would never have appeared, if this issue had been solved.
Now you feel the irony of the situation, don't you?
Thanks for the update.
I will check https://github.com/filipesilva/angular-quickstart-lib
I know you guys will have lots of other issues to focus on.
Hoping to see an update from cli team soon :)
@nsmolenskii Finally every thing works here , used this npm plugin for svn support in repository.
At least i was happy that we are able to bring a temp solution to the desk to keep the project going.
Hi, for my purposes, I scrambled together a packaging script that does all the necessary transformations and produces a library in the Angular Package Format:
https://github.com/dherges/ng-packagr
There are still issues, minification is not yet implemented , source maps need to be re-mapped, and the source maps from downleveling with ... so I will neither support this nor publish this to npm. Things are inspired by the build tasks from the material2 teamtsc are lost
If you like, let's try to incorporate this into Angular CLI. Is there anyone working on the compile library feature? If yes, who can I get in touch with?
Cheers! 🍻
UPDATE: I even added the source-map transformation chain.
@dherges I appreciate your offer but we're not yet open to contributions for this new feature :/
@filipesilva Ok, no deal.
Given that, I am looking for people from the community who are interested in implementing a packaging tool for Angular libraries. You can contact me here on my Twitter account
In contradiction to what I just said a very very loooong time ago, I decided to publish ng-packagr.
Once again, I stress that I am not really able to support this tool for everyone. I believe that a community effort will lead to way better results than one individual can ever achieve. Feel free to use ng-packagr when it suits your needs! If you find any issues or want to add missing features, don't hesitate to contact me ... open issues or pull requests! It's always welcome!
It looks like our company is going to hold back on publishing our Angular modules to the Open Source community until this is figured out. We need to spend more time writing application code, less time maintaining our own custom build chain. We're happy to contribute some hours to helping standardize on this.
Thanks to everyone who threw starter packs together. We've struggled with this problem too and spent countless hours on our NG2 builds. In the end some combination of ngc, webpack and custom gulp tasks worked for us.
To angular team: Angular is loosing ground to React and Vue and others for developer mindshare. Mainly due to the fact that it's so damn hard to package reusable components. This should be your number 1 concern to kick start Angular community.
@oliverjanik
I absolutely agree with you.
Angular should support code sharing(library) as soon as possible
@achieverprince that is disrespectful to framework authors. IMHO framework can be anything for anyone. And remember, we get it for free (which is kinda amazing) - if you don't like something - patches are always welcome
I used https://github.com/robisim74/angular-library-starter with 3 npm packages (http://npmjs.com/~orizens) thus far and it's working quite well with AOT
@benetis-bentley
Not at all, i am not disrespecting any framework or anyone.
We all are here because of the wonderful framework Angular and i love to use it.
I was just worried, Angular should not lose its popularity because of this.
My words would have been little harsh, i apologize if i have hurt any one. (edited my previous comment as well)
I do have to say, it is getting harder than angularjs because of the fragmentation... (angular 2, angular 4), even upgrading the framework from angular 4.0.3 > 4.1.2 broke the build (I think it has nothing to do with the framework, it is problem with the CLI)
It is going out of scope for this issue, so i ll leave it here.
I am just a encouraged developer looking to promote Angular.
Unfortunately I agree with you. The Angular team has not been able to create a simple framework for the community. Instead he has put more inconveniences along the way than improvements.
In my team we have made a library for Angular 2/4 and we have had many problems to support the different versions and, above all, the AOT compilation.
If a framework wants to be successful it needs the community, and it is evident that Angular 2/4 has not been built with the community in mind.
It would be well if the Angular team would participate in the reflection created in this issue and tell us their impressions.
Perhaps the idea of what an Angular Library needs to change to better go with the flow that Angular CLI supports. My thought is that instead of attempting to create an alternative set of build tools for Angular Libraries (ex. https://github.com/gonzofish/angular-library-set), libraries could be included directly into an Angular CLI based project in the /src/app/contrib/<angular library module name> directory so that the standard Angular CLI build chain picks it up. This might get messy with dependency management but Open Source projects like Drupal were able to foster a thriving ecosystem of community contributed modules that did not have the luxury of being able to use their own specific version of some dependency.
@rjsteinert I agree that creating third-party tools don't solve the problem--I created Angular Librarian when I realized using the CLI wasn't going to be possible/too cumbersome to create a library.
I'd love to incorporate what librarian and other generators have done into the CLI to perpetuate a set of standards & practices when it comes to developing Angular code.
It's great to see so many people eager to help with this feature, however @filipesilva commented above:
I appreciate your offer but we're not yet open to contributions for this new feature :/
I think this means that Angular team is working hard on this feature. I only hope to see an update with the progress/roadmap to calm the community down a bit.
@DmitryEfimenko I think that would be great for the community to get an update with the progress as many of us in the community have been eagerly waiting for this feature to be out.
@DmitryEfimenko
I doubt that, cos the priority is still "required".
I think the Angular team has other major issues to deal with in their bucket.
I absolutely respect the team on prioritizing the issues (they know the actual situation)
I think we shouldn't pressure them as well, but what other choice do we got.
Thanks everyone for your comments.
We really appreciate the discussion regarding libraries, but unfortunately this will not be implemented as part of CLI 1.x. There are multiple challenges that are insurmountable with library support and the current state of the CLI. Here are a few examples (in no particular order, and non-exhaustive):
- Webpack does not support the kind of modules we're looking for when publishing Angular libraries (e.g. metadata.json and d.ts files).
- Webpack does not support (but it's on the roadmap) outputting ES6 code like we suggest for flat modules.
- We do not have a story yet for a real multi-application projects, which is required for developing libraries (you want a demo app, a development app and an e2e app for developing libraries).
- We do not have support for custom templates, and creating templates right now is particularly expensive for us.
- We do not have support for having multiple entry points.
- There's no proper serve/test/e2e, or even build stories for libraries in particular. What I mean by this is that no design has been done yet on how e.g.
ng servein a library would even work. This is a surprisingly hard problem for us because the CLI should stay as simple-to-use as possible. Same goes forng test; our current karma config relies heavily on Webpack (see points above).
There are of course other problems that arise when building a CLI tool that supports both libraries and applications while being simple and straightforward to understand.
As for the way forward, we are currently building our Angular Development Kit and in the early design stages. We are rethinking the build story entirely and taking into account libraries from the start. Unfortunately the timeline for the DevKit is rather fuzzy, but once we have something more concrete we will share it with the community.
I'm going to lock this conversation for now, to make sure people coming into this thread see this message. I am not entirely sure this issue will live on as we move to the DevKit, but wherever news happen on library support in the CLI I will point to from this thread so people can follow.
Thanks everyone.
Addendum: We are in the process of adding custom template support to the CLI, and with it another tool that can be used to generate just templates but outside the CLI. We will consider having a scaffold for basic library projects, but it will not be part of the Angular CLI.
I created #6510 to keep this thread locked, but the conversation going. Please continue the discussion over to the new issue, so that people coming here see the official answer.
In version 6.0.0 of Angular CLI you will be able to create, test and lint libraries.
This functionality is available in the latest RCs of 6.0.0, and documentation can temporarily be found at https://github.com/angular/angular-cli/blob/master/docs/documentation/stories/create-library.md. Once 6.0.0 reaches final, the documentation will be moved to the main wiki.