Version: Next

Upgrading to Stencil v4.0.0

Getting Started

We recommend that you only upgrade to Stencil v4 from Stencil v3. If you're a few versions behind, we recommend upgrading one major version at a time (from v1 to v2, then v2 to v3, finally v3 to v4). This will minimize the number of breaking changes you have to deal with at the same time.

For breaking changes introduced in previous major versions of the library, see:

For projects that are on Stencil v3, install the latest version of Stencil v4: npm install @stencil/core@4

Updating Your Code

New Configuration Defaults

Starting with Stencil v4.0.0, the default configuration values have changed for a few configuration options. The following sections lay out the configuration options that have changed, their new default values, and ways to opt-out of the new behavior (if applicable).

`transformAliasedImportPaths`

TypeScript projects have the ability to specify a path aliases via the paths configuration in their tsconfig.json like so:

tsconfig.json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@utils": ["src/utils/index.ts"]
    }
  }
}

In the example above, "@utils" would be mapped to the string "src/utils/index.ts" when TypeScript performs type resolution. The TypeScript compiler does not however, transform these paths from their keys to their values as a part of its output. Instead, it relies on a bundler/loader to do the transformation.

The ability to transform path aliases was introduced in Stencil v3.1.0 as an opt-in feature. Previously, users had to explicitly enable this functionality in their stencil.config.ts file with transformAliasedImportPaths:

stencil.config.ts - enabling 'transformAliasedImportPaths' in Stencil v3.1.0
import { Config } from '@stencil/core';

export const config: Config = {
  transformAliasedImportPaths: true,
  // ...
};

Starting with Stencil v4.0.0, this feature is enabled by default. Projects that had previously enabled this functionality that are migrating from Stencil v3.1.0+ may safely remove the flag from their Stencil configuration file(s).

For users that run into issues with this new default, we encourage you to file a new issue on the Stencil GitHub repo. As a workaround, this flag can be set to false to disable the default functionality.

stencil.config.ts - disabling 'transformAliasedImportPaths' in Stencil v4.0.0
import { Config } from '@stencil/core';

export const config: Config = {
  transformAliasedImportPaths: false,
  // ...
};

For more information on this flag, please see the configuration documentation

`transformAliasedImportPathsInCollection`

Introduced in Stencil v2.18.0, transformAliasedImportPathsInCollection is a configuration flag on the dist output target. transformAliasedImportPathsInCollection transforms import paths, similar to transformAliasedImportPaths. This flag however, only enables the functionality of transformAliasedImportPaths for collection output targets.

Starting with Stencil v4.0.0, this flag is enabled by default. Projects that had previously enabled this functionality that are migrating from Stencil v2.18.0+ may safely remove the flag from their Stencil configuration file(s).

stencil.config.ts - disabling 'transformAliasedImportPathsInCollection' in Stencil v4.0.0
import { Config } from '@stencil/core';

export const config: Config = {
  outputTargets: [
    {
      type: 'dist',
      transformAliasedImportPathsInCollection: false,
    },
    // ...
  ]
  // ...
};

For more information on this flag, please see the dist output target's documentation.

In Browser Compilation Support Removed

Prior to Stencil v4.0.0, components could be compiled from TSX to JS in the browser. This feature was seldom used, and has been removed from Stencil. At this time, there is no replacement functionality. For additional details, please see the request-for-comment on the Stencil GitHub Discussions page.

Legacy Context and Connect APIs Removed

Previously, Stencil supported context and connect as options within the @Prop decorator. Both of these APIs were deprecated in Stencil v1 and are now removed.

@Prop({ context: 'config' }) config: Config;
@Prop({ connect: 'ion-menu-controller' }) lazyMenuCtrl: Lazy<MenuController>;

To migrate away from usages of context, please see the original deprecation announcement. To migrate away from usages of connect, please see the original deprecation announcement.

Legacy Browser Support Removed

In Stencil v3.0.0, we announced the deprecation of IE 11, pre-Chromium Edge, and Safari 10 support. In Stencil v4.0.0, support for these browsers has been dropped (for a full list of supported browsers, please see our Browser Support policy).

By dropping these browsers, a few configuration options are no longer valid in a Stencil configuration file:

`deprecatedcssVarsShim`

The extras.__deprecated__cssVarsShim option caused Stencil to include a polyfill for CSS variables. This field should be removed from a project's Stencil configuration file (stencil.config.ts).

