Version: Next

Upgrading to Stencil v4.0.0

caution

Stencil 4.0.0 is pre-release software. These instructions are for users looking to try an early version of the software

Getting Started

It's recommended that your projects start their upgrade from Stencil v3. Projects using Stencil v0 or Stencil v1 should upgrade to Stencil v2 before proceeding with upgrading to Stencil v3. Projects using Stencil v2 should upgrade to Stencil v3 before proceeding with this guide. For breaking changes introduced in previous major versions of the library, see:

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

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.

Additional Packages

In order to guarantee that other @stencil/ packages will continue to function as expected, it's recommended that a project that uses any of the packages listed below updates to the listed minimum package version.

Package	Minimum Package Version	GitHub	Documentation
`@stencil-angular-output-target`	0.5.0	GitHub	Stencil Doc Site
`@stencil/sass`	2.0.3	GitHub	GitHub README
`@stencil/store`	2.0.0	GitHub	Stencil Doc Site
`@stencil-react-output-target`	0.4.0	GitHub	Stencil Doc Site
`@stencil-vue-output-target`	0.7.0	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​

Additional Packages​

Need Help Upgrading?​