Announcing Stencil 3

Today is the day, everyone! We’re thrilled to announce that Stencil v3.0 is officially here! We’ve been hard at work over the past few months to grow from Alpha to Beta RC and we’ve finally reached general availability. Along with the release of 3.0, the Stencil website and documentation have been updated with a brand new look and feel.

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

npm install @stencil/core@latest

If you’ve been following along since beta, simply upgrade to the latest stable release without any issues. For folks who have not, please follow the migration guide. Read on for more detail on the changes that have been made to Stencil.

Ch-ch-ch-Changes

Stencil generates standards-based Web Components that can be used to craft high quality component libraries, design systems, and applications. With APIs like Virtual DOM, JSX, and async rendering, fast, powerful components are easy to create, while still maintaining 100% compatibility with Web Components.

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 to reference while they update their component setups. The migration guide can be found here.

Docs and Design Update

To coincide with the major release, we’ve made significant improvements to the Stencil website and documentation. You’ll notice a fresh new design, as well as usability improvements in our docs like:

• Toggle between documentation for Stencil versions 2, 3, and Next
• Improved code snippet formatting and highlighting
• Migration to Docusaurus to align with our other docs sites

Let us know what you think of the update, and submit any issues or contributions to the docs on the GitHub repository.

What’s Next

With this GA release, we’ve reached the point where we feel confident in the features and improvements in Stencil 3. But if for some reason you run into any issues or have questions regarding the update, please let us know and open an issue on GitHub!