StencilJS @Load Lazy Loading Guide

Learn how to split your StencilJS bundle at runtime using @Load, see a working parent‑child example, and verify the impact on initial load size and network behavior.

Problem: Large initial JavaScript bundle delays interactivity

When a StencilJS application bundles all components into a single www/build/app.js file, users must download and parse code for components that may never be viewed on the first screen. This inflates the initial payload and can increase time‑to‑interactive (TTI), especially on slower connections.

Takeaway: Use @Load to defer a component until it is needed

The @Load() decorator tells the Stencil compiler to treat the decorated method as a dynamic import point. The returned promise loads the child component’s module only when the promise resolves, creating a separate lazy chunk. The parent can render a fallback UI while waiting, then display the child component once the promise fulfills.

How @Load works – mechanism overview

Declare a method (or property) decorated with @Load() in the parent component.
The method returns a promise that imports the child component’s class via import().
Stencil splits the imported module into its own JavaScript chunk named after the child’s tag.
In the render method, conditionally render the child tag only after the promise resolves (e.g., by storing the loader in a state variable).
While the promise is pending, show a fallback such as a spinner or placeholder.

Worked example: Lazy‑loading a detail panel

Assume we have a parent component my-app that shows a button. Clicking the button should reveal a my-detail component that is not needed for the initial view.

Parent component (my-app.tsx)

import { Component, h, State, Load } from '@stencil/core';\n\n@Component({\n  tag: 'my-app',\n  styleUrl: 'my-app.css',\n})\nexport class MyApp {\n  @State() detailLoader: any = undefined;\n\n  // @Load marks this method as a split point\n  @Load()\n  async loadDetail() {\n    // The dynamic import creates a separate chunk\n    const module = await import('./my-detail');\n    return module.MyDetail;\n  }\n\n  handleClick = async () => {\n    // Trigger the loader; store the resolved class\n    this.detailLoader = await this.loadDetail();\n  }\n\n  render() {\n    return [\n      Show details,\n      // Fallback while loading\n      this.detailLoader === undefined ?\n        Click the button to load details :\n        // Once resolved, render the lazy component\n        \n    ];\n  }\n}\n

Child component (my-detail.tsx)

import { Component, h } from '@stencil/core';\n\n@Component({\n  tag: 'my-detail',\n  styleUrl: 'my-detail.css',\n})\nexport class MyDetail {\n  render() {\n    return (\n      \n        Detail Panel
\n        This content is loaded lazily.
\n      \n    );\n  }\n}\n

Verifying the lazy chunk

After writing the example, run a production build and inspect the output:

Build: Run npm run build (or yarn build) in the project root. No special permissions are needed beyond normal npm access.
Check generated files: Open www/build. You should see:\n
- app.js – the main bundle containing my-app and shared code.
- my-detail.js – a separate chunk named after the lazy‑loaded tag.
\n
Bundle size comparison: Run npm run build -- --verbose. The console prints the size of each chunk. Verify that app.js is smaller after adding @Load() compared to a build where my-detail is imported statically.
Runtime network check:\n
1. Open the page in Chrome.
2. Open DevTools → Network tab.
3. Set throttling to “Slow 3G” (or use a real slow connection).
4. Reload the page. Observe that only app.js (and possibly CSS) loads initially.
5. Click the “Show details” button.
6. Watch for a subsequent request to my-detail.js appearing after the click.
7. Ensure the fallback text (“Click the button to load details”) is replaced by the detail panel once the request finishes.
\n

Limitations and common mistakes

Tag string must be correct: The lazy loader resolves to a component class; if the tag name used in the template (<my-detail>) does not match the component’s @Component({ tag: 'my-detail' }) definition, Stencil throws a runtime error and the fallback never appears.
Path correctness: The dynamic import path (import('./my-detail')) is relative to the parent component’s file. Moving files without updating the path breaks the lazy load.
Over‑splitting: Applying @Load() to many small components can create numerous tiny chunks, leading to a waterfall of requests that may offset the initial‑size gain. Reserve lazy loading for components that are genuinely off the critical path (e.g., modals, tabs, low‑priority widgets).
Missing fallback: If you render the child tag directly without awaiting the loader, Stencil will attempt to instantiate the component before the module is fetched, resulting in a blank placeholder or error. Always guard rendering with a check for the resolved loader (or use async/await in render with await this.detailLoader and a loading state).
Server‑side rendering (SSR) considerations: Stencil’s prerendering does not wait for lazy imports; the lazy component will not be included in the static HTML. Ensure that lazy‑loaded content is acceptable to be client‑only, or provide a server‑rendered fallback.

Practical verification checklist

Run npm run build and confirm a separate chunk file for each @Load()‑ed component.
Compare main bundle size before and after adding the decorator (verbose build output).
In DevTools Network tab, verify that the lazy chunk loads only after the user interaction that triggers the loader.
Check that the fallback UI is shown while the chunk is loading and replaced by the actual component once loading completes.
Ensure no console errors about missing tags or failed imports.

By following the steps above, you can confidently use StencilJS’s @Load() decorator to split code, reduce initial payload, and improve perceived performance while being aware of the pitfalls that can undermine the benefit.

Lazy‑Loading StencilJS Components with the @Load Decorator