December 19, 2022
  • Stencil
  • Design Systems
  • release
  • stencil

Announcing Stencil v3.0 Beta

Ryan Waskiewicz

Hey folks, hope you are all doing well around this time of the year. We’ve been hard at work over the past few months working on the next major version of Stencil, the web component compiler. Today, I’m thrilled to share that Stencil 3.0 Beta is available for testing in your component libraries. Let’s dive in a little bit and understand what has gone into this release.

To update to the latest version, you can simply install the latest version from npm:

npm install @stencil/core@v3-next

Then follow the migration guide to update your project. Let’s take a look at a few changes in this release to get a better understanding of why they were made.


One of the main goals of this major version is to create a new base for what we want Stencil to be in future releases. This means making a few breaking changes to keep up with the ecosystem. For example, we’ve dropped support for Node 12 and require at least Node 14.

In addition to this, we’ve also deprecated support for Safari 10 and IE 11. Any flags used to add support for older Safari and IE have been prepended with __deprecated__ and will be eventually removed in future major versions. These flags include:

  • __deprecated__dynamicImportShim
  • __deprecated__cssVarsShim
  • __deprecated__shadowDomShim
  • __deprecated__safari10

Following an RFC, the dist-custom-elements-bundle output target has been removed in 3.0. Users should migrate to the dist-custom-elements output target.

By default, dist-custom-elements does not automatically define all a project’s components with the CustomElementsRegistry. This allows for better treeshaking and smaller bundle sizes.

For teams that need to migrate quickly to dist-custom-elements, the following configuration should be close to a drop-in replacement for dist-custom-elements-bundle:

// stencil.config.ts

import { Config } from '@stencil/core';

export const config: Config = {
  outputTargets: [
-    {
-      type: 'dist-custom-elements-bundle',
-      // additional configuration
-    },
+    {
+      type: 'dist-custom-elements',
+      customElementsExportBehavior: 'bundle'
+    },
    // ...
  // ...

There are a lot more changes in Stencil 3.0 that folks should be aware of, and we’ve created a full migration guide for folks to reference while they update their component setups. The migration guide can be found here.

Team Updates

Part of the planning process for this major release has also been rebuilding the Stencil team and understanding the intricacies of the Stencil compiler. With this newer version of the team, we’ve spent a lot of time understanding how the compiler works, and sharing the knowledge of the internals amongst the team. This way, the team can move forward making changes with confidence and the knowledge of how Stencil works is not limited to a single person. This has let us have a deeper understanding of the entire compiler and be prepared for new people to join the team.

What’s Next

With this beta, we’re signaling to the community that we’re ready for you all to begin testing this release and to file bug reports. We do understand that given the time frame and holiday season, not everyone will be able to test against their production setup, so we expect beta to last a bit longer than usual. If you happen to run into any issues, or have any questions regarding the update, please let us know and open an issue on GitHub!

Ryan Waskiewicz