docs: add lightweight token page to library section of docs (#36144)

adds new DI technique recommendation for libraries to ensure tree-shaking for unused services
includes reasons for packaging schematics with libraries, clarify schematic usage recommendation

PR Close #36144

.pullapprove.yml

@@ -315,6 +315,7 @@ groups:
           'aio/content/images/guide/dependency-injection-in-action/**',
           'aio/content/guide/dependency-injection-navtree.md',
           'aio/content/guide/dependency-injection-providers.md',
+          'aio/content/guide/lightweight-injection-tokens.md',
           'aio/content/guide/displaying-data.md',
           'aio/content/examples/displaying-data/**',
           'aio/content/images/guide/displaying-data/**',

aio/content/guide/creating-libraries.md

@@ -1,16 +1,13 @@
 # Creating libraries
 
-You can create and publish new libraries to extend Angular functionality. If you find that you need to solve the same problem in more than one app (or want to share your solution with other developers), you have a candidate for a library.
+This page provides a conceptual overview of how you can create and publish new libraries to extend Angular functionality.
 
+If you find that you need to solve the same problem in more than one app (or want to share your solution with other developers), you have a candidate for a library.
 A simple example might be a button that sends users to your company website, that would be included in all apps that your company builds.
 
-<div class="alert is-helpful">
-     <p>For more details on how a library project is structured you can refer the <a href="guide/file-structure#library-project-files">Library Project Files</a></p>
-</div>
-
 ## Getting started
 
-Use the Angular CLI to generate a new library skeleton with the following command:
+Use the Angular CLI to generate a new library skeleton in a new workspace with the following commands.
 
 <code-example language="bash">
  ng new my-workspace --create-application=false
@@ -18,12 +15,18 @@ Use the Angular CLI to generate a new library skeleton with the following comman
  ng generate library my-lib
 </code-example>
 
+The `ng generate` command creates the `projects/my-lib` folder in your workspace, which contains a component and a service inside an NgModule.
+
 <div class="alert is-helpful">
-     <p>You can use the monorepo model to use the same workspace for multiple projects. See <a href="guide/file-structure#multiple-projects">Setting up for a multi-project workspace</a>.</p>
+
+     For more details on how a library project is structured, refer to the [Library project files](guide/file-structure#library-project-files) section of the [Project File Structure guide](guide/file-structure).
+
+     You can use the monorepo model to use the same workspace for multiple projects.
+     See [Setting up for a multi-project workspace](guide/file-structure#multiple-projects).
+
 </div>
 
-This creates the `projects/my-lib` folder in your workspace, which contains a component and a service inside an NgModule.
+When you generate a new library, the workspace configuration file, `angular.json`, is updated with a project of type 'library'.
-The workspace configuration file, `angular.json`, is updated with a project of type 'library'.
 
 <code-example format="json">
 "projects": {
@@ -69,35 +72,30 @@ Here are some things to consider in migrating application functionality to a lib
 
 * Components should expose their interactions through inputs for providing context, and outputs for communicating events to other components.
 
-* Services should declare their own providers (rather than declaring providers in the NgModule or a component), so that they are *tree-shakable*. This allows the compiler to leave the service out of the bundle if it never gets injected into the application that imports the library. For more about this, see [Tree-shakable providers](guide/dependency-injection-providers#tree-shakable-providers).
-
-* If you register global service providers or share providers across multiple NgModules, use the [`forRoot()` and `forChild()` patterns](guide/singleton-services) provided by the [RouterModule](api/router/RouterModule).
-
 * Check all internal dependencies.
    * For custom classes or interfaces used in components or service, check whether they depend on additional classes or interfaces that also need to be migrated.
    * Similarly, if your library code depends on a service, that service needs to be migrated.
-   * If your library code or its templates depend on other libraries (such a Angular Material, for instance), you must configure your library with those dependencies.
+   * If your library code or its templates depend on other libraries (such as Angular Material, for instance), you must configure your library with those dependencies.
 
-## Reusable code and schematics
+* Consider how you provide services to client applications.
 
-A library typically includes *reusable code* that defines components, services, and other Angular artifacts (pipes, directives, and so on) that you simply import into a project.
+   * Services should declare their own providers (rather than declaring providers in the NgModule or a component), so that they are *tree-shakable*. This allows the compiler to leave the service out of the bundle if it never gets injected into the application that imports the library. For more about this, see [Tree-shakable providers](guide/dependency-injection-providers#tree-shakable-providers).
-A library is packaged into an npm package for publishing and sharing, and this package can also include [schematics](guide/glossary#schematic) that provide instructions for generating or transforming code directly in your project, in the same way that the CLI creates a generic skeleton app with `ng generate component`.
-A schematic that is combined with a library can, for example, provide the Angular CLI with the information it needs to generate a particular component defined in that library.
 
-What you include in your library is determined by the kind of task you are trying to accomplish.
+   * If you register global service providers or share providers across multiple NgModules, use the [`forRoot()` and `forChild()` design patterns](guide/singleton-services) provided by the [RouterModule](api/router/RouterModule).
-For example, if you want a dropdown with some canned data to show how to add it to your app, your library could define a schematic to create it.
-For a component like a dropdown that would contain different passed-in values each time, you could provide it as a component in a shared library.
 
-Suppose you want to read a configuration file and then generate a form based on that configuration.
+   * If your library provides optional services that might not be used by all client applications, support proper tree-shaking for that case by using the [lightweight token design pattern](guide/lightweight-injection-tokens).
-If that form will need additional customization by the user, it might work best as a schematic.
-However, if the forms will always be the same and not need much customization by developers, then you could create a dynamic component that takes the configuration and generates the form.
-In general, the more complex the customization, the more useful the schematic approach.
 
 {@a integrating-with-the-cli}
 
-## Integrating with the CLI
+## Integrating with the CLI using code-generation schematics
 
-A library can include [schematics](guide/glossary#schematic) that allow it to integrate with the Angular CLI.
+A library typically includes *reusable code* that defines components, services, and other Angular artifacts (pipes, directives, and so on) that you simply import into a project.
+A library is packaged into an npm package for publishing and sharing.
+This package can also include [schematics](guide/glossary#schematic) that provide instructions for generating or transforming code directly in your project, in the same way that the CLI creates a generic new component with `ng generate component`.
+A schematic that is packaged with a library can, for example, provide the Angular CLI with the information it needs to generate a component that configures and uses a particular feature, or set of features, defined in that library.
+One example of this is Angular Material's navigation schematic which configures the CDK's `BreakpointObserver` and uses it with Material's `MatSideNav` and `MatToolbar` components.
+
+You can create and include the following kinds of schematics.
 
 * Include an installation schematic so that `ng add` can add your library to a project.
 
@@ -105,11 +103,20 @@ A library can include [schematics](guide/glossary#schematic) that allow it to in
 
 * Include an update schematic so that `ng update` can update your library’s dependencies and provide migrations for breaking changes in new releases.
 
+What you include in your library depends on your task.
+For example, you could define a schematic to create a dropdown that is pre-populated with canned data to show how to add it to an app.
+If you want a dropdown that would contain different passed-in values each time, your library could define a schematic to create it with a given configuration. Developers could then use `ng generate` to configure an instance for their own app.
+
+Suppose you want to read a configuration file and then generate a form based on that configuration.
+If that form will need additional customization by the developer who is using your library, it might work best as a schematic.
+However, if the forms will always be the same and not need much customization by developers, then you could create a dynamic component that takes the configuration and generates the form.
+In general, the more complex the customization, the more useful the schematic approach.
+
 To learn more, see [Schematics Overview](guide/schematics) and [Schematics for Libraries](guide/schematics-for-libraries).
 
 ## Publishing your library
 
-Use the Angular CLI and the npm package manager to build and publish your library as an npm package. 
+Use the Angular CLI and the npm package manager to build and publish your library as an npm package.
 
 Before publishing a library to NPM, build it using the `--prod` flag which will use the older compiler and runtime known as View Engine instead of Ivy.
 

aio/content/guide/lightweight-injection-tokens.md

@@ -0,0 +1,187 @@
+# Optimizing client app size with lightweight injection tokens
+
+This page provides a conceptual overview of a dependency injection technique that is recommended for library developers.
+Designing your library with *lightweight injection tokens* helps optimize the bundle size of client applications that use your library.
+
+You can manage the dependency structure among your components and injectable services to optimize bundle size by using [tree-shakable providers](guide/dependency-injection-providers#tree-shakable-providers).
+This normally ensures that if a provided component or service is never actually used by the app, the compiler can eliminate its code from the bundle.
+
+However, due to the way Angular stores injection tokens, it is possible that such an unused component or service can end up in the bundle anyway.
+This page describes a dependency-injection design pattern that supports proper tree-shaking by using lightweight injection tokens.
+
+The lightweight injection token design pattern is especially important for library developers. It ensures that when an application uses only some of your library's capabilities, the unused code can be eliminated from the client's app bundle.
+
+When an application uses your library, there might be some services that your library supplies which the client app doesn't use.
+In this case, the app developer should expect that service to be tree-shaken, and not contribute to the size of the compiled app.
+Because the application developer cannot know about or remedy a tree-shaking problem in the library, it is the responsibility of the library developer to do so.
+To prevent the retention of unused components, your library should use the lightweight injection token design pattern.
+
+## When tokens are retained
+
+To better explain the condition under which token retention occurs, consider a library that provides a library-card component, which contains a body and can contain an optional header.
+
+```
+<lib-card>
+  <lib-header>...</lib-header>
+</lib-card>
+```
+
+In a likely implementation, the `<lib-card>` component uses `@ContentChild()` or `@ContentChildren()` to obtain `<lib-header>` and `<lib-body>`, as in the following.
+
+```
+@Component({
+  selector: 'lib-header',
+  ...,
+})
+class LibHeaderComponent {}
+
+@Component({
+  selector: 'lib-card',
+  ...,
+})
+class LibCardComponent {
+  @ContentChild(LibHeaderComponent)
+  header: LibHeaderComponent|null = null;
+}
+```
+
+Because `<lib-header>` is optional, the element can appear in the template in its minimal form,
+`<lib-card></lib-card>`.
+In this case, `<lib-header>` is not used and you would expect it to be tree-shaken, but that is not what happens.
+This is because `LibCardComponent` actually contains two references to the `LibHeaderComponent`.
+
+`@ContentChild(LibHeaderComponent) header: LibHeaderComponent;`
+
+* One of these reference is in the *type position*-- that is, it specifies `LibHeaderComponent` as a type: `header: LibHeaderComponent;`.
+
+* The other reference is in the *value position*-- that is, LibHeaderComponent is the value of the `@ContentChild()` parameter decorator: `@ContentChild(LibHeaderComponent)`.
+
+The compiler handles token references in these positions differently.
+
+* The compiler erases *type position* references after conversion from TypeScript, so they have no impact on tree-shaking.
+
+* The compiler must retain *value position*  references at runtime, which prevents the component from being tree-shaken.
+
+In the example, the compiler retains the `LibHeaderComponent` token that occurs in the value position, which prevents the referenced component from being tree-shaken, even if the application developer does not actually use `<lib-header>` anywhere.
+If `LibHeaderComponent` is large (code, template, and styles), including it unnecessarily can significantly increase the size of the client application.
+
+## When to use the lightweight injection token pattern
+
+The tree-shaking problem arises when a component is used as an injection token.
+There are two cases when that can happen.
+
+* The token is used in the value position of a [content query](guide/lifecycle-hooks#using-aftercontent-hooks "See more about using content queries.").
+* The token is used as a type specifier for constructor injection.
+
+In the following example, both uses of the `OtherComponent` token cause retention of `OtherComponent` (that is, prevent it from being tree-shaken when it is not used).
+
+```
+class MyComponent {
+  constructor(@Optional() other: OtherComponent) {}
+
+  @ContentChild(OtherComponent)
+  other: OtherComponent|null;
+}
+```
+
+Although tokens used only as type specifiers are removed when converted to JavaScript, all tokens used for dependency injection are needed at runtime.
+These effectively change `constructor(@Optional() other: OtherComponent)` to `constructor(@Optional() @Inject(OtherComponent) other)`. The token is now in a value position, and causes the tree shaker to retain the reference.
+
+<div class="alert is helpful">
+
+For all services, a library should use [tree-shakable providers](guide/dependency-injection-providers#tree-shakable-providers), providing dependencies at the root level rather than in component constructors.
+
+</div>
+
+## Using lightweight injection tokens
+
+The lightweight injection token design pattern consists of using a small abstract class as an injection token, and providing the actual implementation at a later stage.
+The abstract class is retained (not tree-shaken), but it is small and has no material impact on the application size.
+
+The following example shows how this works for the `LibHeaderComponent`.
+
+```
+abstract class LibHeaderToken {}
+
+@Component({
+  selector: 'lib-header',
+  providers: [
+    {provide: LibHeaderToken, useExisting: LibHeaderComponent}
+  ]
+  ...,
+})
+class LibHeaderComponent extends LibHeaderToken {}
+
+@Component({
+  selector: 'lib-card',
+  ...,
+})
+class LibCardComponent {
+  @ContentChild(LibHeaderToken) header: LibHeaderToken|null = null;
+}
+```
+
+In this example, the `LibCardComponent` implementation no longer refers to `LibHeaderComponent` in either the type position or the value position.
+This allows full tree shaking of `LibHeaderComponent` to take place.
+The `LibHeaderToken` is retained, but it is only a class declaration, with no concrete implementation. It is small and does not materially impact the application size when retained after compilation.
+
+Instead, `LibHeaderComponent` itself implements the abstract `LibHeaderToken` class. You can safely use that token as the provider in the component definition, allowing Angular to correctly inject the concrete type.
+
+To summarize, the lightweight injection token pattern consists of the following.
+
+1. A lightweight injection token that is represented as an abstract class.
+2. A component definition that implements the abstract class.
+3. Injection of the lightweight pattern, using ` @ContentChild()` or `@ContentChildren()`.
+4. A provider in the implementation of the lightweight injection token which associates the lightweight injection token with the implementation.
+
+### Use the lightweight injection token for API definition
+
+A component that injects a lightweight injection token might need to invoke a method in the injected class.
+Because the token is now an abstract class, and the injectable component implements that class, you must also declare an abstract method in the abstract lightweight injection token class.
+The implementation of the method (with all of its code overhead) resides in the injectable component that can be tree-shaken.
+This allows the parent to communicate with the child (if it is present) in a type-safe manner.
+
+For example, the `LibCardComponent` now queries`LibHeaderToken` rather than `LibHeaderComponent`.
+The following example shows how the pattern allows `LibCardComponent` to communicate with the `LibHeaderComponent` without actually referring to `LibHeaderComponent`.
+
+```
+abstract class LibHeaderToken {
+  abstract doSomething(): void;
+}
+
+@Component({
+  selector: 'lib-header',
+  providers: [
+    {provide: LibHeaderToken, useExisting: LibHeader}
+  ]
+  ...,
+})
+class LibHeaderComponent extends LibHeaderToken {
+  doSomething(): void {
+    // Concrete implementation of `doSomething`
+  }
+}
+
+@Component({
+  selector: 'lib-card',
+  ...,
+})
+class LibCardComponent implement AfterContentInit {
+  @ContentChild(LibHeaderToken)
+  header: LibHeaderToken|null = null;
+
+  ngAfterContentInit(): void {
+    this.header && this.header.doSomething();
+  }
+}
+```
+
+In this example the parent  queries the token to obtain the child component, and stores the resulting component reference if it is present.
+Before calling a method in the child, the parent component checks to see if the child component is present.
+If the child component has been tree-shaken, there is no runtime reference to it, and no call to its method.
+
+### Naming your lightweight injection token
+
+Lightweight injection tokens are only useful with components. The Angular style guide suggests that you name components using the "Component" suffix. The example "LibHeaderComponent" follows this convention.
+
+To maintain the relationship between the component and its token while still distinguishing between them, the recommended style is to use the component base name with the suffix "Token" to name your lightweight injection tokens: "LibHeaderToken".

aio/content/navigation.json

@@ -552,6 +552,11 @@
               "url": "guide/creating-libraries",
               "title": "Creating Libraries",
               "tooltip": "Extend Angular by creating, publishing, and using your own libraries."
+            },
+            {
+              "url": "guide/lightweight-injection-tokens",
+              "title": "Lightweight Injection Tokens for Libraries",
+              "tooltip": "Optimize client app size by designing library services with lightweight injection tokens."
             }
           ]
         },