WIP - AIO: Third party library guide #16486

filipesilva · 2017-05-02T18:44:43Z

Please check if the PR fulfills these requirements

The commit message follows our guidelines: https://github.com/angular/angular/blob/master/CONTRIBUTING.md#commit
Tests for the changes have been added (for bug fixes / features)
Docs have been added / updated (for bug fixes / features)

What kind of change does this PR introduce? (check one with "x")

[ ] Bugfix
[ ] Feature
[ ] Code style update (formatting, local variables)
[ ] Refactoring (no functional changes, no api changes)
[ ] Build related changes
[ ] CI related changes
[x] Other... Please describe: AIO third party lib guide

What is the current behavior? (You can also link to an open issue here)
N/A

What is the new behavior?
A guide for third party library development is added. This PR is a port from angular/angular.io#3411.

Does this PR introduce a breaking change? (check one with "x")

[ ] Yes
[x] No

If this PR contains a breaking change, please describe the impact and migration path for existing applications: ...

Other information:
For now the quickstart lib seed is hosted at https://github.com/filipesilva/angular-quickstart-lib. It should be hosted under the angular org upon release.

/cc @wardbell @alxhub

mary-poppins · 2017-05-02T19:02:01Z

The angular.io preview for 1c9e4ce is available here.

gkalpak

That will be really helpful for library authors 👍

gkalpak · 2017-05-02T19:36:47Z

aio/content/guide/third-party-lib.md

+the library they actually need and in the format they need it in.
+
+This cookbook shows how to publish a third party library in a way that makes it possible to 
+fully benefit from techniques like Ahead of Time Compilation (AOT) and Tree Shaking.


Inconsistent capitalization AOT (here) vs AOT (above).

gkalpak · 2017-05-02T19:45:16Z

aio/content/guide/third-party-lib.md

+Third Party Library
+
+@intro
+Create a third party library with support for AoT, JiT and Tree Shaking.


I've noticed several variations throughout the text for terms like AOT anf JIT (e.g. "AoT" vs "AOT", "Ahead of Time" vs "Ahead-of-time" etc). I think we should be consistent.

gkalpak · 2017-05-02T19:45:47Z

aio/content/guide/third-party-lib.md

