Stencil Documentation

Stencil is a compiler that generates standards-compliant Web Components (specifically Custom Elements). It combines TypeScript, JSX, and CSS to create high-quality component libraries.

Key features include:

• Framework Compatibility: Components work with popular frameworks out of the box. Stencil can also generate framework-specific wrappers to provide a native developer experience for specific frameworks.
• Enhanced Web Component APIs: Provides convenient APIs that simplify writing components compared to using the raw Custom Elements APIs directly.
• Performance & DX: Uses a Virtual DOM, JSX, and async rendering for speed. It includes built-in capabilities like prerendering and support for objects-as-properties (rather than just strings).
• Developer Experience: Includes a built-in dev server with live reload.

Stencil is a developer-focused toolchain designed for building reusable, scalable component libraries. It uses a compiler to generate highly optimized, standards-compliant Web Components.

Key capabilities include:

• Framework Agnosticism: Components work with many popular frameworks (Angular, React, Vue) out of the box or can be used as standalone Web Components.
• Optimized Runtime: The compiler performs static analysis to include only the necessary APIs for each component, minimizing bundle size.
• Advanced Web Component Features: Provides features like Virtual DOM, JSX, async rendering, prerendering, and the ability to pass complex objects/arrays as properties (not just strings).
• Lazy Loading: Components are lazy-loaded by default to reduce application startup times and improve distribution.

Stencil includes an integrated dev server that coordinates with the compiler to provide an enhanced development experience. It supports Hot Module Replacement (HMR) to update components and logic without losing browser state, and Style Replacement to dynamically update CSS (including styles within Shadow DOM) without a page refresh.

When errors occur, Stencil overlays the error on the app in the browser. These error overlays include clickable line numbers that can open the source file directly in your IDE.

A Design System is a collection of UI components and a defined visual style, released as both code implementations and design artifacts. It is composed of four key pillars:

• Components: Standalone, reusable UI elements (e.g., buttons, links, forms, modals) that act as building blocks for user experiences.
• Patterns: Opinionated combinations of components used to create standardized user experiences (e.g., data capture forms, filtering workflows).
• Visual Language: The defined visual style, including colors (primary, secondary, tertiary), typography, and icons.
• Design Artifacts and Code Implementations: Design artifacts represent UI workflows, serving as the guidance for developers to implement the design in code.

For greater styling flexibility, use the part attribute on elements within your component. This exposes those elements to the light DOM via the ::part() pseudo-element. This allows consumers to apply any CSS properties (not just variables) to the specific element.

// Inside component render
<h1 part="heading">{this.heading}</h1>

/* Inside consumer CSS */
shadow-card::part(heading) {
  text-transform: uppercase;
}

When building components for SSR, avoid passing complex data structures (like objects) that rely on function calls to generate them. While Stencil supports serializing complex objects, it cannot resolve the value of function calls (e.g., items={generateMenuData()}) during the SSR process (except when using runtime-based SSR within Next.js applications).

Recommendation: Do not depend on external data structures or function-generated objects for rendering Stencil components during SSR. Use primitive values where possible to ensure reliable serialization.

Stencil automatically generates TypeScript declaration files (src/component.d.ts) during the compilation process. These declarations provide strong typing for consuming components, enabling:

• Property Validation: Ensures proper values are passed to component properties.
• IDE Autocompletion: Provides code completion in modern editors like VSCode.
• Event Details: Provides type safety for the detail property in CustomEvents.
• Method Signatures: Provides correct types for component methods.

These types support both strong typing in JSX (similar to React) and HTMLElement interfaces for vanilla JavaScript usage.

Unlike many other tools, Stencil does not use Puppeteer or jsdom for prerendering.

• Why not Puppeteer? While excellent for E2E testing, it is too slow for generating large websites with many pages.
• Why not jsdom? It can be difficult to use with asynchronous components and its global environment nature can cause issues.

The Stencil Way: Stencil uses its own internal DOM APIs that strictly follow web standards but are optimized for Node.js environments. This allows developers to use the same standard Web APIs they use for client-side components, ensuring that code written for the browser works seamlessly during the prerendering process without requiring specialized APIs or different coding patterns.

Stencil acts as a compiler that transforms TSX to vanilla JavaScript. To ensure compatibility, Stencil ships with a specific version of the TypeScript compiler included in its distributable.

Note: The TypeScript compiler is used only for compilation and type checking; it is not included in the final output of your Stencil project.

Stencil aims to stay within one minor version of the latest TypeScript release, typically updating every three months.