diff --git a/aio/content/guide/lightweight-injection-tokens.md b/aio/content/guide/lightweight-injection-tokens.md index 66a621c741e6c..9269e622b574b 100644 --- a/aio/content/guide/lightweight-injection-tokens.md +++ b/aio/content/guide/lightweight-injection-tokens.md @@ -1,12 +1,12 @@ -# Optimizing client app size with lightweight injection tokens +# Optimizing client application 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/architecture-services#introduction-to-services-and-dependency-injection). -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. +This normally ensures that if a provided component or service is never actually used by the application, the compiler can remove 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. +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. @@ -19,7 +19,7 @@ To prevent the retention of unused components, your library should use the light ## 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. +To better explain the condition under which token retention occurs, consider a library that provides a library-card component. This component contains a body and can contain an optional header. @@ -29,7 +29,7 @@ To better explain the condition under which token retention occurs, consider a l -In a likely implementation, the `` component uses `@ContentChild()` or `@ContentChildren()` to obtain `` and ``, as in the following. +In a likely implementation, the `` component uses `@ContentChild()` or `@ContentChildren()` to get `` and ``, as in the following. @@ -68,10 +68,10 @@ 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. +* The compiler must keep *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 `` anywhere. -If `LibHeaderComponent` is large \(code, template, and styles\), including it unnecessarily can significantly increase the size of the client application. +In the example, the compiler retains the `LibHeaderComponent` token that occurs in the value position. This prevents the referenced component from being tree-shaken, even if the application developer does not actually use `` anywhere. +If `LibHeaderComponent` 's code, template, and styles combined becomes too large, including it unnecessarily can significantly increase the size of the client application. ## When to use the lightweight injection token pattern @@ -81,7 +81,7 @@ 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\). +In the following example, both uses of the `OtherComponent` token cause retention of `OtherComponent`, preventing it from being tree-shaken when it is not used. @@ -96,7 +96,7 @@ class MyComponent { 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. +The token is now in a value position, and causes the tree shaker to keep the reference.
@@ -107,7 +107,7 @@ For all services, a library should use [tree-shakable providers](guide/architect ## 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 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`. @@ -152,9 +152,9 @@ To summarize, the lightweight injection token pattern consists of the following. ### 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 lets the parent communicate with the child \(if it is present\) in a type-safe manner. +The token is now an abstract class. Since 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 its code overhead, resides in the injectable component that can be tree-shaken. +This lets the parent 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 lets `LibCardComponent` communicate with the `LibHeaderComponent` without actually referring to `LibHeaderComponent`. @@ -193,7 +193,7 @@ class LibCardComponent implement AfterContentInit { -In this example the parent queries the token to obtain the child component, and stores the resulting component reference if it is present. +In this example the parent queries the token to get 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. @@ -203,7 +203,7 @@ 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`". +You should 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`."