Version: v2

Upgrading to Stencil v3.0.0

Getting Started

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

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

Updating Your Code

New Configuration Defaults

Starting with Stencil v3.0.0, the default configuration values have changed for a few properties.

SourceMaps

Sourcemaps are generated by default for all builds. Previously, sourcemaps had to be explicitly enabled by setting the sourceMap flag to true. To restore the old behavior, set the sourceMap flag to false in your project's stencil.config.ts:

// stencil.config.ts
import { Config } from '@stencil/core';

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

`dist-custom-elements` Type Declarations

Type declaration files (.d.ts files) are now generated by default for the dist-custom-elements output target. If your project is using dist-custom-elements and you do not wish to generate type declarations, the old behavior can be achieved by setting generateTypeDeclarations to false in the dist-custom-elements output target in your project's stencil.config.ts:

// stencil.config.ts
import { Config } from '@stencil/core';

export const config: Config = {
  outputTargets: [
    {
      type: 'dist-custom-elements',
      generateTypeDeclarations: false,
      // ...
    },
    // ...
  ],
  // ...
};

Legacy Browser Support Fields Deprecated

Several configuration options related to support for Safari <11, IE11, and Edge <19 have been marked as deprecated, and will be removed entirely in a future version of Stencil.

`dynamicImportShim`

The extras.dynamicImportShim option causes Stencil to include a polyfill for the dynamic import() function for use at runtime. The field is renamed to __deprecated__dynamicImportShim to indicate deprecation. To retain the previous behavior the new option can be set in your project's stencil.config.ts:

// stencil.config.ts
import { Config } from '@stencil/core';
export const config: Config = {
  extras: {
    __deprecated__dynamicImportShim: true
  }
};

`shadowDomShim`

If extras.shadowDomShim is set to true the Stencil runtime will check whether a shim for shadow DOM is needed in the current browser, and include one if so. For Stencil v3.0.0 this field is renamed to __deprecated__shadowDomShim. To retain the previous behavior the new option can be set in your project's stencil.config.ts:

// stencil.config.ts
import { Config } from '@stencil/core';
export const config: Config = {
  extras: {
    __deprecated__shadowDomShim: true
  }
};

`cssVarsShim`

extras.cssVarsShim causes Stencil to include a polyfill for CSS variables. For Stencil v3.0.0 this field is renamed to __deprecated__cssVarsShim. To retain the previous behavior the new option can be set in your project's stencil.config.ts:

// stencil.config.ts
import { Config } from '@stencil/core';
export const config: Config = {
  extras: {
    __deprecated__cssVarsShim: true
  }
};

`safari10`

If extras.safari10 is set to true the Stencil runtime will patch ES module support for Safari 10. For Stencil v3.0.0 this field is renamed to __deprecated__safari10. To retain the previous behavior the new option can be set in your project's stencil.config.ts:

// stencil.config.ts
import { Config } from '@stencil/core';
export const config: Config = {
  extras: {
    __deprecated__safari10: true
  }
};

Deprecated `assetsDir` Removed from `@Component()` decorator

The assetsDir field was deprecated in Stencil v2.0.0, but some backwards compatibility was retained with a warning message. It has been fully removed in Stencil v3.0.0 in favor of assetsDirs. To migrate from existing usages of assetsDir, update the property name and wrap its value in an array:

@Component({
  tag: 'my-component',
- assetsDir: 'assets',
+ assetsDirs: ['assets'],
})

For more information on the assetsDirs field, please see the Stencil Documentation on assetsDirs

Drop Node 12 Support

Stencil no longer supports Node 12. Please upgrade local development machines, continuous integration pipelines, etc. to use Node v14 or higher.

Strongly Typed Inputs

onInput and onInputCapture events have had their interface's updated to accept an argument of InputEvent over Event:

- onInput?: (event: Event) => void;
+ onInput?: (event: InputEvent) => void;
- onInputCapture?: (event: Event) => void;
+ onInputCapture?: (event: InputEvent) => void;

event arguments to either callback should be updated to take this narrower typing into account

Narrowed Typing for `autocapitalize` Attribute

The autocaptialize attribute has been narrowed from type any to type string. This change brings Stencil into closer alignment with TypeScript's typings for the attribute. No explicit changes are needed, unless a project was passing non-strings to the attribute.

Custom Types for Props and Events are now Exported from `components.d.ts`

Custom types for props and custom events are now re-exported from a project's components.d.ts file.

