Skip to main content
Version: v4.0

Support Policy

Community Maintenance

Stencil is a 100% open source (MIT) project. Developers can ensure Stencil is the right choice for building web components through Ionic’s community maintenance strategy. The Stencil team regularly ships new releases, bug fixes, and is welcoming to community pull requests.

Stencil Maintenance and Support Status

Given the reality of time and resource constraints as well as the desire to keep innovating in the frontend development space, over time it becomes necessary for the Stencil team to shift focus to newer versions of the library. However, the Stencil team will do everything it can to make the transition to newer versions as smooth as possible. The Stencil team recommends updating to the newest version of the Stencil for the latest features, improvements and stability updates.

The current status of each Stencil version is:

VersionStatusReleasedMaintenance EndsExt. Support Ends
V4ActiveJun 26, 2023TBDTBD
V3MaintenanceJan 25, 2023Dec 26, 2023Jun 26, 2024
V2MaintenanceAug 08, 2020Jul 25, 2023Jan 25, 2024
V1End of SupportJun 03, 2019Aug 08, 2020Aug 08, 2020

Maintenance Period: Only critical bug and security fixes. No major feature improvements.

Extended Support Period: Available to Stencil Enterprise customers.

Stencil Support Details

Starting with Stencil v2, the Stencil team is adopting a newly revised maintenance policy. When a new major version of Stencil is released, the previous major version release will enter maintenance mode. While a version of Stencil is in maintenance mode, only critical bug & security fixes will be applied to that version, and no major feature improvements will be added. The maintenance period shall last six months from the release of the new major version.

Once the maintenance period has ended for a version of Stencil, that version enters the extended support period. During the extended support period, only critical bug and security fixes will be applied for teams and organizations using Stencil's Enterprise offerings. The extended support period lasts for twelve months from the release of the new major version.

The table below describes a theoretical timeline of releases:

VersionStatusReleasedMaintenance EndsExt. Support Ends
DActiveJan 01, 2022TBDTBD
CMaintenanceJul 07, 2021Jul 01, 2022Jan 01, 2023
BExtended Support OnlyJan 01, 2021Jan 07, 2022Jul 07, 2022
AEnd of SupportJul 07, 2020Jul 01, 2021Jan 01, 2021

In the example above, when Version D is released, Version C enters maintenance mode. Version D was released on January 1st, 2022. Version C shall be in maintenance mode until July 1st, 2022, three months after the release of Version D. After July 1st 2022, Version C will be in extended support until Jun 1st, 2023, twelve months after the release of Version D.

Browser Support

Stencil builds Web Components that run natively in all widely used desktop and mobile browsers. Custom Elements are natively supported in Chrome, Edge, Firefox, and Safari (including iOS)!

Stencil supports the following browsers:

Stencil VersionChromeEdgeFirefoxSafariInternet ExplorerPre-Chromium Edge
V4v79+v79+v70+v14+
V3v79+v79+v70+v14+
V2v60+v79+v63+v10.1+

TypeScript Support

Stencil acts as a compiler for a project's web components, and works closely with the TypeScript compiler to transform TSX to vanilla JavaScript. To ensure compatibility between the two, Stencil takes an opinionated stance on which version of the TypeScript compiler must be used.

Stencil includes a recent copy of the TypeScript compiler in its distributable* to guarantee this compatibility. The Stencil team is committed to keeping its version of TypeScript up to date and, as of Stencil v2.10.0, attempts to be within one minor version of the latest TypeScript release.

The table below describes recent versions of Stencil and the version of TypeScript each version shipped with.

Stencil VersionTypeScript Version
v3.3.0v5.0.4
v3.0.0v4.9.4
v2.21.0v4.9.3
v2.20.0v4.8.4
v2.18.0v4.7.4
v2.14.0v4.5.4
v2.10.0v4.3.5
v2.5.0v4.2.3
v2.4.0v4.1.3
v2.2.0v4.0.5

The TypeScript team releases a new minor version of the TypeScript compiler approximately once every three months. To accomplish its goal of staying within one minor version of the latest release, Stencil will update its version of TypeScript once every three months as well. Updates to the version of TypeScript will often, but not always, occur in a minor version release of Stencil.

The Stencil team acknowledges that TypeScript minor version releases may contain breaking changes. The Stencil team will do everything in its power to avoid propagating breaking changes to its user base.

* The TypeScript compiler is never included in the output of your Stencil project, and is only used for compilation and type checking purposes.

Compatibility Recommendations

Stencil is in many regards an opinionated library, and includes much of the software necessary to get users building web components as quickly as possible. There are a few pieces of software that Stencil allows users to choose to best fit their team, organizational structure, and existing technical stack. The Stencil team has compiled a series of compatibility tables to describe the interoperability requirements of these pieces of software and Stencil.

JavaScript Runtime

Stencil VersionNode v10Node v12Node v14Node v16Node v18Node v20
V4
V3
V2
V1

Testing Libraries

Jest

Stencil VersionJest v24Jest v25Jest v26Jest v27Jest v28+ *
V4
V3
V2
V1

* Support for Jest 28+ will be released in an upcoming version of Stencil v4.

Puppeteer

Stencil VersionPuppeteer v5-9Puppeteer v10Puppeteer v11-21
V4
V3
V2
V1