1"use strict";(self.webpackChunk_stencil_stencil_site=self.webpackChunk_stencil_stencil_site||[]).push([[5930],{31360:(e,t,n)=>{n.r(t),n.d(t,{assets:()=>a,contentTitle:()=>d,default:()=>u,frontMatter:()=>c,metadata:()=>l,toc:()=>h});var s=n(74848),o=n(28453),i=n(45645),r=n(7227);const c={title:"Upgrading to Stencil v3.0.0",description:"Upgrading to Stencil v3.0.0",url:"/docs/upgrading-to-stencil-3"},d="Upgrading to Stencil v3.0.0",l={id:"introduction/upgrading-to-stencil-three",title:"Upgrading to Stencil v3.0.0",description:"Upgrading to Stencil v3.0.0",source:"@site/versioned_docs/version-v2/introduction/upgrading-to-stencil-three.md",sourceDirName:"introduction",slug:"/introduction/upgrading-to-stencil-three",permalink:"/docs/v2/introduction/upgrading-to-stencil-three",draft:!1,unlisted:!1,editUrl:"https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v2/introduction/upgrading-to-stencil-three.md",tags:[],version:"v2",frontMatter:{title:"Upgrading to Stencil v3.0.0",description:"Upgrading to Stencil v3.0.0",url:"/docs/upgrading-to-stencil-3"},sidebar:"docs",previous:{title:"Getting Started",permalink:"/docs/v2/getting-started"},next:{title:"API",permalink:"/docs/v2/api"}},a={},h=[{value:"Getting Started",id:"getting-started",level:2},{value:"Updating Your Code",id:"updating-your-code",level:2},{value:"New Configuration Defaults",id:"new-configuration-defaults",level:3},{value:"SourceMaps",id:"sourcemaps",level:4},{value:"<code>dist-custom-elements</code> Type Declarations",id:"dist-custom-elements-type-declarations",level:4},{value:"Legacy Browser Support Fields Deprecated",id:"legacy-browser-support-fields-deprecated",level:3},{value:"<code>dynamicImportShim</code>
1",id:"dynamicimportshim",level:4},{value:"<code>shadowDomShim</code>",id:"shadowdomshim",level:4},{value:"<code>cssVarsShim</code>",id:"cssvarsshim",level:4},{value:"<code>safari10</code>",id:"safari10",level:4},{value:"Deprecated <code>assetsDir</code> Removed from <code>@Component()</code> decorator",id:"deprecated-assetsdir-removed-from-component-decorator",level:3},{value:"Drop Node 12 Support",id:"drop-node-12-support",level:3},{value:"Strongly Typed Inputs",id:"strongly-typed-inputs",level:3},{value:"Narrowed Typing for <code>autocapitalize</code> Attribute",id:"narrowed-typing-for-autocapitalize-attribute",level:3},{value:"Custom Types for Props and Events are now Exported from <code>components.d.ts</code>",id:"custom-types-for-props-and-events-are-now-exported-from-componentsdts",level:3},{value:"Composition Event Handlers Renamed",id:"composition-event-handlers-renamed",level:3},{value:"Output Targets",id:"output-targets",level:2},{value:"<code>dist-custom-elements</code> Output Target",id:"dist-custom-elements-output-target",level:3},{value:"Add <code>customElementsExportBehavior</code> to Control Export Behavior",id:"add-customelementsexportbehavior-to-control-export-behavior",level:4},{value:"Move <code>autoDefineCustomElements</code> Configuration",id:"move-autodefinecustomelements-configuration",level:4},{value:"Remove <code>inlineDynamicImports</code> Configuration",id:"remove-inlinedynamicimports-configuration",level:4},{value:"<code>dist-custom-elements-bundle</code> Output Target",id:"dist-custom-elements-bundle-output-target",level:3},{value:"Framework Integration Output Targets",id:"framework-integration-output-targets",level:2},{value:"Using <code>includeImportCustomElements</code>",id:"using-includeimportcustomelements",level:3},{value:"Legacy Angular Output Target",id:"legacy-angular-output-target",level:2},{value:"Stencil APIs",id:"stencil-apis",level:2},{value:"Flag Parsing, <code>parseFlags()</code>",id:"flag-parsing-parseflags",level:3},{value:"Destroy Callback, <code>addDestroy()</code>, <code>removeDestroy()</code>",id:"destroy-callback-adddestroy-removedestroy",level:3},{value:"End-to-End Testing",id:"end-to-end-testing",level:2},{value:"Puppeteer v10+ Required",id:"puppeteer-v10-required",level:3},{value:"Additional Packages",id:"additional-packages",level:2},{value:"Need Help Upgrading?",id:"need-help-upgrading",level:2}];function p(e){const t={a:"a",admonition:"admonition",code:"code",em:"em",h1:"h1",h2:"h2",h3:"h3",h4:"h4",header:"header",li:"li",p:"p",pre:"pre",table:"table",tbody:"tbody",td:"td",th:"th",thead:"thead",tr:"tr",ul:"ul",...(0,o.R)(),...e.components};return(0,s.jsxs)(s.Fragment,{children:[(0,s.jsx)(t.header,{children:(0,s.jsx)(t.h1,{id:"upgrading-to-stencil-v300",children:"Upgrading to Stencil v3.0.0"})}),"\n",(0,s.jsx)(t.h2,{id:"getting-started",children:"Getting Started"}),"\n",(0,s.jsx)(t.p,{children:"It's recommended that your projects start their upgrade from Stencil v2.\nProjects using Stencil v0 or Stencil v1 should upgrade to Stencil v2 before proceeding with this guide.\nFor breaking changes introduced in previous major versions of the library, see:"}),"\n",(0,s.jsxs)(t.ul,{children:["\n",(0,s.jsx)(t.li,{children:(0,s.jsx)(t.a,{href:"https://github.com/ionic-team/stencil/blob/main/BREAKING_CHANGES.md#stencil-two",children:"Stencil v2 Breaking Changes"})}),"\n",(0,s.jsx)(t.li,{children:(0,s.jsx)(t.a,{href:"https://github.com/ionic-team/stencil/blob/main/BREAKING_CHANGES.md#stencil-one",children:"Stencil v1 Breaking Changes"})}),"\n"]}),"\n",(0,s.jsxs)(t.p,{children:["For projects that are on Stencil v2, install the latest version of Stencil v3: ",(0,s.jsx)(t.code,{children:"npm install @stencil/core@v3-next"})]}),"\n",(0,s.jsx)(t.h2,{id:"updating-your-code",children:"Updating Your Code"}),"\n",(0,s.jsx)(t.h3,{id:"new-configuration-defaults",children:"New Configuration Defaults"}),"\n",(0,s.jsx)(t.p,{children:"Starting with Stencil v3.0.0, the default configuration values have changed for a few properties."}),"\n",(0,s.jsx)(t.h4,{id:"sourcemaps",children:"SourceMaps"}),"\n",(0,s.jsxs)(t.p,{children:["Sourcemaps are generated by default for all builds.\nPreviously, sourcemaps had to be explicitly enabled by setting the ",(0,s.jsx)(t.code,{children:"sourceMap"})," flag to ",(0,s.jsx)(t.code,{children:"true"}),".\nTo restore the old behavior, set the ",(0,s.jsx)(t.code,{children:"sourceMap"})," flag to ",(0,s.jsx)(t.code,{children:"false"})," in your project's ",(0,s.jsx)(t.code,{children:"stencil.config.ts"}),":"]}),"\n",(0,s.jsx)(t.pre,{children:(0,s.jsx)(t.code,{className:"language-ts",children:"// stencil.config.ts\nimport { Config } from '@stencil/core';
1\n\nexport const config: Config = {\n sourceMap: false,\n // ...\n};\n"})}),"\n",(0,s.jsxs)(t.h4,{id:"dist-custom-elements-type-declarations",children:[(0,s.jsx)(t.code,{children:"dist-custom-elements"})," Type Declarations"]}),"\n",(0,s.jsxs)(t.p,{children:["Type declaration files (",(0,s.jsx)(t.code,{children:".d.ts"})," files) are now generated by default for the ",(0,s.jsxs)(t.a,{href:"/docs/v2/custom-elements",children:[(0,s.jsx)(t.code,{children:"dist-custom-elements"})," output target"]}),".\nIf your project is using ",(0,s.jsx)(t.code,{children:"dist-custom-elements"})," and you do not wish to generate type declarations, the old behavior can be achieved by setting ",(0,s.jsx)(t.code,{children:"generateTypeDeclarations"})," to ",(0,s.jsx)(t.code,{children:"false"})," in the ",(0,s.jsx)(t.code,{children:"dist-custom-elements"})," output target in your project's ",(0,s.jsx)(t.code,{children:"stencil.config.ts"}),":"]}),"\n",(0,s.jsx)(t.pre,{children:(0,s.jsx)(t.code,{className:"language-ts",children:"// stencil.config.ts\nimport { Config } from '@stencil/core';\n\nexport const config: Config = {\n outputTargets: [\n {\n type: 'dist-custom-elements',\n generateTypeDeclarations: false,\n // ...\n },\n // ...\n ],\n // ...\n};\n"})}),"\n",(0,s.jsx)(t.h3,{id:"legacy-browser-support-fields-deprecated",children:"Legacy Browser Support Fields Deprecated"}),"\n",(0,s.jsx)(t.p,{children:"Several configuration options related to support for Safari <11, IE11, and Edge\n<19 have been marked as deprecated, and will be removed entirely in a future\nversion of Stencil."}),"\n",(0,s.jsx)(t.h4,{id:"dynamicimportshim",children:(0,s.jsx)(t.code,{children:"dynamicImportShim"})}),"\n",(0,s.jsxs)(t.p,{children:["The ",(0,s.jsx)(t.code,{children:"extras.dynamicImportShim"})," option causes Stencil to include a polyfill for\nthe ",(0,s.jsxs)(t.a,{href:"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import",children:["dynamic ",(0,s.jsx)(t.code,{children:"import()"}),"\nfunction"]}),"\nfor use at runtime. The field is renamed to ",(0,s.jsx)(t.code,{children:"__deprecated__dynamicImportShim"}),"\nto indicate deprecation. To retain the previous behavior the new option can be\nset in your project's ",(0,s.jsx)(t.code,{children:"stencil.config.ts"}),":"]}),"\n",(0,s.jsx)(t.pre,{children:(0,s.jsx)(t.code,{className:"language-ts",children:"// stencil.config.ts\nimport { Config } from '@stencil/core';\nexport const config: Config = {\n extras: {\n __deprecated__dynamicImportShim: true\n }\n};\n"})}),"\n",(0,s.jsx)(t.h4,{id:"shadowdomshim",children:(0,s.jsx)(t.code,{children:"shadowDomShim"})}),"\n",(0,s.jsxs)(t.p,{children:["If ",(0,s.jsx)(t.code,{children:"extras.shadowDomShim"})," is set to ",(0,s.jsx)(t.code,{children:"true"})," the Stencil runtime will check\nwhether a shim for ",(0,s.jsx)(t.a,{href:"https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM",children:"shadow\nDOM"}),"\nis needed in the current browser, and include one if so. For Stencil v3.0.0\nthis field is renamed to ",(0,s.jsx)(t.code,{children:"__deprecated__shadowDomShim"}),". To retain the previous\nbehavior the new option can be set in your project's ",(0,s.jsx)(t.code,{children:"stencil.config.ts"}),":"]}),"\n",(0,s.jsx)(t.pre,{children:(0,s.jsx)(t.code,{className:"language-ts",children:"// stencil.config.ts\nimport { Config } from '@stencil/core';\nexport const config: Config = {\n extras: {\n __deprecated__shadowDomShim: true\n }\n};\n"})}),"\n",(0,s.jsx)(t.h4,{id:"cssvarsshim",children:(0,s.jsx)(t.code,{children:"cssVarsShim"})}),"\n",(0,s.jsxs)(t.p,{children:[(0,s.jsx)(t.code,{children:"extras.cssVarsShim"})," causes Stencil to include a polyfill for ",(0,s.jsx)(t.a,{href:"https://developer.mozilla.org/en-US/docs/Web/CSS/--*",children:"CSS\nvariables"}),". For Stencil\nv3.0.0 this field is renamed to ",(0,s.jsx)(t.code,{children:"__deprecated__cssVarsShim"}),". To retain the\nprevious behavior the new option can be set in your project's\n",(0,s.jsx)(t.code,{children:"stencil.config.ts"}),":"]}),"\n",(0,s.jsx)(t.pre,{children:(0,s.jsx)(t.code,{className:"language-ts",children:"// stencil.config.ts\nimport { Config } from '@stencil/core';\nexport const config: Config = {\n extras: {\n __deprecated__cssVarsShim: true\n }\n};\n"})}),"\n",(0,s.jsx)(t.h4,{id:"safari10",children:(0,s.jsx)(t.code,{children:"safari10"})}),"\n",(0,s.jsxs)(t.p,{children:["If ",(0,s.jsx)(t.code,{children:"extras.safari10"})," is set to ",(0,s.jsx)(t.code,{children:"true"})," the Stencil runtime will patch ES module\nsupport for Safari 10. For Stencil v3.0.0 this field is renamed to\n",(0,s.jsx)(t.code,{children:"__deprecated__safari10"}),". To retain the previous behavior the new option can be\nset in your project's ",(0,s.jsx)(t.code,{children:"stencil.config.ts"}),":"]}),"\n",(0,s.jsx)(t.pre,{children:(0,s.jsx)(t.code,{className:"language-ts",children:"// stencil.config.ts\nimport { Config } from '@stencil/core';\nexport const config: Config = {\n extras: {\n __deprecated__safari10: true\n }\n};\n"})}),"\n",(0,s.jsxs)(t.h3,{id:"deprecated-assetsdir-removed-from-component-decorator",children:["Deprecated ",(0,s.jsx)(t.code,{children:"assetsDir"})," Removed from ",(0,s.jsx)(t.code,{children:"@Component()"})," decorator"]}),"\n",(0,s.jsxs)(t.p,{children:["The ",(0,s.jsx)(t.code,{children:"assetsDir"})," field was ",(0,s.jsx)(t.a,{href:"https://github.com/ionic-team/stencil/blob/main/BREAKING_CHANGES.md#componentassetsdir",children:"deprecated
1in Stencil v2.0.0"}),", but some backwards compatibility was retained with a warning message.\nIt has been fully removed in Stencil v3.0.0 in favor of ",(0,s.jsx)(t.code,{children:"assetsDirs"}),".\nTo migrate from existing usages of ",(0,s.jsx)(t.code,{children:"assetsDir"}),", update the property name and wrap its value in an array:"]}),"\n",(0,s.jsx)(t.pre,{children:(0,s.jsx)(t.code,{className:"language-diff",children:"@Component({\n tag: 'my-component',\n- assetsDir: 'assets',\n+ assetsDirs: ['assets'],\n})\n"})}),"\n",(0,s.jsxs)(t.p,{children:["For more information on the ",(0,s.jsx)(t.code,{children:"assetsDirs"})," field, please see the ",(0,s.jsxs)(t.a,{href:"/docs/v2/assets#assetsdirs",children:["Stencil Documentation on ",(0,s.jsx)(t.code,{children:"assetsDirs"})]})]}),"\n",(0,s.jsx)(t.h3,{id:"drop-node-12-support",children:"Drop Node 12 Support"}),"\n",(0,s.jsx)(t.p,{children:"Stencil no longer supports Node 12.\nPlease upgrade local development machines, continuous integration pipelines, etc. to use Node v14 or higher."}),"\n",(0,s.jsx)(t.h3,{id:"strongly-typed-inputs",children:"Strongly Typed Inputs"}),"\n",(0,s.jsxs)(t.p,{children:[(0,s.jsx)(t.code,{children:"onInput"})," and ",(0,s.jsx)(t.code,{children:"onInputCapture"})," events have had their interface's updated to accept an argument of ",(0,s.jsx)(t.code,{children:"InputEvent"})," over ",(0,s.jsx)(t.code,{children:"Event"}),":"]}),"\n",(0,s.jsx)(t.pre,{children:(0,s.jsx)(t.code,{className:"language-diff",children:"- onInput?: (event: Event) => void;\n+ onInput?: (event: InputEvent) => void;\n- onInputCapture?: (event: Event) => void;\n+ onInputCapture?: (event: InputEvent) => void;\n"})}),"\n",(0,s.jsxs)(t.p,{children:[(0,s.jsx)(t.code,{children:"event"})," arguments to either callback should be updated to take this narrower typing into account"]}),"\n",(0,s.jsxs)(t.h3,{id:"narrowed-typing-for-autocapitalize-attribute",children:["Narrowed Typing for ",(0,s.jsx)(t.code,{children:"autocapitalize"})," Attribute"]}),"\n",(0,s.jsxs)(t.p,{children:["The ",(0,s.jsxs)(t.a,{href:"https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/autocapitalize",children:[(0,s.jsx)(t.code,{children:"autocaptialize"})," attribute"]})," has been narrowed from type ",(0,s.jsx)(t.code,{children:"any"})," to type ",(0,s.jsx)(t.code,{children:"string"}),".\nThis change brings Stencil into closer alignment with TypeScript's typings for the attribute.\nNo explicit changes are needed, unless a project was passing non-strings to the attribute."]}),"\n",(0,s.jsxs)(t.h3,{id:"custom-types-for-props-and-events-are-now-exported-from-componentsdts",children:["Custom Types for Props and Events are now Exported from ",(0,s.jsx)(t.code,{children:"components.d.ts"})]}),"\n",(0,s.jsxs)(t.p,{children:["Custom types for props and custom events are now re-exported from a project's ",(0,s.jsx)(t.code,{children:"components.d.ts"})," file."]}),"\n",(0,s.jsx)(t.p,{children:"For the following Stencil component"}),"\n",(0,s.jsx)(t.pre,{children:(0,s.jsx)(t.code,{className:"language-tsx",children:"import { Component, Event, EventEmitter, Prop, h } from '@stencil/core';\n\nexport type NameType = string;\nexport type Todo = Event;\n\n@Component({\n tag: 'my-component',\n styleUrl: 'my-component.css',\n shadow: true,\n})\nexport class MyComponent {\n @Prop() first: NameType;\n\n @Event() todoCompleted: EventEmitter<Todo>\n\n render() {\n return <div>Hello, World! I'm {this.first}</div>;\n }\n}\n"})}),"\n",(0,s.jsxs)(t.p,{children:["The following data will now be included automatically in ",(0,s.jsx)(t.code,{children:"components.d.ts"}),":"]}),"\n",(0,s.jsx)(t.pre,{children:(0,s.jsx)(t.code,{className:"language-diff",children:' import { HTMLStencilElement, JSXBase } from "@stencil/core/internal";\n import { NameType, Todo } from "./components/my-component/my-component";\n+ export { NameType, Todo } from "./components/my-component/my-component";\n export namespace Components {\n interface MyComponent {\n "first": NameType;\n }\n }\n export interface MyComponentCustomEvent<T> extends CustomEvent<T> {\n detail: T;\n target: HTMLMyComponentElement;\n }\n declare global {\n interface HTMLMyComponentElement extends Components.MyComponent, HTMLStencilElement {\n }\n'})}),"\n",(0,s.jsx)(t.p,{children:"This allows those types to be easily accessed from the root of the type distribution:"}),"\n",(0,s.jsx)(t.pre,{children:(0,s.jsx)(t.code,{className:"language-ts",children:"import { NameType, Todo } from '@my-lib/types';\n"})}),"\n",(0,s.jsxs)(t.p,{children:["When using ",(0,s.jsx)(t.code,{children:"dist-custom-elements"}),", these types can now be accessed from the custom element output:"]}),"\n",(0,s.jsx)(t.pre,{children:(0,s.jsx)(t.code,{className:"language-ts",children:"import { NameType, Todo } from '@my-custom-elements-output';\n"})}),"\n",(0,s.jsxs)(t.p,{children:["This ",(0,s.jsx)(t.em,{children:"may"})," clash with any manually created types in existing Stencil projects.\nProjects that manually create type definitions from ",(0,s.jsx)(t.code,{children:"components.d.ts"})," will either need to:"]}),"\n",(0,s.jsxs)(t.ul,{children:["\n",(0,s.jsxs)(t.li,{children:["remove the manually created type (if the types generated in ",(0,s.jsx)(t.code,{children:"components.d.ts"})," suffice)"]}),"\n",(0,s.jsx)(t.li,{children:"update their type creation logic to account for potential naming collisions with the newly generated types"}),"\n"]}),"\n",(0,s.jsx)(t.h3,{id:"composition-event-handlers-renamed",children:"Composition Event Handlers Renamed"}),"\n",(0,s.jsx)(t.p,{children:"The names of Stencil's composition event handlers have been changed in order to\ncorrect a casing issue which prevented handlers from being called when events\nfired. The changes are as follows:"}),"\n",(0,s.jsxs)(t.table,{children:[(0,s.jsx)(t.thead,{children:(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.th,{children:"previous name"}),(0,s.jsx)(t.th,{children:"new name"})]})}),(0,s.jsxs)(t.tbody,{children:[(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{children:(0,s.jsx)(t.code,{children:"onCompositionEnd"})}),(0,s.jsx)(t.td,{children:(0,s.jsx)(t.code,{children:"onCompositionend"})})]}),(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{children:(0,s.jsx)(t.code,{children:"onCompositionEndCapture"})}),(0,s.jsx)(t.td,{children:(0,s.jsx)(t.code,{children:"onCompositionendCapture"})})]}),(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{children:(0,s.jsx)(t.code,{children:"onCompositionStart"})}),(0,s.jsx)(t.td,{children:(0,s.jsx)(t.code,{children:"onCompositionstart"})})]}),(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{children:(0,s.jsx)(t.code,{children:"onCompositionStartCapture"})}),(0,s.jsx)(t.td,{children:(0,s.jsx)(t.code,{children:"onCompositionstartCapture"})})]}),(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{children:(0,s.jsx)(t.code,{children:"onCompositionUpdate"})}),(0,s.jsx)(t.td,{children:(0,s.jsx)(t.code,{children:"onCompositionupdate"})})]}),(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{children:(0,s.jsx)(t.code,{children:"onCompositionUpdateCapture"})}),(0,s.jsx)(t.td,{children:(0,s.jsx)(t.code,{children:"onCompositionupdateCapture"})})]})]})]}),"\n",(0,s.jsx)(t.h2,{id:"output-targets",children:"Output Targets"}),"\n",(0,s.jsxs)(t.h3,{id:"dist-custom-elements-output-target",children:[(0,s.jsx)(t.code,{children:"dist-custom-elements"})," Output Target"]}),"\n",(0,s.jsxs)(t.h4,{id:"add-customelementsexportbehavior-to-control-export-behavior",children:["Add ",(0,s.jsx)(t.code,{children:"customElementsExportBehavior"})," to Control Export Behavior"]}),"\n",(0,s.jsxs)(t.p,{children:[(0,s.jsx)(t.code,{children:"customElementsExportBehavior"}
1)," is a new configuration option for the output target.\nIt allows users to configure the export behavior of components that are compiled using the output target.\nBy default, this output target will behave exactly as it did in Stencil v2.0.0."]}),"\n",(0,s.jsx)(t.p,{children:"This config option provides additional behaviors that will alter the default component export OR custom element definition behaviors\nfor this target. The desired behavior can be set via the following in a project's Stencil config:"}),"\n",(0,s.jsx)(t.pre,{children:(0,s.jsx)(t.code,{className:"language-ts",children:"// stencil.config.ts\nimport { Config } from '@stencil/core';\nexport const config: Config = {\n outputTargets: [\n {\n type: 'dist-custom-elements',\n customElementsExportBehavior: 'default' | 'auto-define-custom-elements' | 'bundle' | 'single-export-module',\n },\n // ...\n ],\n // ...\n};\n"})}),"\n",(0,s.jsxs)(t.table,{children:[(0,s.jsx)(t.thead,{children:(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.th,{children:"Option"}),(0,s.jsx)(t.th,{children:"Description"})]})}),(0,s.jsxs)(t.tbody,{children:[(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{children:(0,s.jsx)(t.code,{children:"default"})}),(0,s.jsxs)(t.td,{children:["No additional re-export or auto-definition behavior will be performed.",(0,s.jsx)("br",{}),(0,s.jsx)("br",{}),"This value will be used if no explicit value is set in the config, or if a given value is not a valid option."]})]}),(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{children:(0,s.jsx)(t.code,{children:"auto-define-custom-elements"})}),(0,s.jsxs)(t.td,{children:["A component and its children will be automatically defined with the ",(0,s.jsx)(t.code,{children:"CustomElementRegistry"})," when the component's module is imported."]})]}),(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{children:(0,s.jsx)(t.code,{children:"bundle"})}),(0,s.jsxs)(t.td,{children:["A utility ",(0,s.jsx)(t.code,{children:"defineCustomElements()"})," function is exported from the ",(0,s.jsx)(t.code,{children:"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."]})]}),(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{children:(0,s.jsx)(t.code,{children:"single-export-module"})}),(0,s.jsxs)(t.td,{children:["All component and custom element definition helper functions will be exported from the ",(0,s.jsx)(t.code,{children:"index.js"})," file in the output directory (see ",(0,s.jsx)(t.a,{href:"/docs/v2/custom-elements#defining-exported-custom-elements",children:"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 ",(0,s.jsx)(t.a,{href:"/docs/v2/custom-elements#distributing-custom-elements",children:"below"})," for more details."]})]})]})]}),"\n",(0,s.jsx)(t.admonition,{type:"note",children:(0,s.jsxs)(t.p,{children:["This option also has an impact when using the ",(0,s.jsx)(t.a,{href:"/docs/v2/overview",children:"Stencil framework integration output targets"}),". Please see the ",(0,s.jsx)(t.a,{href:"#framework-integration-output-targets",children:"framework integration migration"})," section below for more information."]})}),"\n",(0,s.jsxs)(t.h4,{id:"move-autodefinecustomelements-configuration",children:["Move ",(0,s.jsx)(t.code,{children:"autoDefineCustomElements"})," Configuration"]}),"\n",(0,s.jsxs)(t.p,{children:[(0,s.jsx)(t.code,{children:"autoDefineCustomElements"})," was a configuration option to define a component and its children automatically with the ",(0,s.jsx)(t.code,{children:"CustomElementRegistry"})," when the component's module is imported.\nThis behavior has been merged into the ",(0,s.jsxs)(t.a,{href:"#add-customelementsexportbehavior-to-control-export-behavior",children:[(0,s.jsx)(t.code,{children:"customElementsExportBehavior"})," configuration field"]}),".\nTo continue to use this behavior, replace ",(0,s.jsx)(t.code,{children:"autoDefineCustomElements"})," in your project's ",(0,s.jsx)(t.code,{children:"stencil.config.ts"})," with the following:"]}),"\n",(0,s.jsx)(t.pre,{children:(0,s.jsx)(t.code,{className:"language-diff",children:"// stencil.config.ts\nimport { Config } from '@stencil/core';
1\n\nexport const config: Config = {\n outputTargets: [\n {\n type: 'dist-custom-elements',\n- autoDefineCustomElements: true,\n+ customElementsExportBehavior: 'auto-define-custom-elements',\n // ...\n },\n // ...\n ],\n // ...\n};\n"})}),"\n",(0,s.jsxs)(t.h4,{id:"remove-inlinedynamicimports-configuration",children:["Remove ",(0,s.jsx)(t.code,{children:"inlineDynamicImports"})," Configuration"]}),"\n",(0,s.jsxs)(t.p,{children:["The ",(0,s.jsx)(t.code,{children:"inlineDynamicImports"})," configuration option on ",(0,s.jsx)(t.code,{children:"dist-custom-elements"}),' has been removed. Previously, this option would throw an error at build\ntime during the Rollup bundling process if the build contained multiple "inputs" (components).']}),"\n",(0,s.jsxs)(t.h3,{id:"dist-custom-elements-bundle-output-target",children:[(0,s.jsx)(t.code,{children:"dist-custom-elements-bundle"})," Output Target"]}),"\n",(0,s.jsxs)(t.p,{children:["The ",(0,s.jsx)(t.code,{children:"dist-custom-elements-bundle"})," has been removed starting with Stencil v3.0.0, following the ",(0,s.jsx)(t.a,{href:"https://github.com/ionic-team/stencil/issues/3136",children:"RFC process"}),".\nUsers of this output target should migrate to the ",(0,s.jsx)(t.code,{children:"dist-custom-elements"})," output target."]}),"\n",(0,s.jsxs)(t.p,{children:["By default, ",(0,s.jsx)(t.code,{children:"dist-custom-elements"})," does not automatically define all a project's component's with the CustomElementsRegistry.\nThis allows for better tree-shaking and smaller bundle sizes."]}),"\n",(0,s.jsxs)(t.p,{children:["For teams that need to migrate quickly to ",(0,s.jsx)(t.code,{children:"dist-custom-elements"}),", the following configuration should be close to a drop-in replacement for ",(0,s.jsx)(t.code,{children:"dist-custom-elements-bundle"}),":"]}),"\n",(0,s.jsx)(t.pre,{children:(0,s.jsx)(t.code,{className:"language-diff",children:"// stencil.config.ts\nimport { Config } from '@stencil/core';\n\nexport const config: Config = {\n outputTargets: [\n- {\n- type: 'dist-custom-elements-bundle',\n- // additional configuration\n- },\n+ {\n+ type: 'dist-custom-elements',\n+ customElementsExportBehavior: 'bundle'\n+ },\n // ...\n ],\n // ...\n};\n"})}),"\n",(0,s.jsxs)(t.p,{children:["However, it does not necessarily improve tree-shaking/bundle size.\nFor more information on configuring this output target, please see the ",(0,s.jsxs)(t.a,{href:"/docs/v2/custom-elements",children:[(0,s.jsx)(t.code,{children:"dist-custom-elements"})," documentation"]})]}),"\n",(0,s.jsx)(t.h2,{id:"framework-integration-output-targets",children:"Framework Integration Output Targets"}),"\n",(0,s.jsxs)(t.h3,{id:"using-includeimportcustomelements",children:["Using ",(0,s.jsx)(t.code,{children:"includeImportCustomElements"})]}),"\n",(0,s.jsxs)(t.p,{children:["The addition of the ",(0,s.jsx)(t.a,{href:"#add-customelementsexportbehavior-to-control-export-behavior",children:"customElementsExportBehavior"})," option on ",(0,s.jsx)(t.code,{children:"dist-custom-elements"})," can also have an impact on the\n",(0,s.jsx)(t.a,{href:"/docs/v2/overview",children:"Stencil framework integration output targets"})," if they are configured to use the output from ",(0,s.jsx)(t.code,{children:"dist-custom-elements"})," (i.e. by setting\n",(0,s.jsx)(t.code,{children:"includeImportCustomElements: true"}),"). If you encounter problems with the generated import statements in the component proxy files, setting\n",(0,s.jsx)(t.code,{children:"customElementsExportBehavior: 'single-export-module'"})," in the ",(0,s.jsx)(t.code,{children:"dist-custom-elements"})," output target config should result in the same behavior as in Stencil V2. For example, a project using\nthe Angular framework integration output target would have a config like:"]}),"\n",(0,s.jsx)(t.pre,{children:(0,s.jsx)(t.code,{className:"language-ts",children:"// stencil.config.ts\nimport { Config } from '@stencil/core';\nimport { angularOutputTarget } from '@stencil/angular-output-target';\n\nexport const config: Config = {\n outputTargets: [\n angularOutputTarget({\n // Same config as V2\n includeImportCustomElements: true\n }),\n {\n type: 'dist-custom-elements',\n // This will create the same behavior as Stencil V2\n customElementsExportBehavior: 'single-export-module'\n }\n ]\n}\n"})}),"\n",(0,s.jsx)(t.h2,{id:"legacy-angular-output-target",children:"Legacy Angular Output Target"}
1),"\n",(0,s.jsxs)(t.p,{children:["Prior to the creation of the ",(0,s.jsx)(t.a,{href:"https://github.com/ionic-team/stencil-ds-output-targets/blob/main/packages/angular-output-target/README.md",children:(0,s.jsx)(t.code,{children:"@stencil/angular-output-target"})}),", the ",(0,s.jsx)(t.code,{children:"'angular'"})," output target was the original means of connecting a Stencil component to an Angular application.\nThis output target has been removed in favor of ",(0,s.jsx)(t.code,{children:"@stencil/angular-output-target"}),".\nPlease migrate to ",(0,s.jsx)(t.code,{children:"@stencil/angular-output-target"})," and remove the ",(0,s.jsx)(t.code,{children:"'angular'"})," output target from your ",(0,s.jsx)(t.code,{children:"stencil.config.ts"})," file.\nInstructions for doing so can be found ",(0,s.jsx)(t.a,{href:"/docs/v2/angular#setup",children:"in the Angular Framework Integration section"})," of this site."]}),"\n",(0,s.jsx)(t.h2,{id:"stencil-apis",children:"Stencil APIs"}),"\n",(0,s.jsx)(t.p,{children:"Stencil exposes Node APIs for programmatically invoking the compiler.\nMost users do not use these APIs directly.\nUnless your project calls these APIs, no action is required for this section."}),"\n",(0,s.jsxs)(t.h3,{id:"flag-parsing-parseflags",children:["Flag Parsing, ",(0,s.jsx)(t.code,{children:"parseFlags()"})]}),"\n",(0,s.jsxs)(t.p,{children:["Stencil exposes an API for parsing flags that it receives from the command line.\nPreviously, it accepted an optional ",(0,s.jsx)(t.code,{children:"CompilerSystem"})," argument that was never properly used.\nThe flag has been removed as of Stencil v3.0.0.\nTo migrate, remove the argument from any calls to ",(0,s.jsx)(t.code,{children:"parseFlags"})," imported from the Stencil CLI package."]}),"\n",(0,s.jsx)(t.pre,{children:(0,s.jsx)(t.code,{className:"language-diff",children:"import { parseFlags } from '@stencil/core/cli';\n- parseFlags(flags, compilerSystem);\n+ parseFlags(flags);\n"})}),"\n",(0,s.jsxs)(t.h3,{id:"destroy-callback-adddestroy-removedestroy",children:["Destroy Callback, ",(0,s.jsx)(t.code,{children:"addDestroy()"}),", ",(0,s.jsx)(t.code,{children:"removeDestroy()"})]}),"\n",(0,s.jsxs)(t.p,{children:["The Stencil ",(0,s.jsx)(t.code,{children:"CompilerSystem"})," interface has a pair of methods, ",(0,s.jsx)(t.code,{children:"addDestroy"})," and ",(0,s.jsx)(t.code,{children:"removeDestroy"})," that were previously misspelled.\nIf your codebase explicitly calls these methods, they need to be updated.\nReplace all instances of ",(0,s.jsx)(t.code,{children:"addDestory"})," with ",(0,s.jsx)(t.code,{children:"addDestroy"})," and all instances of ",(0,s.jsx)(t.code,{children:"removeDestory"})," with ",(0,s.jsx)(t.code,{children:"removeDestroy"}),"\nThe functionality of these methods remains the same."]}),"\n",(0,s.jsx)(t.h2,{id:"end-to-end-testing",children:"End-to-End Testing"}),"\n",(0,s.jsx)(t.h3,{id:"puppeteer-v10-required",children:"Puppeteer v10+ Required"}),"\n",(0,s.jsxs)(t.p,{children:["Versions of Puppeteer prior to Puppeteer version 10 are no longer supported.\nIn newer versions of Puppeteer, the library provides its own types, making ",(0,s.jsx)(t.code,{children:"@types/puppeteer"})," no longer necessary.\nEnsure that Puppeteer v10 or higher is installed, and that its typings are not:"]}),"\n",(0,s.jsxs)(i.A,{groupId:"npm2yarn",children:[(0,s.jsx)(r.A,{value:"npm",children:(0,s.jsx)(t.pre,{children:(0,s.jsx)(t.code,{className:"language-bash",children:"$ npm install puppeteer\n$ npm uninstall @types/puppeteer\n"})})}),(0,s.jsx)(r.A,{value:"yarn",label:"Yarn",children:(0,s.jsx)(t.pre,{children:(0,s.jsx)(t.code,{className:"language-bash",children:"$ yarn add puppeteer\n$ yarn remove @types/puppeteer\n"})})}),(0,s.jsx)(r.A,{value:"pnpm",label:"pnpm",children:(0,s.jsx)(t.pre,{children:(0,s.jsx)(t.code,{className:"language-bash",children:"$ pnpm add puppeteer\n$ pnpm remove @types/puppeteer\n"})})})]}),"\n",(0,s.jsx)(t.h2,{id:"additional-packages",children:"Additional Packages"}),"\n",(0,s.jsxs)(t.p,{children:["In order to guarantee that other ",(0,s.jsx)(t.code,{children:"@stencil/"})," packages will continue to function as expected,\nit's recommended that a project that uses any of the packages listed below updates to the listed minimum package version."]}),"\n",(0,s.jsxs)(t.table,{children:[(0,s.jsx)(t.thead,{children:(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.th,{children:"Package"}),(0,s.jsx)(t.th,{children:"Minimum Package Version"}),(0,s.jsx)(t.th,{children:"GitHub"}),(0,s.jsx)(t.th,{children:"Documentation"})]})}),(0,s.jsxs)(t.tbody,{children:[(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{children:(0,s.jsx)(t.code,{children:"@stencil/angular-output-target"})}),(0,s.jsx)(t.td,{children:(0,s.jsx)(t.a,{href:"https://github.com/ionic-team/stencil-ds-output-targets/releases/tag/%40stencil%2Fangular-output-target%400.5.0",children:"0.5.0"})}),(0,s.jsx)(t.td,{children:(0,s.jsx)(t.a,{href:"https://github.com/ionic-team/stencil-ds-output-targets",children:"GitHub"})}),(0,s.jsx)(t.td,{children:(0,s.jsx)(t.a,{href:"/docs/v2/angular",children:"Stencil Doc Site"})})]}),(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{children:(0,s.jsx)(t.code,{children:"@stencil/sass"})}),(0,s.jsx)(t.td,{children:(0,s.jsx)(t.a,{href:"https://github.com/ionic-team/stencil-sass/releases/tag/v2.0.3",children:"2.0.3"})}),(0,s.jsx)(t.td,{children:(0,s.jsx)(t.a,{href:"https://github.com/ionic-team/stencil-sass",children:"GitHub"})}),(0,s.jsx)(t.td,{children:(0,s.jsx)(t.a,{href:"https://github.com/ionic-team/stencil-sass",children:"GitHub README"})})]}),(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{children:(0,s.jsx)(t.code,{children:"@stencil/store"})}),(0,s.jsx)(t.td,{children:(0,s.jsx)(t.a,{href:"https://github.com/ionic-team/stencil-store/releases/tag/v2.0.0",children:"2.0.0"})}),(0,s.jsx)(t.td,{children:(0,s.jsx)(t.a,{href:"https://github.com/ionic-team/stencil-store",children:"GitHub"})}),(0,s.jsx)(t.td,{children:(0,s.jsx)(t.a,{href:"/docs/v2/stencil-store",children:"Stencil Doc Site"})})]}),(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{children:(0,s.jsx)(t.code,{children:"@stencil/react-output-target"})}),(0,s.jsx)(t.td,{children:(0,s.jsx)(t.a,{href:"https://github.com/ionic-team/stencil-ds-output-targets/releases/tag/%40stencil%2Freact-output-target%400.4.0",children:"0.4.0"})}),(0,s.jsx)(t.td,{children:(0,s.jsx)(t.a,{href:"https://github.com/ionic-team/stencil-ds-output-targets",children:"GitHub"})}),(0,s.jsx)(t.td,{children:(0,s.jsx)(t.a,{href:"/docs/v2/react",children:"Stencil Doc Site"})})]}),(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{children:(0,s.jsx)(t.code,{children:"@stencil/vue-output-target"})}),(0,s.jsx)(t.td,{children:(0,s.jsx)(t.a,{href:"https://github.com/ionic-team/stencil-ds-output-targets/releases/tag/%40stencil%2Fvue-output-target%400.7.0",children:"0.7.0"})}),(0,s.jsx)(t.td,{children:(0,s.jsx)(t.a,{href:"https://github.com/ionic-team/stencil-ds-output-targets",children:"GitHub"})}),(0,s.jsx)(t.td,{children:(0,s.jsx)(t.a,{href:"/docs/v2/vue",children:"Stencil Doc Site"})})]})]})]}),"\n",(0,s.jsx)(t.h2,{id:"need-help-upgrading",children:"Need Help Upgrading?"}),"\n",(0,s.jsxs)(t.p,{children:["Be sure to look at the Stencil ",(0,s.jsx)(t.a,{href:"https://github.com/ionic-team/stencil/blob/v3.0.0-dev/BREAKING_CHANGES.md#stencil-v300",children:"v3.0.0 Breaking Changes Guide"}),"."]}),"\n",(0,s.jsxs)(t.p,{children:["If you need help upgrading, please post a thread on the ",(0,s.jsx)(t.a,{href:"https://forum.ionicframework.com/c/stencil/21",children:"Stencil Forum"}),"."]})]})}function u(e={}){const{wrapper:t}={...(0,o.R)(),...e.components};return t?(0,s.jsx)(t,{...e,children:(0,s.jsx)(p,{...e})}):p(e)}},7227:(e,t,n)=>{n.d(t,{A:()=>r});n(96540);var s=n(34164);const o={tabItem:"tabItem_Ymn6","#":"#_ftL_"};var i=n(74848);function r({children:e,hidden:t,className:n}){return(0,i.jsx)("div",{role:"tabpanel",className:(0,s.A)(o.tabItem,n),hidden:t,children:e})}},45645:(e,t,n)=>{n.d(t,{A:()=>u});var s=n(96540),o=n(34164),i=n(24245),r=n(8626),c=n(11062);const d={tabList:"tabList__CuJ","#":"#_CEXP",tabItem:"tabItem_LNqP"};var l=n(74848);function a({className:e,block:t,selectedValue:n,selectValue:s,tabValues:r}){const c=[],{blockElementScrollPositionUntilNextRender:a}
1=(0,i.a_)(),h=e=>{const t=e.currentTarget,o=c.indexOf(t),i=r[o].value;i!==n&&(a(t),s(i))},p=e=>{let t=null;switch(e.key){case"Enter":h(e);break;case"ArrowRight":{const n=c.indexOf(e.currentTarget)+1;t=c[n]??c[0];break}case"ArrowLeft":{const n=c.indexOf(e.currentTarget)-1;t=c[n]??c[c.length-1];break}}t?.focus()};return(0,l.jsx)("ul",{role:"tablist","aria-orientation":"horizontal",className:(0,o.A)("tabs",{"tabs--block":t},e),children:r.map((({value:e,label:t,attributes:s})=>(0,l.jsx)("li",{role:"tab",tabIndex:n===e?0:-1,"aria-selected":n===e,ref:e=>c.push(e),onKeyDown:p,onClick:h,...s,className:(0,o.A)("tabs__item",d.tabItem,s?.className,{"tabs__item--active":n===e}),children:t??e},e)))})}function h({lazy:e,children:t,selectedValue:n}){const i=(Array.isArray(t)?t:[t]).filter(Boolean);if(e){const e=i.find((e=>e.props.value===n));return e?(0,s.cloneElement)(e,{className:(0,o.A)("margin-top--md",e.props.className)}):null}return(0,l.jsx)("div",{className:"margin-top--md",children:i.map(((e,t)=>(0,s.cloneElement)(e,{key:t,hidden:e.props.value!==n})))})}function p(e){const t=(0,r.u)(e);return(0,l.jsxs)("div",{className:(0,o.A)("tabs-container",d.tabList),children:[(0,l.jsx)(a,{...t,...e}),(0,l.jsx)(h,{...t,...e})]})}function u(e){const t=(0,c.default)();return(0,l.jsx)(p,{...e,children:(0,r.v)(e.children)},String(t))}},28453:(e,t,n)=>{n.d(t,{R:()=>r,x:()=>c});var s=n(96540);const o={},i=s.createContext(o);function r(e){const t=s.useContext(i);return s.useMemo((function(){return"function"==typeof e?e(t):{...t,...e}}),[t,e])}function c(e){let t;return t=e.disableParentContext?"function"==typeof e.components?e.components(o):e.components||o:r(e.components),s.createElement(i.Provider,{value:t},e.children)}}}]);
Line numbers count LF bytes from the start of the resource, as the search results do. Vendor segments are library code the classifier recognised; they are stored but not indexed. Bytes are shown as Latin1 characters, one per byte.