For the following Stencil component

import { Component, Event, EventEmitter, Prop, h } from '@stencil/core';

export type NameType = string;
export type Todo = Event;

@Component({
  tag: 'my-component',
  styleUrl: 'my-component.css',
  shadow: true,
})
export class MyComponent {
  @Prop() first: NameType;

  @Event() todoCompleted: EventEmitter<Todo>

  render() {
    return <div>Hello, World! I'm {this.first}</div>;
  }
}

The following data will now be included automatically in components.d.ts:

  import { HTMLStencilElement, JSXBase } from "@stencil/core/internal";
  import { NameType, Todo } from "./components/my-component/my-component";
+ export { NameType, Todo } from "./components/my-component/my-component";
  export namespace Components {
      interface MyComponent {
        "first": NameType;
      }
  }
  export interface MyComponentCustomEvent<T> extends CustomEvent<T> {
      detail: T;
      target: HTMLMyComponentElement;
  }
  declare global {
      interface HTMLMyComponentElement extends Components.MyComponent, HTMLStencilElement {
  }

This allows those types to be easily accessed from the root of the type distribution:

import { NameType, Todo } from '@my-lib/types';

When using dist-custom-elements, these types can now be accessed from the custom element output:

import { NameType, Todo } from '@my-custom-elements-output';

This may clash with any manually created types in existing Stencil projects. Projects that manually create type definitions from components.d.ts will either need to:

remove the manually created type (if the types generated in components.d.ts suffice)
update their type creation logic to account for potential naming collisions with the newly generated types

Composition Event Handlers Renamed

The names of Stencil's composition event handlers have been changed in order to correct a casing issue which prevented handlers from being called when events fired. The changes are as follows:

previous name	new name
`onCompositionEnd`	`onCompositionend`
`onCompositionEndCapture`	`onCompositionendCapture`
`onCompositionStart`	`onCompositionstart`
`onCompositionStartCapture`	`onCompositionstartCapture`
`onCompositionUpdate`	`onCompositionupdate`
`onCompositionUpdateCapture`	`onCompositionupdateCapture`

Output Targets

`dist-custom-elements` Output Target

Add `customElementsExportBehavior` to Control Export Behavior

customElementsExportBehavior is a new configuration option for the output target. It allows users to configure the export behavior of components that are compiled using the output target. By default, this output target will behave exactly as it did in Stencil v2.0.0.

This config option provides additional behaviors that will alter the default component export OR custom element definition behaviors for this target. The desired behavior can be set via the following in a project's Stencil config:

// stencil.config.ts
import { Config } from '@stencil/core';
export const config: Config = {
  outputTargets: [
    {
      type: 'dist-custom-elements',
      customElementsExportBehavior: 'default' | 'auto-define-custom-elements' | 'bundle' | 'single-export-module',
    },
    // ...
  ],
  // ...
};

Option	Description
`default`	No additional re-export or auto-definition behavior will be performed. This value will be used if no explicit value is set in the config, or if a given value is not a valid option.
`auto-define-custom-elements`	A component and its children will be automatically defined with the `CustomElementRegistry` when the component's module is imported.
`bundle`	A utility `defineCustomElements()` function is exported from the `index.js` file of the output directory. This function can be used to quickly define all Stencil components in a project on the custom elements registry.
`single-export-module`	All component and custom element definition helper functions will be exported from the `index.js` file in the output directory (see Defining Exported Custom Elements for more information on this file's purpose). This file can be used as the root module when distributing your component library, see below for more details.

note

This option also has an impact when using the Stencil framework integration output targets. Please see the framework integration migration section below for more information.

Move `autoDefineCustomElements` Configuration

autoDefineCustomElements was a configuration option to define a component and its children automatically with the CustomElementRegistry when the component's module is imported. This behavior has been merged into the customElementsExportBehavior configuration field. To continue to use this behavior, replace autoDefineCustomElements in your project's stencil.config.ts with the following:

// stencil.config.ts
import { Config } from '@stencil/core';

export const config: Config = {
  outputTargets: [
    {
      type: 'dist-custom-elements',
-      autoDefineCustomElements: true,
+      customElementsExportBehavior: 'auto-define-custom-elements',
      // ...
    },
    // ...
  ],
  // ...
};

Remove `inlineDynamicImports` Configuration

The inlineDynamicImports configuration option on dist-custom-elements has been removed. Previously, this option would throw an error at build time during the Rollup bundling process if the build contained multiple "inputs" (components).

`dist-custom-elements-bundle` Output Target

The dist-custom-elements-bundle has been removed starting with Stencil v3.0.0, following the RFC process. Users of this output target should migrate to the dist-custom-elements output target.

By default, dist-custom-elements does not automatically define all a project's component's 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'
+    },
    // ...
  ],
  // ...
};

