Architectural note: Lazy loading and hydration in StencilJS for smaller bundles and faster TTI

Problem: Large initial JavaScript bundle delays interactivity

When a StencilJS application bundles all components into a single file, the first paint may show server‑rendered HTML but the page stays unresponsive until the whole bundle downloads, parses and executes. This increases Time to Interactive (TTI) and hurts metrics on slower connections.

Takeaway

Enable Stencil’s compiler‑driven lazy loading and hydration so each component is shipped as its own chunk, loaded only when its custom element appears in the DOM, while server‑rendered markup becomes interactive without a full re‑render.

Requirements

• StencilJS v2.x or later (compiler supports lazy loading).
• Server‑side rendering (SSR) enabled to deliver initial HTML.
• Build pipeline that can emit multiple chunks (default Stencil build).
• Ability to edit stencil.config.ts and run the build command.

Smallest suitable design

1. Mark each component that is not needed on the initial view with @Component({ lazy: true }).
2. Keep only the components required for the above‑the‑fold UI in the eager bundle (either omit lazy or set lazy: false).
3. Ensure the component’s tag is present in the server‑rendered HTML so the browser can instantiate it later.
4. Let Stencil’s compiler generate a separate chunk file for each lazy component (named [component-name].js by default).

Trust / data boundaries

Stencil uses Shadow DOM to encapsulate each component’s style and markup, preventing CSS from leaking out or global styles from unintentionally affecting the component’s internal DOM. This creates a clear trust boundary:

• Component’s internal DOM and styles are private.
• Communication with the parent happens only through public properties, methods, or events declared in the component’s API.
• Global theme values can be passed in via CSS Custom Properties, which cross the shadow boundary deliberately.

Operational checks

1. After building, open the dist folder and verify that alongside the main bundle (main.js) there are separate files such as my-lazy-component.js.
2. Run the application (npm start or stencil dev --serve) and open Chrome DevTools → Network. Filter by JS and interact with the page to trigger the lazy component; you should see a request for its chunk appear only after the interaction.
3. Disable JavaScript in the browser, reload the page, and confirm that the server‑rendered HTML is still visible (no blank screen). Re‑enable JS and observe the hydrated class being added to the host element, indicating hydration completed.
4. Inspect the host element in the Elements pane; after hydration you should see a class attribute containing hydrated (added by Stencil) and no duplicate markup.

Failure modes and conditions that would change the design

• Flash of Unstyled Content (FOUC) – If the component’s CSS is not inlined or delivered with the initial HTML, the element may appear unstyled before its chunk loads. Mitigation: include critical CSS in the SSR output or set devTools: false and rely on Stencil’s automatic CSS injection.
• Layout shift – Hydration can modify the DOM size if server‑rendered markup differs from the client‑generated tree (e.g., due to conditional rendering based on browser‑only APIs). Keep server and client render identical for lazy components, or use hydrateSlot to preserve existing nodes.
• Excessive HTTP requests – Splitting too many tiny components can increase round‑trip overhead, especially on HTTP/1.1. Monitor the number of chunk requests in the Network tab; if > 20‑30 requests noticeably delay TTI, consider bundling a group of related lazy components using stencil-build’s devTools flag or a custom rollup config.
• Shadow DOM theming – Global variables defined outside the shadow root do not pierce the boundary. If a design system relies on cascading variables, expose them through CSS Custom Properties on the host (:host { --theme-color: var(--global-primary); }) and consume them inside the component.

Practical verification checklist

1. Build: npm run build (requires read/write access to project directory).
2. Check output: ls dist/**/*.js should list main.js plus one file per lazy component.
3. Run dev server: npm start (or stencil dev --serve).
4. Open Chrome DevTools → Network → JS, enable ‘Disable cache’, reload, then interact to trigger lazy component; verify a new chunk request appears.
5. Disable JS, reload, confirm server‑rendered content visible.
6. Re‑enable JS, inspect host element for hydrated class.

If any of these checks fail, revisit the lazy flag, ensure the component is actually used in the SSR template, and verify that Stencil’s compiler version supports lazy loading (v2.0+).