docs(cb-third-party-lib) create a third party lib #2758

thelgevold · 2016-11-05T17:29:43Z

WIP. Do not merge

s s s s s c s c s s s s s s s s s s s s s s s s s s s s s s s s s

thelgevold · 2016-11-05T21:55:58Z

Ready for review:

Here is my Third-Party-Library cookbook.

The library is published with support for AoT and JiT builds.

AoT files:: JS with esm modules, .d.ts and metadata.json, html, and css files

JiT: files: umd bundle with inlined templates and css.

The html/css inlining approach is currently using a script borrowed from material 2.

The sample library is published to node_modules via a custom script triggered from add-example-boilerplate

@wardbell @robwormald @filipesilva @Foxandxss

Foxandxss · 2016-11-07T12:35:01Z

public/docs/ts/latest/cookbook/third-party-lib.jade

+
+:marked
+  Traditionally, third party JavaScript libraries have been published in the form of a single minified JavaScript file.
+  Consumers of the library have then included the minified JavaScript file, "as is", somewhere on the page using a `script` tag.


I would personally drop the "minified" mentions you have in here. It is more common to see unminified source now than minified. Your tool will always minify third party libraries. And even when you have both options, it is better to not add the minified versions. Angular for example strips all error messages from minified versions.

Foxandxss · 2016-11-07T12:39:28Z

public/docs/ts/latest/cookbook/third-party-lib.jade

+
+  Modern web development has changed this process. Instead of publishing a "one size fits all" bundle, developers want to only include the parts of the library they actually need.
+
+  This cookbook will show how to publish a third party library in a way that makes it possible to take advantage of techniques like Ahead of Time Compilation (AoT) and Tree shaking.


Avoid the word will.

Foxandxss · 2016-11-07T13:07:29Z

public/docs/ts/latest/cookbook/third-party-lib.jade

+
+  In addition to supporting AoT, the library code should also be "Tree Shakable". 
+
+  Thee Shakers work best with `ES2015` JavaScript. 


Foxandxss · 2016-11-07T13:08:35Z

public/docs/ts/latest/cookbook/third-party-lib.jade

+
+  AoT compiled code is the prefered format for production builds, but due to the long compilation time, it may not be practical to use AoT during development.
+
+  To create a more flexible developer experience, a JiT compatible build of the library should be published as well. The format of the JiT bundle is `umd`, which stands for Universal Module Definition. Shipping the bundle as `umd` ensures compatability with most common module loading formats.


compatibility

Foxandxss · 2016-11-07T13:11:16Z

public/docs/ts/latest/cookbook/third-party-lib.jade

+  ## Publish
+
+:marked
+  `Rollup` wil create the `umd` bundle, but but prior to bundling, all external templates or css files must be inlined. 


No will (or wil :P)

Double but.

Foxandxss · 2016-11-07T13:29:50Z

I am more worried in teaching Webpack as well. There are a lot of libraries being published with a Webpack tooling and the would need guidance as well.

thelgevold · 2016-11-07T23:39:36Z

@Foxandxss Thanks for the review. I have made tweaks based on your feedback.

I am unsure about the Webpack part though. My thinking is that the most important take-away from this is learning what is required to be AoT compatible. Specifically, which files to include.

I do agree that webpack seems to be very popular these days though. I have also seen feedback that people would like to see more webpack stuff in our AoT docs.

What I find appealing about Rollup is that the configuration is simpler and requires less intensive tech stack explanations.

However, I want to try to offer the most useful content to the users...

@wardbell @robwormald Any feedback on whether it makes sense to include webpack here vs updating our existing webpack guide?

Foxandxss · 2016-11-07T23:40:47Z

Leave the webpack aside I guess. I would like to think about some ideas but I need to run all of them through Ward first.

filipesilva

The chapter looks good @thelgevold! It clarified a bunch of stuff for me, and I especially like how succinct it is.