`deprecateddynamicImportShim`

The extras.__deprecated__dynamicImportShim option caused Stencil to include a polyfill for the dynamic import() function for use at runtime. This field should be removed from a project's Stencil configuration file (stencil.config.ts).

`deprecatedsafari10`

The extras.__deprecated__safari10 option would patch ES module support for Safari 10. This field should be removed from a project's Stencil configuration file (stencil.config.ts).

`deprecatedshadowDomShim`

The extras.__deprecated__shadowDomShim option would check whether a shim for shadow DOM was needed in the current browser, and include one if so. This field should be removed from a project's Stencil configuration file (stencil.config.ts).

Legacy Cache Stats Config Flag Removed

The enableCacheStats flag was used in legacy behavior for caching, but has not been used for some time. This flag has been removed from Stencil's API and should be removed from a project's Stencil configuration file (stencil.config.ts).

Drop Node 14 Support

Stencil no longer supports Node 14. Please upgrade local development machines, continuous integration pipelines, etc. to use Node v16 or higher. For the full list of supported runtimes, please see our Support Policy.

Information Included in `docs-json` Expanded

For Stencil v4 the information included in the output of the docs-json output target was expanded to include more information about the types of properties and methods on Stencil components.

For more context on this change, see the documentation for the new supplementalPublicTypes option for the JSON documentation output target.

`JsonDocsEvent`

The JSON-formatted documentation for an @Event now includes a field called complexType which includes more information about the types referenced in the type declarations for that property.

Here's an example of what this looks like for the ionBreakpointDidChange event on the Modal component in Ionic Framework:

{
  "complexType": {
    "original": "ModalBreakpointChangeEventDetail",
    "resolved": "ModalBreakpointChangeEventDetail",
    "references": {
      "ModalBreakpointChangeEventDetail": {
        "location": "import",
        "path": "./modal-interface",
        "id": "src/components/modal/modal.tsx::ModalBreakpointChangeEventDetail"
      }
    }
  }
}

`JsonDocsMethod`

The JSON-formatted documentation for a @Method now includes a field called complexType which includes more information about the types referenced in the type declarations for that property.

Here's an example of what this looks like for the open method on the Select component in Ionic Framework:

{
  "complexType": {
    "signature": "(event?: UIEvent) => Promise<any>",
    "parameters": [
      {
        "tags": [
          {
            "name": "param",
            "text": "event The user interface event that called the open."
          }
        ],
        "text": "The user interface event that called the open."
      }
    ],
    "references": {
      "Promise": {
        "location": "global",
        "id": "global::Promise"
      },
      "UIEvent": {
        "location": "global",
        "id": "global::UIEvent"
      },
      "HTMLElement": {
        "location": "global",
        "id": "global::HTMLElement"
      }
    },
    "return": "Promise<any>"
  }
}

Additional Packages

To ensure the proper functioning of other @stencil/ packages, it is advisable for projects utilizing any of the packages mentioned below to upgrade to the minimum package version specified.

Package	Minimum Package Version	GitHub	Documentation
`@stencil/angular-output-target`	0.7.1	GitHub	Stencil Doc Site
`@stencil/sass`	3.0.4	GitHub	GitHub README
`@stencil/store`	2.0.8	GitHub	Stencil Doc Site
`@stencil/react-output-target`	0.5.1	GitHub	Stencil Doc Site
`@stencil/vue-output-target`	0.8.6	GitHub	Stencil Doc Site

Need Help Upgrading?

Be sure to look at the Stencil v4.0.0 Breaking Changes Guide.

If you need help upgrading, please post a thread on the Stencil Discord.

Upgrading to Stencil v4.0.0

Getting Started​

Updating Your Code​

New Configuration Defaults​

transformAliasedImportPaths​

transformAliasedImportPathsInCollection​

In Browser Compilation Support Removed​

Legacy Context and Connect APIs Removed​

Legacy Browser Support Removed​

__deprecated__cssVarsShim​

__deprecated__dynamicImportShim​

__deprecated__safari10​

__deprecated__shadowDomShim​

Legacy Cache Stats Config Flag Removed​

Drop Node 14 Support​

Information Included in docs-json Expanded​

JsonDocsEvent​

JsonDocsMethod​

Additional Packages​

Need Help Upgrading?​

Contents