docs: rework programmatically rendering components section to mention @defer (#61763)

carolruo · AndrewKushnir · commit 78910a32effd · 2025-06-10T12:01:30.000-07:00
PR Close #61763
diff --git a/adev/src/content/guide/components/programmatic-rendering.md b/adev/src/content/guide/components/programmatic-rendering.md
@@ -2,9 +2,17 @@
 
 TIP: This guide assumes you've already read the [Essentials Guide](essentials). Read that first if you're new to Angular.
 
-In addition to using a component directly in a template, you can also dynamically render components.
-There are two main ways to dynamically render a component: in a template with `NgComponentOutlet`,
-or in your TypeScript code with `ViewContainerRef`.
+In addition to using a component directly in a template, you can also dynamically render components 
+programmatically. This is helpful for situations when a component is unknown initially (thus can not 
+be referenced in a template directly) and it depends on some conditions.
+
+There are two main ways to render a component programmatically: in a template using `NgComponentOutlet`,
+or in your TypeScript code using `ViewContainerRef`. 
+
+HELPFUL: for lazy-loading use-cases (for example if you want to delay loading of a heavy component), consider 
+using the built-in [`@defer` feature](/guide/templates/defer) instead. The `@defer` feature allows the code 
+of any components, directives, and pipes inside the `@defer` block to be extracted into separate JavaScript 
+chunks automatically and loaded only when necessary, based on the configured triggers.
 
 ## Using NgComponentOutlet
 
@@ -95,9 +103,11 @@ In the example above, clicking the "Load content" button results in the followin
 
 ## Lazy-loading components
 
-You can use both of the approaches described above, `NgComponentOutlet` and `ViewContainerRef`, to
-render components that are lazy-loaded with a standard
-JavaScript [dynamic import](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Operators/import).
+HELPFUL: if you want to lazy-load some components, you may consider using the built-in [`@defer` feature](/guide/templates/defer) 
+instead.
+
+If your use-case is not covered by the `@defer` feature, you can use either `NgComponentOutlet` or 
+`ViewContainerRef` with a standard JavaScript [dynamic import](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Operators/import).
 
 ```angular-ts
 @Component({
diff --git a/packages/core/src/render3/component.ts b/packages/core/src/render3/component.ts
@@ -60,7 +60,7 @@ import {assertComponentDef} from './errors';
  * applicationRef.attachView(componentRef.hostView);
  * componentRef.changeDetectorRef.detectChanges();
  * ```
- *
+ * 
  * @param component Component class reference.
  * @param options Set of options to use:
  *  * `environmentInjector`: An `EnvironmentInjector` instance to be used for the component.