+
+- `main` (default): an ES5 [UMD](https://github.com/umdjs/umd) bundle that can be consumed anywhere.
+- `module`: a flat ECMAScript Module (ESM) bundle containing ES5 code.
+- `es2015`: a flat ESM containing ES2015 bundle.


bundle --> code (?)

gkalpak · 2017-05-02T19:49:44Z

aio/content/guide/third-party-lib.md

+</div>
+
+<div class="l-sub-section">
+  A flat ECMAScript module (FESM) is a bundled ECMAScript module where all imports were followed 


were followed copied onto the same file file --> ?

gkalpak · 2017-05-02T19:53:03Z

aio/content/guide/third-party-lib.md

+## The QuickStart Library seed
+
+Setting up a new library project on your machine is quick and easy with the **QuickStart Library seed**,
+maintained [on github](https://github.com/angular/quickstart-lib "Install the github QuickStart Library repo").


The link is invalid. Is the project supposed to be created later?

Correct, for now it is in https://github.com/filipesilva/angular-quickstart-lib. When this guide is approved we can move the codebase under the Angular org.

gkalpak · 2017-05-02T20:19:23Z

aio/content/guide/third-party-lib.md

+
+- Keep an eye on the issue tracker.
+- Document your library.
+- [Manage your dependencies properly](guide/appendix-dependency-management)


Wrong link. It should be guide/third-party-lib#appendix-dependency-management.

gkalpak · 2017-05-02T20:23:10Z

aio/content/guide/third-party-lib.md

+
+Why not ship TypeScript source instead? 
+After all the library will be part of another TypeScript compilation step when the library is
+imported by the consuming application? 


? --> . (?)

gkalpak · 2017-05-02T20:24:32Z

aio/content/guide/third-party-lib.md

+- `dependencies`: here go all the other libraries yours depends on when being used.
+A good way to figure out these is to go through your library source code (in `src/lib` **only**)
+and list all the libraries there.
+- `devDependencies`: libraries that you need while developing, testing and building your app


app --> library

gkalpak · 2017-05-02T20:24:59Z

aio/content/guide/third-party-lib.md

+go here.
+When a user installs your library, these won't be installed. 
+Users don't need to develop, build or test your library, they just need to run it.
+your app.


Remove this line.

gkalpak · 2017-05-02T20:27:37Z

aio/content/guide/third-party-lib.md

+A good rule of thumb is to have all `dependencies` specified with a tilde `~`(`~1.2.3`),
+while your `peerDependencies` have a range (`"@angular/core": ">=4.0.0 <5.0.0 || >=4.0.0-beta <5.0.0"`).
+
+Any extra dependency or peer Dependency that you add to `package.json` should also be added


peer Dependency --> peer dependency (?)

FriOne · 2017-05-10T13:20:21Z

@filipesilva It would be nice to have a seed on github for this instead of text(or both). Thanks, It should help me to solve a problem.

filipesilva · 2017-05-10T14:04:19Z

@FriOne the seed is temporarily at https://github.com/filipesilva/angular-quickstart-lib

filipesilva · 2017-05-10T15:21:39Z

Thank you for the review @gkalpak, lots of improvements there.

danwulff · 2017-05-25T21:42:58Z

I'm looking forward to this being merged and the quickstart-lib codebase being added to @angular.

nathanosdev · 2017-06-03T13:13:33Z

aio/content/guide/third-party-lib.md

+
+Only code written in TypeScript can be AOT compiled.
+
+Before publishing the library must first be compiled using the AOT compiler (`ngc`). 


Add a comma after 'publishing', otherwise the sentence can be confusing the first time it is read.

nathanosdev · 2017-06-03T13:16:28Z

aio/content/guide/third-party-lib.md

+JavaScript has no way of representing typings. 
+In order to preserve the original typings, `ngc` will generate `.d.ts` typings files.
+
+*Meta Data JSON files*


All mentions of 'meta data' here are inconsistent with references to 'metadata' elsewhere in the document. It should be 'metadata' everywhere.

austince · 2017-07-20T15:38:23Z

aio/content/guide/third-party-lib.md

+You shouldn't have a `library-name.js` file, as it will be auto generated by `ngc` in order to 
+create a flat module, re-exporting the public API of your library.
+
+Below is a handy list for you to check if your entry points files are correctly build:


Typo: are correctly build: -> are correctly built:

johnpapa · 2017-10-09T19:18:55Z

What is the status on this? Would love to have official Angular team guidance on creating these library apps.

IgorMinar · 2018-02-06T23:45:13Z

@filipesilva should we try to resurrect this guide and reuse it for the docs we'll need for the upcoming library support in CLI? or should we close this PR?

cc: @jenniferfell

filipesilva · 2018-02-08T08:45:23Z

@IgorMinar I think at this point too much has changed. The examples will not be applicable to the new source, and neither will be the explanations about internals.

I think it should be closed but used as inspiration for a new one. The structure and the peripheral explanations still apply.

brandonroberts · 2018-08-03T14:47:13Z

Closing this one for now.

angular-automatic-lock-bot · 2019-09-13T21:53:00Z

This issue has been automatically locked due to inactivity.
Please file a new issue if you are encountering a similar or related problem.

Read more about our automatic conversation locking policy.

_{This action has been performed automatically by a bot.}

googlebot added the cla: yes label May 2, 2017

gkalpak reviewed May 2, 2017

View reviewed changes

wardbell added comp: aio and removed cla: yes labels May 4, 2017

This was referenced May 5, 2017

AOT error when referencing components from another project angular/angular-cli#6059

Closed

"Please add a @NgModule annotation." error with AOT, full path vs short package.json main angular/angular-cli#6239

Closed

googlebot added the cla: yes label May 10, 2017

This was referenced May 11, 2017

Library with Typescript files fails to compile in AOT angular/angular-cli#6228

Closed

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

Closed

tomwanzek mentioned this pull request May 16, 2017

Fails when use systemjs.config.js tomwanzek/d3-ng2-service#27

Closed

ajcrites mentioned this pull request May 18, 2017

Built module distribution cannot be imported to other modules angular/angular-cli#6378

Closed

robwormald mentioned this pull request May 31, 2017

[RFC] Library Support and Boilerplate Comment Thread angular/angular-cli#6510

Closed

rjcorwin mentioned this pull request May 31, 2017

Add code reuse FAQ to NG Module Guide #17129

Closed

3 tasks

nathanosdev reviewed Jun 3, 2017

View reviewed changes

wardbell added area: packaging Issues related to Angular's creation of npm packages area: build & ci Related the build and CI infrastructure of the project area: core Issues related to the framework runtime and removed comp: aio labels Jun 21, 2017

austince reviewed Jul 20, 2017

View reviewed changes

franzbecker mentioned this pull request Jul 25, 2017

import seed project test-editor/deprecated-web-workspace-navigator#1

Merged

filipesilva added 3 commits July 26, 2017 12:54

add nav and dummy file

71f652b

add base jade

4c42ae8

add auto converted

0d0f1cd

filipesilva added 4 commits July 26, 2017 12:54

fix tables and filetree

d09b402

add title/intro

f2d632f

review content

c5d11f9

incorporate @gkalpak's feedback

97c6e83

mhevery force-pushed the new-cb-third-party-lib branch from fe1d5c9 to 97c6e83 Compare July 26, 2017 19:54

axtho mentioned this pull request Aug 11, 2017

update the link parts for angular-cli and update to ngrx v4 benorama/ngrx-demo-apps#13

Closed

ebtc mentioned this pull request Aug 15, 2017

core(bug): adapt to latest cli digitaldeacon/memberhive#149

Closed

lazarljubenovic mentioned this pull request Sep 16, 2017

Use the Angular Package Format sebholstein/angular-google-maps#1157

Closed

jenniferfell added the state: community Someone from the Angular community is working on this issue or submitted this PR label Jul 23, 2018

brandonroberts closed this Aug 3, 2018

angular-automatic-lock-bot bot locked and limited conversation to collaborators Sep 13, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

WIP - AIO: Third party library guide #16486

WIP - AIO: Third party library guide #16486

filipesilva commented May 2, 2017 •

edited

Loading

mary-poppins commented May 2, 2017

gkalpak left a comment

gkalpak May 2, 2017

filipesilva May 10, 2017

gkalpak May 2, 2017

filipesilva May 10, 2017

gkalpak May 2, 2017

filipesilva May 10, 2017

gkalpak May 2, 2017

filipesilva May 10, 2017

gkalpak May 2, 2017

filipesilva May 10, 2017

gkalpak May 2, 2017

filipesilva May 10, 2017

gkalpak May 2, 2017

filipesilva May 10, 2017

gkalpak May 2, 2017

filipesilva May 10, 2017

gkalpak May 2, 2017

filipesilva May 10, 2017

gkalpak May 2, 2017

filipesilva May 10, 2017

FriOne commented May 10, 2017 •

edited

Loading

filipesilva commented May 10, 2017

filipesilva commented May 10, 2017

danwulff commented May 25, 2017

nathanosdev Jun 3, 2017

nathanosdev Jun 3, 2017

austince Jul 20, 2017

johnpapa commented Oct 9, 2017

IgorMinar commented Feb 6, 2018

filipesilva commented Feb 8, 2018 •

edited

Loading

brandonroberts commented Aug 3, 2018

angular-automatic-lock-bot bot commented Sep 13, 2019


		Only code written in TypeScript can be AOT compiled.

		Before publishing the library must first be compiled using the AOT compiler (`ngc`).

WIP - AIO: Third party library guide #16486

WIP - AIO: Third party library guide #16486

Conversation

filipesilva commented May 2, 2017 • edited Loading

mary-poppins commented May 2, 2017

gkalpak 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

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

FriOne commented May 10, 2017 • edited Loading

filipesilva commented May 10, 2017

filipesilva commented May 10, 2017

danwulff commented May 25, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

johnpapa commented Oct 9, 2017

IgorMinar commented Feb 6, 2018

filipesilva commented Feb 8, 2018 • edited Loading

brandonroberts commented Aug 3, 2018

angular-automatic-lock-bot bot commented Sep 13, 2019

filipesilva commented May 2, 2017 •

edited

Loading

FriOne commented May 10, 2017 •

edited

Loading

filipesilva commented Feb 8, 2018 •

edited

Loading