Stencil JS

Stencil is a compiler that generates Web Components and builds high-performance web applications. It operates across several distinct phases:

1. Build Time: Managed by the CLI and Compiler, which uses TypeScript, Rollup, and a Build Optimizer to transform source code into optimized bundles.
2. Development: Powered by a Dev Server featuring Hot Module Replacement (HMR) and a WebSocket server for real-time updates.
3. Runtime: A client-side runtime that manages the Virtual DOM, component lifecycles, and state reactivity in the browser.
4. Server Side: Supports Server-Side Rendering (SSR) and hydration via a Node.js rendering environment and a Mock Document implementation for DOM emulation.

The Stencil Compiler follows a modular architecture organized into four main layers:

1. Input Layer: Consumes configuration, source files, and assets.
2. Processing Layer: Includes the TypeScript Parser, AST Transformers, Rollup Bundler, and an Optimizer.
3. Output Layer: Uses Output Generators, a File Writer, and a Build Validator to produce the final artifacts.
4. Support Systems: Provides cross-cutting concerns like the Cache System, Worker Threads for parallel processing, and Diagnostics for error reporting.

Stencil components are lazy-loaded by default to reduce initial bundle size.

1. Registration: During bootstrap, Stencil registers a lightweight HostElement (extending HTMLElement) for each component using customElements.define. This host element acts as a placeholder.
2. Dynamic Import: When a HostElement is connected to the DOM, Stencil triggers a dynamic import() of the actual component bundle (e.g., ./build/[bundleId].js).
3. Activation: Once the module is loaded, the real component logic is instantiated and attached to the host element.

Stencil now automatically re-exports custom types for props and custom events from the project's components.d.ts file. This allows you to import these types directly from your library's entry point or the custom element output.

For example, if a component defines:

export type NameType = string;
export type Todo = Event;

@Component({ tag: 'my-component' })
export class MyComponent {
  @Prop() first: NameType;
  @Event() todoCompleted: EventEmitter<Todo>
}

You can now access them via:

import { NameType, Todo } from '@my-lib/types';

When testing components with the legacy runner, follow these patterns:

Lifecycle Methods

Verify that methods like componentWillLoad or componentDidLoad are called by checking state changes or flags within the component instance.

Custom Events

To test events, you can use standard Jest spies on the root element or use the spyOnEvent utility provided by the E2E runner.

// Lifecycle pattern
import { newSpecPage } from '@stencil/core/testing';

// ... component definition ...

const page = await newSpecPage({ components: [TestLifecycle], html: '<test-lifecycle></test-lifecycle>' });
expect(componentWillLoadCalled).toBe(true);

// Event pattern
const eventSpy = jest.fn();
page.root.addEventListener('myEvent', eventSpy);
page.rootInstance.emitEvent();
expect(eventSpy).toHaveBeenCalledWith(expect.objectContaining({ detail: { message: 'Hello' } }));

The Stencil Dev Server is designed for a fast development experience using a multi-process architecture. It separates the main process (CLI/Watch Task and Compiler) from the Server Process to ensure stability and performance.

Process Roles

• Main Process: Orchestrates the CLI, watch tasks, and the compiler. It communicates with the server process via Inter-Process Communication (IPC).
• Server Process: A separate Node.js process that hosts the HTTP server (for static files and requests) and a WebSocket server (for Hot Module Replacement).
• Browser (Client): The Dev Client runs in the browser, receiving updates via WebSockets to perform DOM updates, console forwarding, and error overlays without full page reloads.

Stencil's lazy loading mechanism ensures minimal initial payload by using a proxy-to-real-element upgrade pattern:

1. Proxy Generation: The compiler generates a lightweight proxy component for every component.
2. Registration: The proxy is registered with the Stencil runtime loader.
3. On-Demand Import: When the browser encounters the custom element tag, the loader triggers a dynamic import() for the actual component module.
4. Upgrade: Once the module loads, the component initializes and upgrades the existing proxy element into the real component instance.

Stencil components follow a specific lifecycle execution order to ensure parent-child relationships are respected during hydration.

1. componentWillLoad fires from top to bottom (parent to child).
2. componentDidLoad fires from bottom to top (child to parent).

Note that because components are lazy-loaded, they may finish loading in a random order. However, Stencil ensures the correct firing order by allowing componentWillLoad to return a Promise. All child components will wait for that promise to resolve before their own lifecycles proceed.

Example Execution Flow: For a hierarchy <cmp-a><cmp-b><cmp-c></cmp-c></cmp-b></cmp-a>:

• cmp-a - componentWillLoad (Top)
• cmp-b - componentWillLoad
• cmp-c - componentWillLoad
• cmp-c - componentDidLoad (Bottom)
• cmp-b - componentDidLoad
• cmp-a - componentDidLoad (Top)