Stencil — Compiler for Building Fast Reusable Web Components

Introduction

Stencil is a compiler that generates standards-based web components from a TypeScript and JSX authoring experience. Created by the Ionic team, it combines the developer experience of a modern framework with the output of vanilla custom elements that run natively in any browser. Stencil powers the Ionic Framework's component library.

What Stencil Does

• Compiles TypeScript + JSX source files into native Web Components
• Generates lazy-loading bundles with automatic code splitting per component
• Produces framework wrappers for React, Vue, and Angular from a single source
• Provides a built-in dev server with hot module replacement and docs generation
• Creates distributable component libraries with auto-generated readme files

Architecture Overview

Stencil acts as a build-time compiler rather than a runtime framework. It parses decorated TypeScript classes, generates an optimized virtual DOM renderer, and outputs standard custom elements with minimal runtime overhead. The compiler applies tree shaking, minification, and differential loading automatically. At runtime, the generated components register as native custom elements with shadow or scoped CSS encapsulation.

Self-Hosting & Configuration

• Initialize a project with npm init stencil and select a starter template
• Configure stencil.config.ts for output targets (dist, dist-custom-elements, www)
• Use the docs-readme output target to auto-generate markdown documentation
• Publish to npm as a standard package; consumers import elements directly
• Set up framework wrappers via official output target plugins for React, Vue, and Angular

Key Features

• Near-zero runtime: compiles away the framework, shipping only what each component needs
• Automatic lazy loading splits each component into its own chunk
• Server-side rendering support with hydration for fast first paint
• Built-in testing utilities with Jest and Puppeteer integration
• 12k+ GitHub stars, proven at scale by Ionic Framework and enterprise design systems

Comparison with Similar Tools

• Lit — also builds web components but is a runtime library; Stencil is a compile-time tool with JSX and auto-generated wrappers
• Svelte — compiles to vanilla JS but targets full apps; Stencil focuses on reusable component libraries
• React — requires React runtime in consumers; Stencil outputs framework-free custom elements
• Angular Elements — wraps Angular components as custom elements; Stencil produces smaller, faster output without Angular overhead

FAQ

Q: Do I need Ionic to use Stencil? A: No. Stencil is a standalone tool. Ionic uses Stencil internally, but you can use Stencil for any web component project.

Q: Can I use Stencil components in React? A: Yes. Stencil's React output target generates type-safe React wrapper components automatically.

Q: How small are the generated components? A: A typical Stencil component adds 2-5 KB gzipped to the bundle, including the minimal runtime.

Q: Does Stencil support server-side rendering? A: Yes. Stencil provides a hydrate module that renders components on the server and hydrates them on the client.

Sources

• https://github.com/ionic-team/stencil
• https://stenciljs.com/docs/introduction