Here’s Exactly How I Implemented @defer for Granular Code Splitting in Days — Step-by-Step

Source: Dev.to

@defer Fundamentals and Setup

Angular’s @defer block is a game‑changer for performance, letting you split heavy template sections—like charts or dashboards—into separate JavaScript bundles that load only when triggered by events such as viewport entry, user interaction, or browser idle time. This slashes your initial payload, speeding up Largest Contentful Paint (LCP) and overall app startup, especially in large single‑page apps where not every user needs every feature right away.

Requirements for Success

• Angular v17 or later (stable deferrable views from Angular 18 onward).
• Components, directives, and pipes inside an @defer block must be standalone and not referenced elsewhere in the same file (e.g., no ViewChild queries or external imports that would cause eager loading).
• Transitive dependencies can be a mix of standalone or NgModule‑based, but keep placeholders lightweight since their dependencies load upfront.

Basic Syntax in Action

@defer (on viewport) {
  
}
@placeholder {
  
}

• Triggers: idle (default), interaction, hover, timer(2s), or a custom when showLargeChart.
• Loading indicator: @loading (minimum 1s) { }
• Error handling: @error { Retry? }
• Prefetch: prefetch on idle loads the bundle early without rendering it.

Verify Your Build Wins

1. Run ng build and look for new chunks such as defer-heavy-chart.js.
2. Serve the app, open Chrome DevTools → Network, and confirm that the heavy bundle loads only when the trigger fires.
3. For unit tests, you can simulate defer states with:

TestBed.deferBlockBehavior = DeferBlockBehavior.Manual;

Real‑World Starter: Dashboard Magic

@defer (on viewport; prefetch on idle) {
  
}
@placeholder (minimum 500ms) {
  
}

Wrapping a data‑heavy dashboard widget this way can shrink the main bundle by 30 %+ on complex pages, delivering a smooth experience for below‑the‑fold metrics.

Core Triggers and Sub‑Blocks

Multiple triggers can be combined with semicolons (OR logic). Prefetching is specified separately, e.g.:

@defer (on viewport; prefetch on idle) { ... }

Sub‑Blocks for Seamless UX

• @placeholder – Eagerly loaded, lightweight content shown before the deferred bundle. Use minimum 500ms to avoid flicker.
• @loading – Shown after the trigger fires, before the bundle resolves. Parameters like after 100ms; minimum 1s control timing.
• @error – Displays a fallback UI if the load fails. Wrap these blocks in a container with aria-live="polite" for screen‑reader announcements.

@defer (on hover) {
  
}
@placeholder {  }
@loading {  }
@error {  }

Custom Triggers with when

Use when for bespoke logic:

@defer (when isVisible()) {
  
}

when evaluates a signal or expression once; it does not revert. You can also combine with prefetch:

@defer (when userClicked(); prefetch when dataReady) { ... }

Advanced Patterns and Optimization

Nested @defer and Cascading Avoidance

Nested defer blocks enable layered lazy loading, but improper stacking can cause multiple bundles to fire simultaneously. Stagger triggers to avoid cascading requests:

@defer (on viewport) {
  @defer (on interaction) {
    
  } @placeholder {
    Click to expand
  }
} @placeholder {
  Scroll to see more
}
@if (isExpanded) {
  
}

• Outer block uses viewport to load only when the section scrolls into view.
• Inner block waits for an explicit interaction, preventing a burst of network requests.

SSR/SSG and Hydration Magic

• On the server, only @placeholder content (or nothing) is rendered; triggers are ignored because there is no viewport or idle state.
• During client‑side hydration, configured triggers fire, making the UI interactive.
• Enable incremental hydration with hydrate on triggers for SEO‑friendly server rendering without inflating client bundles. Pair with prefetch on idle to preload code before hydration.

Bundle Analysis and HMR Pitfalls

1. Install the explorer: npm i -D source-map-explorer.
2. Build with source maps: ng build --source-map.
3. Run the analysis:

npx source-map-explorer dist/**/main.js

The interactive treemap shows how main bundles shrink as heavy standalone components split off.

HMR note: Development servers eager‑load all @defer chunks, bypassing triggers. Disable HMR for accurate testing:

ng serve --no-hmr

Visual Example

Accessibility with ARIA Live Regions

Screen readers may miss the transition from placeholder to loaded content. Wrap defer blocks in a container with ARIA live attributes:

@defer (on hover) {  }
@placeholder {  }
@loading {  }
@error {  }

This ensures that dynamic content changes are announced automatically, keeping the UI both performant and inclusive.