Improve how this is published and distributed

tomwayson commented 7 years ago

After all the pain and suffering that I went through trying to initially publish library in way that it could actually be consumed in an Angular app, there are now actually a few good resources on how to properly publish an angular library:

https://medium.com/@cyrilletuzi/how-to-build-and-publish-an-angular-module-7ad19c0b4464 http://blog.mgechev.com/2017/01/21/distributing-an-angular-library-aot-ngc-types/

UPDATE: See below for final punch list

Things I'm sure I want to do:

update to latest esri-loader
Output as ES5/ESM (module) and UMD (main)
use rollup and uglify for umd build
output to dist & only publish dist

Things I'm not sure are needed, nor how beneficial they are for a library that only exposes a service:

use ngc instead of tsc for module build
Include an Angular module that exposes the service? Sounds like this is needed for ngc? Would this be a breaking change?

Prob could use angular2-esri4-components as a starting point if going w/ ngc and module.

Also not sure if this sentence from the medium article: "explicit "paths" to other modules you use are needed, as the final bundle won’t include them directly (more on that later)." which refers to these lines would apply to esri-loader.

tomwayson commented 7 years ago

@kgs916 would love your input if you think ngc (and if so, and Angular module) are warranted in this case.

tomwayson commented 7 years ago

This will obviate the need for #5 and #8

tomwayson commented 7 years ago

There's also this talk from ngconf https://www.youtube.com/watch?v=unICbsPGFIA (haven't watched yet)

TheKeithStewart commented 7 years ago

@tomwayson yeah, this was a good talk about how to properly structure your libraries for Angular. I was actually sitting front row for this talk.

Creating an NgModule for the library and using ngc for transpiling will probably be the way to go here. I'll look into it a bit more though and get back to you soon.

tomwayson commented 7 years ago

OK

After watching that talk I'm convinced to:

add an NgModule for the service
use ngc to compile
generate FESM output and have package.module point to that
base the file structure on https://github.com/jasonaden/simple-ui-lib and https://github.com/filipesilva/angular-quickstart-lib
not generate a UMD bundle, this library doesn't currently have one, so no consumers are currently depending on it

I could take or leave the es2015 output. Seems like once you get the FESM set up, it's not hard to add ES2015, but I don't think it would get used by anyone for a while and it's one more thing to maintain. I'd say get FESM output working in a few apps and consider adding es2015 later, like if someone asks for it.

I'd be half tempted to go all in on angular-quickstart-lib (include the demo and integration apps and tests, if it weren't for this warning. I've been bit in the ass too many times by being on the bleeding edge with Angular. Even using FESM instead of ESM makes me a bit nervous, but if that's what core and material are shipping I guess it works. So for now, I'd say focus on the above bullet points (basically https://github.com/jasonaden/simple-ui-lib w/o es2015 and move src under src/lib) and later can add more stuff from https://github.com/filipesilva/angular-quickstart-lib as it matures.

Thoughts @kgs916?

tomwayson commented 7 years ago

@patrickarlt @noahmulfinger I think you guys are using this too, so just wanted to get your 👍 and/or feedback on above plan before moving forward.

TheKeithStewart commented 7 years ago

@tomwayson I like the bullets that you laid out. The one thing that I don't like about Jason Aden's setup is the use of the shell script for executing the build. I'd rather use NPM modules and scripts so that it can more easily be run on different platforms.

tomwayson commented 7 years ago

completely agree, that was my plan too.

tomwayson commented 7 years ago

Final proposed punch list:

[x] update to latest esri-loader
[x] base the file structure on https://github.com/jasonaden/simple-ui-lib (except moving code under src/lib as in https://github.com/filipesilva/angular-quickstart-lib)
[x] add an NgModule for the service
[x] use ngc to compile and get tsconfig params from above repos & generate FESM output
[x] use rollup to bundle FESM
[x] remove package.main and have package.module point FESM
[x] output to dist & only publish dist

tomwayson commented 7 years ago

resolved in #12

tomwayson / angular-esri-loader

Improve how this is published and distributed #9