I think we need to generalize and publish an angular/quickstart-lib for people to use as well, but that can be done later.

I have a few change requests though, nothing major.

filipesilva · 2017-01-05T12:36:44Z

public/docs/ts/latest/cookbook/third-party-lib.jade

+
+  `tsconfig.json` for JiT compilation and `tsconfig-aot.json` for AoT compilation.
+
+makeTabs(


index.ts is mentioned elsewhere in the prose but not shown here.

filipesilva · 2017-01-05T12:38:56Z

public/docs/ts/latest/cookbook/third-party-lib.jade

+
+makeTabs(
+  `cb-third-party-lib/hero-profile/hero-profile.module.ts,
+   cb-third-party-lib/hero-profile/tsconfig-aot.json,


Would it be possible to actually only use one tsconfig.json, but invoke it with overrides for the changed props?

For instance ngc --module=es2015.

filipesilva · 2017-01-05T12:42:47Z

public/docs/_examples/cb-third-party-lib/hero-profile/hero-profile.component.ts

+  moduleId: module.id,
+  selector: 'hero-profile',
+  templateUrl: 'hero-profile.component.html',
+  styleUrls: ['hero-profile.component.css']


#3071 changed all paths to be relative, these should be as well.

filipesilva · 2017-01-05T12:45:40Z

public/docs/ts/latest/cookbook/third-party-lib.jade

+makeTabs(
+  `cb-third-party-lib/hero-profile/hero-profile.module.ts,
+   cb-third-party-lib/hero-profile/tsconfig-aot.json,
+   cb-third-party-lib/ts/tsconfig.json,


Can you make tsconfig.1.json for this chapter with the config you want to show and use it here?

Our internal tsconfigs have some properties that shouldn't be shown to users:

"typeRoots": [ "../../node_modules/@types/" ]

"exclude": [ "node_modules/*", "**/*-aot.ts", "app-aot" ]

filipesilva · 2017-01-05T12:46:36Z

public/docs/_examples/cb-third-party-lib/hero-profile/publish.js

+
+  // AoT compile
+  var spawnNgc = require( 'child_process' ).spawnSync;
+  var ngc = spawnNgc('./public/docs/_examples/node_modules/.bin/ngc', ['-p', './public/docs/_examples/cb-third-party-lib/hero-profile/tsconfig-aot.json']);


Although this is the correct path for our tooling, it shouldn't be the path shown to users.

filipesilva · 2017-01-05T12:46:44Z

public/docs/_examples/cb-third-party-lib/hero-profile/publish.js

+  var fs = require('fs');
+  var del = require('del');
+
+  var node_modules_root = './public/docs/_examples/node_modules/hero-profile/';


Same as above.

filipesilva · 2017-01-05T12:47:47Z

public/docs/_examples/cb-third-party-lib/hero-profile/publish.js

+
+  var node_modules_root = './public/docs/_examples/node_modules/hero-profile/';
+
+  del.sync(node_modules_root, {force:true});


What is this step for? It's not explained in the prose.

filipesilva · 2017-01-05T12:54:38Z

public/docs/ts/latest/cookbook/third-party-lib.jade

+:marked
+   ## Final Application 
+
+   If you have cloned the `Angular.io` repo, all the steps described in this cookbook can be executed by running the following command:


I think we need to give people instructions on how to build a sample lib outside of angular.io. Something like a angular/quickstart-lib, side by side with angular/quickstart.

This is something I can do later and should not block the release of this chapter.

I think that makes sense. Some of the complexity comes from having to simulate an npm dependency, and at the same time, make it work with the angular.io workflow.

I think most of the value is in teaching what types of files are necessary to make the library AoT compatible.

I think it's also useful to describe the umd part of the library and its use.

filipesilva · 2017-03-22T18:24:15Z

Superseded by #3411

googlebot added the CLA: yes label Nov 5, 2016

thelgevold force-pushed the cb-third-party-lib branch 4 times, most recently from ee2bc6a to ecde57b Compare November 5, 2016 21:45

docs(cb-third-party-lib) create a third party lib

ab8e8ed

s s s s s c s c s s s s s s s s s s s s s s s s s s s s s s s s s

thelgevold force-pushed the cb-third-party-lib branch from ecde57b to ab8e8ed Compare November 5, 2016 21:48

thelgevold changed the title ~~WIP: docs(cb-third-party-lib) create a third party lib~~ docs(cb-third-party-lib) create a third party lib Nov 5, 2016

Foxandxss reviewed Nov 7, 2016

View reviewed changes

addressing PR review items

0ea2b04

filipesilva suggested changes Jan 5, 2017

View reviewed changes

filipesilva mentioned this pull request Feb 13, 2017

Webpack build breaks ability to use npm installed custom components angular/angular-cli#1624

Closed

filipesilva mentioned this pull request Mar 9, 2017

[Feature] Create boilerplate for library angular/angular-cli#1692

Closed

filipesilva mentioned this pull request Mar 22, 2017

New cb third party lib #3411

Open

filipesilva closed this Mar 22, 2017

matheo mentioned this pull request Apr 20, 2017

Find the way to publish this as a library codelab-fun/codelab#5

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(cb-third-party-lib) create a third party lib #2758

docs(cb-third-party-lib) create a third party lib #2758

thelgevold commented Nov 5, 2016

thelgevold commented Nov 5, 2016 •

edited

Loading

Foxandxss Nov 7, 2016

Foxandxss Nov 7, 2016

Foxandxss Nov 7, 2016

Foxandxss Nov 7, 2016

Foxandxss Nov 7, 2016

Foxandxss Nov 7, 2016

Foxandxss commented Nov 7, 2016

thelgevold commented Nov 7, 2016 •

edited

Loading

Foxandxss commented Nov 7, 2016

filipesilva left a comment

filipesilva Jan 5, 2017

filipesilva Jan 5, 2017

filipesilva Jan 5, 2017

filipesilva Jan 5, 2017

filipesilva Jan 5, 2017

filipesilva Jan 5, 2017

filipesilva Jan 5, 2017

filipesilva Jan 5, 2017

thelgevold Jan 6, 2017

thelgevold Jan 6, 2017

filipesilva commented Mar 22, 2017


		Modern web development has changed this process. Instead of publishing a "one size fits all" bundle, developers want to only include the parts of the library they actually need.

		This cookbook will show how to publish a third party library in a way that makes it possible to take advantage of techniques like Ahead of Time Compilation (AoT) and Tree shaking.


		In addition to supporting AoT, the library code should also be "Tree Shakable".

		Thee Shakers work best with `ES2015` JavaScript.


		AoT compiled code is the prefered format for production builds, but due to the long compilation time, it may not be practical to use AoT during development.

		To create a more flexible developer experience, a JiT compatible build of the library should be published as well. The format of the JiT bundle is `umd`, which stands for Universal Module Definition. Shipping the bundle as `umd` ensures compatability with most common module loading formats.


		`tsconfig.json` for JiT compilation and `tsconfig-aot.json` for AoT compilation.

		+makeTabs(


		var node_modules_root = './public/docs/_examples/node_modules/hero-profile/';

		del.sync(node_modules_root, {force:true});

docs(cb-third-party-lib) create a third party lib #2758

docs(cb-third-party-lib) create a third party lib #2758

Conversation

thelgevold commented Nov 5, 2016

thelgevold commented Nov 5, 2016 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Foxandxss commented Nov 7, 2016

thelgevold commented Nov 7, 2016 • edited Loading

Foxandxss commented Nov 7, 2016

filipesilva left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

filipesilva commented Mar 22, 2017

thelgevold commented Nov 5, 2016 •

edited

Loading

thelgevold commented Nov 7, 2016 •

edited

Loading