However, it does not necessarily improve treeshaking/bundle size. For more information on configuring this output target, please see the dist-custom-elements documentation

Framework Integration Output Targets

Using `includeImportCustomElements`

The addition of the customElementsExportBehavior option on dist-custom-elements can also have an impact on the Stencil framework integration output targets if they are configured to use the output from dist-custom-elements (i.e. by setting includeImportCustomElements: true). If you encounter problems with the generated import statements in the component proxy files, setting customElementsExportBehavior: 'single-export-module' in the dist-custom-elements output target config should result in the same behavior as in Stencil V2. For example, a project using the Angular framework integration output target would have a config like:

// stencil.config.ts
import { Config } from '@stencil/core';
import { angularOutputTarget } from '@stencil/angular-output-target';

export const config: Config = {
  outputTargets: [
    angularOutputTarget({
      // Same config as V2
      includeImportCustomElements: true
    }),
    {
      type: 'dist-custom-elements',
      // This will create the same behavior as Stencil V2
      customElementsExportBehavior: 'single-export-module'
    }
  ]
}

Legacy Angular Output Target

Prior to the creation of the @stencil/angular-output-target, the 'angular' output target was the original means of connecting a Stencil component to an Angular application. This output target has been removed in favor of @stencil/angular-output-target. Please migrate to @stencil/angular-output-target and remove the 'angular' output target from your stencil.config.ts file. Instructions for doing so can be found in the Angular Framework Integration section of this site.

Stencil APIs

Stencil exposes Node APIs for programmatically invoking the compiler. Most users do not use these APIs directly. Unless your project calls these APIs, no action is required for this section.

Flag Parsing, `parseFlags()`

Stencil exposes an API for parsing flags that it receives from the command line. Previously, it accepted an optional CompilerSystem argument that was never properly used. The flag has been removed as of Stencil v3.0.0. To migrate, remove the argument from any calls to parseFlags imported from the Stencil CLI package.

import { parseFlags } from '@stencil/core/cli';
- parseFlags(flags, compilerSystem);
+ parseFlags(flags);

Destroy Callback, `addDestroy()`, `removeDestroy()`

The Stencil CompilerSystem interface has a pair of methods, addDestroy and removeDestroy that were previously misspelled. If your codebase explicitly calls these methods, they need to be updated. Replace all instances of addDestory with addDestroy and all instances of removeDestory with removeDestroy The functionality of these methods remains the same.

End-to-End Testing

Puppeteer v10+ Required

Versions of Puppeteer prior to Puppeteer version 10 are no longer supported. In newer versions of Puppeteer, the library provides its own types, making @types/puppeteer no longer necessary. Ensure that Puppeteer v10 or higher is installed, and that its typings are not:

npm
Yarn

$ npm install puppeteer
$ npm uninstall @types/puppeteer

$ yarn add puppeteer
$ yarn remove @types/puppeteer

Need Help Upgrading?

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

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

Upgrading to Stencil v3.0.0

Getting Started​

Updating Your Code​

New Configuration Defaults​

SourceMaps​

dist-custom-elements Type Declarations​

Legacy Browser Support Fields Deprecated​

dynamicImportShim​

shadowDomShim​

cssVarsShim​

safari10​

Deprecated assetsDir Removed from @Component() decorator​

Drop Node 12 Support​

Strongly Typed Inputs​

Narrowed Typing for autocapitalize Attribute​

Custom Types for Props and Events are now Exported from components.d.ts​

Composition Event Handlers Renamed​

Output Targets​

dist-custom-elements Output Target​

Add customElementsExportBehavior to Control Export Behavior​

Move autoDefineCustomElements Configuration​

Remove inlineDynamicImports Configuration​

dist-custom-elements-bundle Output Target​

Framework Integration Output Targets​

Using includeImportCustomElements​

Legacy Angular Output Target​

Stencil APIs​

Flag Parsing, parseFlags()​

Destroy Callback, addDestroy(), removeDestroy()​

End-to-End Testing​

Puppeteer v10+ Required​

Need Help Upgrading?​