1"use strict";(self.webpackChunk_stencil_stencil_site=self.webpackChunk_stencil_stencil_site||[]).push([[9024],{35236:(e,t,n)=>{n.r(t),n.d(t,{assets:()=>a,contentTitle:()=>c,default:()=>p,frontMatter:()=>r,metadata:()=>d,toc:()=>h});var s=n(74848),i=n(28453),l=n(45645),o=n(7227);const r={title:"Custom Elements with Stencil",sidebar_label:"dist-custom-elements",description:"Custom Elements with Stencil",slug:"/custom-elements"},c="Custom Elements",d={id:"output-targets/custom-elements",title:"Custom Elements with Stencil",description:"Custom Elements with Stencil",source:"@site/versioned_docs/version-v4.42/output-targets/custom-elements.md",sourceDirName:"output-targets",slug:"/custom-elements",permalink:"/docs/v4.42/custom-elements",draft:!1,unlisted:!1,editUrl:"https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.42/output-targets/custom-elements.md",tags:[],version:"v4.42",frontMatter:{title:"Custom Elements with Stencil",sidebar_label:"dist-custom-elements",description:"Custom Elements with Stencil",slug:"/custom-elements"},sidebar:"docs",previous:{title:"Copy Tasks",permalink:"/docs/v4.42/copy-tasks"},next:{title:"dist",permalink:"/docs/v4.42/distribution"}},a={},h=[{value:"Config",id:"config",level:2},{value:"copy",id:"copy",level:3},{value:"customElementsExportBehavior",id:"customelementsexportbehavior",level:3},{value:"dir",id:"dir",level:3},{value:"empty",id:"empty",level:3},{value:"externalRuntime",id:"externalruntime",level:3},{value:"generateTypeDeclarations",id:"generatetypedeclarations",level:3},{value:"includeGlobalScripts",id:"includeglobalscripts",level:3},{value:"isPrimaryPackageOutputTarget",id:"isprimarypackageoutputtarget",level:3},{value:"minify",id:"minify",level:3},{value:"Making Assets Available",id:"making-assets-available",level:2},{value:"Example Bundler Configs",id:"example-bundler-configs",level:2},{value:"webpack.config.js",id:"webpackconfigjs",level:3},{value:"rollup.config.js",id:"rollupconfigjs",level:3}];function u(e){const t={a:"a",admonition:"admonition",code:"code",em:"em",h1:"h1",h2:"h2",h3:"h3",header:"header",li:"li",ol:"ol",p:"p",pre:"pre",table:"table",tbody:"tbody",td:"td",th:"th",thead:"thead",tr:"tr",...(0,i.R)(),...e.components};return(0,s.jsxs)(s.Fragment,{children:[(0,s.jsx)(t.header,{children:(0,s.jsx)(t.h1,{id:"custom-elements",children:"Custom Elements"})}),"\n",(0,s.jsxs)(t.p,{children:["The ",(0,s.jsx)(t.code,{children:"dist-custom-elements"})," output target creates custom elements that directly extend ",(0,s.jsx)(t.code,{children:"HTMLElement"})," and provides simple utility functions for easily defining these elements on the ",(0,s.jsx)(t.a,{href:"https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry",children:"Custom Element Registry"}),". This output target excels in use in frontend frameworks and projects that will handle bundling, lazy-loading, and custom element registration themselves."]}),"\n",(0,s.jsxs)(t.p,{children:["This target can be used outside of frameworks as well, if lazy-loading functionality is not required or desired. For using lazily loaded Stencil components, please refer to the ",(0,s.jsx)(t.a,{href:"/docs/v4.42/distribution",children:"dist output target"}),"."]}),"\n",(0,s.jsxs)(t.p,{children:["To generate components using the ",(0,s.jsx)(t.code,{children:"dist-custom-elements"})," output target, add it to a project's ",(0,s.jsx)(t.code,{children:"stencil.config.ts"})," file like so:"]}),"\n",(0,s.jsx)(t.pre,{children:(0,s.jsx)(t.code,{className:"language-tsx",metastring:'title="stencil.config.ts"',children:"import { Config } from '@stencil/core';\n\nexport const config: Config = {\n // Other top-level config options here\n outputTargets: [\n {\n type: 'dist-custom-elements',\n // Output target config options here\n },\n // Other output targets here\n ],\n};\n"})}),"\n",(0,s.jsx)(t.h2,{id:"config",children:"Config"}),"\n",(0,s.jsx)(t.h3,{id:"copy",children:"copy"}),"\n",(0,s.jsx)(t.p,{children:(0,s.jsxs)(t.em,{children:["default: ",(0,s.jsx)(t.code,{children:"undefined"})]})}),"\n",(0,s.jsxs)(t.p,{children:["An array of ",(0,s.jsx)(t.a,{href:"/docs/v4.42/copy-tasks",children:"copy tasks"})," to be executed during the build process."]}),"\n",(0,s.jsx)(t.h3,{id:"customelementsexportbehavior",children:"customElementsExportBehavior"}),"\n",(0,s.jsx)(t.p,{children:(0,s.jsxs)(t.em,{children:["default: ",(0,s.jsx)(t.code,{children:"'default'"})]})}),"\n",(0,s.jsxs)(t.p,{children:["By default, the ",(0,s.jsx)(t.code,{children:"dist-custom-elements"})," output target generates a single file per component, and exports each of those files individually."]}),"\n",(0,s.jsx)(t.p,{children:"In some cases, library authors may want to change this behavior, for instance to automatically define component children, provide a single file containing all component exports, etc."}),"\n",(0,s.jsxs)(t.p,{children:["This config option provides additional behaviors that will alter the default component export ",(0,s.jsx)(t.em,{children:"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';
1\n\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. This file can be used as the root module when distributing your component library, see ",(0,s.jsx)(t.a,{href:"/publishing",children:"Publishing"})," for more details."]})]})]})]}),"\n",(0,s.jsx)(t.admonition,{type:"note",children:(0,s.jsx)(t.p,{children:"At this time, components that do not use JSX cannot be automatically\ndefined. This is a known limitation of Stencil that users should be aware of."})}),"\n",(0,s.jsx)(t.h3,{id:"dir",children:"dir"}),"\n",(0,s.jsx)(t.p,{children:(0,s.jsxs)(t.em,{children:["default: ",(0,s.jsx)(t.code,{children:"'dist/components'"})]})}),"\n",(0,s.jsx)(t.p,{children:"This config option allows you to change the output directory where the compiled output for this output target will be written."}),"\n",(0,s.jsx)(t.h3,{id:"empty",children:"empty"}),"\n",(0,s.jsx)(t.p,{children:(0,s.jsxs)(t.em,{children:["default: ",(0,s.jsx)(t.code,{children:"true"})]})}),"\n",(0,s.jsxs)(t.p,{children:["Setting this flag to ",(0,s.jsx)(t.code,{children:"true"})," will remove the contents of the ",(0,s.jsx)(t.a,{href:"#dir",children:"output directory"})," between builds."]}),"\n",(0,s.jsx)(t.h3,{id:"externalruntime",children:"externalRuntime"}),"\n",(0,s.jsx)(t.p,{children:(0,s.jsxs)(t.em,{children:["default: ",(0,s.jsx)(t.code,{children:"true"})]})}),"\n",(0,s.jsxs)(t.p,{children:["Setting this flag to ",(0,s.jsx)(t.code,{children:"true"})," results in the following behaviors:"]}),"\n",(0,s.jsxs)(t.ol,{children:["\n",(0,s.jsxs)(t.li,{children:["Minification will follow what is specified in the ",(0,s.jsx)(t.a,{href:"/docs/v4.42/config#minifyjs",children:"Stencil config"}),"."]}),"\n",(0,s.jsx)(t.li,{children:"Filenames will not be hashed."}),"\n",(0,s.jsxs)(t.li,{children:["All imports from packages under ",(0,s.jsx)(t.code,{children:"@stencil/core/*"})," will be marked as external and therefore not included in the generated Rollup bundle."]}),"\n"]}),"\n",(0,s.jsxs)(t.p,{children:["Ensure that ",(0,s.jsx)(t.code,{children:"@stencil/core"})," is included in your list of dependencies if you set this option to ",(0,s.jsx)(t.code,{children:"true"}),". This is crucial to prevent any runtime errors."]}),"\n",(0,s.jsx)(t.h3,{id:"generatetypedeclarations",children:"generateTypeDeclarations"}),"\n",(0,s.jsx)(t.p,{children:(0,s.jsxs)(t.em,{children:["default: ",(0,s.jsx)(t.code,{children:"true"})]})}),"\n",(0,s.jsxs)(t.p,{children:["By default, Stencil will generate type declaration files (",(0,s.jsx)(t.code,{children:".d.ts"})," files) as a part of the ",(0,s.jsx)(t.code,{children:"dist-custom-elements"})," output target through the ",(0,s.jsx)(t.code,{children:"generateTypeDeclarations"})," field on the target options. Type declaration files will be placed in the ",(0,s.jsx)(t.code,{children:"dist/types"})," directory in the root of a Stencil project. At this time, this output destination is not able to be configured."]}),"\n",(0,s.jsxs)(t.p,{children:["Setting this flag to ",(0,s.jsx)(t.code,{children:"false"})," will not generate type declaration files for the ",(0,s.jsx)(t.code,{children:"dist-custom-elements"})," output target."]}),"\n",(0,s.jsx)(t.admonition,{type:"note",children:(0,s.jsxs)(t.p,{children:["When set to generate type declarations, Stencil respects the export behavior selected via ",(0,s.jsx)(t.code,{children:"customElementsExportBehavior"})," and generates type declarations specific to the content of the generated ",(0,s.jsx)(t.a,{href:"#dir",children:"output directory's"})," ",(0,s.jsx)(t.code,{children:"index.js"})," file."]})}),"\n",(0,s.jsx)(t.h3,{id:"includeglobalscripts",children:"includeGlobalScripts"}),"\n",(0,s.jsx)(t.p,{children:(0,s.jsxs)(t.em,{children:["default: ",(0,s.jsx)(t.code,{children:"false"})]})}),"\n",(0,s.jsxs)(t.p,{children:["Setting this flag to ",(0,s.jsx)(t.code,{children:"true"})," will include ",(0,s.jsx)(t.a,{href:"/docs/v4.42/config#globalscript",children:"global scripts"})," in the bundle and execute them once the bundle entry point in loaded."]}),"\n",(0,s.jsx)(t.h3,{id:"isprimarypackageoutputtarget",children:"isPrimaryPackageOutputTarget"}),"\n",(0,s.jsx)(t.p,{children:(0,s.jsxs)(t.em,{children:["default: ",(0,s.jsx)(t.code,{children:"false"})]})}),"\n",(0,s.jsxs)(t.p,{children:["If ",(0,s.jsx)(t.code,{children:"true"}),", this output target will be used to validate ",(0,s.jsx)(t.code,{children:"package.json"})," fields for your project's distribution. See the overview of ",(0,s.jsx)(t.a,{href:"/docs/v4.42/output-targets#primary-package-output-target-validation",children:"primary package output target validation"}),"\nfor more information."]}),"\n",(0,s.jsx)(t.h3,{id:"minify",children:"minify"}),"\n",(0,s.jsx)(t.p,{children:(0,s.jsxs)(t.em,{children:["default: ",(0,s.jsx)(t.code,{children:"false"})]})}),"\n",(0,s.jsxs)(t.p,{children:["Setting this flag to ",(0,s.jsx)(t.code,{children:"true"})," will cause file minification to follow what is specified in the ",(0,s.jsx)(t.a,{href:"/docs/v4.42/config#minifyjs",children:"Stencil config"}),". ",(0,s.jsx)(t.em,{children:"However"}),", if ",(0,s.jsx)(t.a,{href:"#externalruntime",children:(0,s.jsx)(t.code,{children:"externalRuntime"})})," is enabled, it will override this option and always result in minification being disabled."]}),"\n",(0,s.jsx)(t.h2,{id:"making-assets-available",children:"Making Assets Available"}),"\n",(0,s.jsxs)(t.p,{children:["For performance reasons, the generated bundle does not include ",(0,s.jsx)(t.a,{href:"/docs/v4.42/assets",children:"local assets"})," built within the JavaScript output,\nbut instead it's recommended to keep static assets as external files. By keeping them external this ensures they can be requested on-demand, rather\nthan either welding their content into the JS file, or adding many URLs for the bundler to add to the output.\nOne method to ensure ",(0,s.jsx)(t.a,{href:"/docs/v4.42/assets",children:"assets"})," are available to external builds and http servers is to set the asset path using ",(0,s.jsx)(t.code,{children:"setAssetPath()"}),"."]}),"\n",(0,s.jsxs)(t.p,{children:["The ",(0,s.jsx)(t.code,{children:"setAssetPath()"})," function is used to manually set the base path where static assets can be found.\nFor the lazy-loaded output target the asset path is automatically set and assets copied to the correct\nbuild directory. However, for custom elements builds, the ",(0,s.jsx)(t.code,{children:"setAssetPath(path)"})," should be\nused to customize the asset path depending on where they are found on the http server."]}),"\n",(0,s.jsxs)(t.p,{children:["If the component's script is a ",(0,s.jsx)(t.code,{children:'type="module"'}),", it's recommended to use ",(0,s.jsx)(t.code,{children:"import.meta.url"}),", such\nas ",(0,s.jsx)(t.code,{children:"setAssetPath(import.meta.url)"}),". Other options include ",(0,s.jsx)(t.code,{children:"setAssetPath(document.currentScript.src)"}),", or using a bundler's replace plugin to\ndynamically set the path at build time, such as ",(0,s.jsx)(t.code,{children:"setAssetPath(process.env.ASSET_PATH)"}),"."]}),"\n",(0,s.jsx)(t.pre,{children:(0,s.jsx)(t.code,{className:"language-tsx",children:"import { setAssetPath } from 'my-library/dist/components';\n\nsetAssetPath(document.currentScript.src);\n"})}),"\n",(0,s.jsx)(t.p,{children:"Make sure to copy the assets over to a public directory in your app. This configuration depends on how your script is bundled, or lack of\nbundling, and where your assets can be loaded from. How the files are copied to the production build directory depends on the bundler or tooling.\nThe configs below provide examples of how to do this automatically with popular bundlers."}),"\n",(0,s.jsx)(t.h2,{id:"example-bundler-configs",children:"Example Bundler C
1onfigs"}),"\n",(0,s.jsx)(t.p,{children:"Instructions for consuming the custom elements bundle vary depending on the bundler you're using. These examples will help your users consume your components with webpack and Rollup."}),"\n",(0,s.jsxs)(t.p,{children:["The following examples assume your component library is published to NPM as ",(0,s.jsx)(t.code,{children:"my-library"}),". You should change this to the name you actually publish your library with."]}),"\n",(0,s.jsx)(t.p,{children:"Users will need to install your library before importing them."}),"\n",(0,s.jsxs)(l.A,{groupId:"npm2yarn",children:[(0,s.jsx)(o.A,{value:"npm",children:(0,s.jsx)(t.pre,{children:(0,s.jsx)(t.code,{className:"language-bash",children:"npm install my-library\n"})})}),(0,s.jsx)(o.A,{value:"yarn",label:"Yarn",children:(0,s.jsx)(t.pre,{children:(0,s.jsx)(t.code,{className:"language-bash",children:"yarn add my-library\n"})})}),(0,s.jsx)(o.A,{value:"pnpm",label:"pnpm",children:(0,s.jsx)(t.pre,{children:(0,s.jsx)(t.code,{className:"language-bash",children:"pnpm add my-library\n"})})})]}),"\n",(0,s.jsx)(t.h3,{id:"webpackconfigjs",children:"webpack.config.js"}),"\n",(0,s.jsxs)(t.p,{children:["A webpack config will look something like the one below. Note how assets are copied from the library's ",(0,s.jsx)(t.code,{children:"node_module"})," folder to ",(0,s.jsx)(t.code,{children:"dist/assets"})," via the ",(0,s.jsx)(t.code,{children:"CopyPlugin"})," utility. This is important if your library includes ",(0,s.jsx)(t.a,{href:"/docs/v4.42/assets",children:"local assets"}),"."]}),"\n",(0,s.jsx)(t.pre,{children:(0,s.jsx)(t.code,{className:"language-js",children:"const path = require('path');\nconst CopyPlugin = require('copy-webpack-plugin');\n\nmodule.exports = {\n entry: './src/index.js',\n output: {\n filename: 'main.js',\n path: path.resolve(__dirname, 'dist'),\n },\n module: {\n rules: [\n {\n test: /\\.css$/i,\n use: ['style-loader', 'css-loader'],\n },\n ],\n },\n plugins: [\n new CopyPlugin({\n patterns: [\n {\n from: path.resolve(__dirname, 'node_modules/my-library/dist/my-library/assets'),\n to: path.resolve(__dirname, 'dist/assets'),\n },\n ],\n }),\n ],\n};\n"})}),"\n",(0,s.jsx)(t.h3,{id:"rollupconfigjs",children:"rollup.config.js"}),"\n",(0,s.jsxs)(t.p,{children:["A Rollup config will look something like the one below. Note how assets are copied from the library's ",(0,s.jsx)(t.code,{children:"node_module"})," folder to ",(0,s.jsx)(t.code,{children:"dist/assets"})," via the ",(0,s.jsx)(t.code,{children:"rollup-copy-plugin"})," utility. This is important if your library includes ",(0,s.jsx)(t.a,{href:"/docs/v4.42/assets",children:"local assets"}),"."]}),"\n",(0,s.jsx)(t.pre,{children:(0,s.jsx)(t.code,{className:"language-js",children:"import path from 'path';\nimport commonjs from '@rollup/plugin-commonjs';\nimport copy from 'rollup-plugin-copy';\nimport postcss from 'rollup-plugin-postcss';\nimport resolve from '@rollup/plugin-node-resolve';\n\nexport default {\n input: 'src/index.js',\n output: [{ dir: path.resolve('dist/'), format: 'es' }],\n plugins: [\n resolve(),\n commonjs(),\n postcss({\n extensions: ['.css'],\n }),\n copy({\n targets: [\n {\n src: path.resolve(__dirname, 'node_modules/my-library/dist/my-library/assets'),\n dest: path.resolve(__dirname, 'dist'),\n },\n ],\n }),\n ],\n};\n"})})]})}function p(e={}){const{wrapper:t}={...(0,i.R)(),...e.components};return t?(0,s.jsx)(t,{...e,children:(0,s.jsx)(u,{...e})}):u(e)}},7227:(e,t,n)=>{n.d(t,{A:()=>o});n(96540);var s=n(34164);const i={tabItem:"tabItem_Ymn6","#":"#_ftL_"};var l=n(74848);function o({children:e,hidden:t,className:n}){return(0,l.jsx)("div",{role:"tabpanel",className:(0,s.A)(i.tabItem,n),hidden:t,children:e})}},45645:(e,t,n)=>{n.d(t,{A:()=>p});var s=n(96540),i=n(34164),l=n(24245),o=n(8626),r=n(11062);const c={tabList:"tabList__CuJ","#":"#_CEXP",tabItem:"tabItem_LNqP"};var d=n(74848);function a({className:e,block:t,selectedValue:n,selectValue:s,tabValues:o}){const r=[],{blockElementScrollPositionUntilNextRender:a}
1=(0,l.a_)(),h=e=>{const t=e.currentTarget,i=r.indexOf(t),l=o[i].value;l!==n&&(a(t),s(l))},u=e=>{let t=null;switch(e.key){case"Enter":h(e);break;case"ArrowRight":{const n=r.indexOf(e.currentTarget)+1;t=r[n]??r[0];break}case"ArrowLeft":{const n=r.indexOf(e.currentTarget)-1;t=r[n]??r[r.length-1];break}}t?.focus()};return(0,d.jsx)("ul",{role:"tablist","aria-orientation":"horizontal",className:(0,i.A)("tabs",{"tabs--block":t},e),children:o.map((({value:e,label:t,attributes:s})=>(0,d.jsx)("li",{role:"tab",tabIndex:n===e?0:-1,"aria-selected":n===e,ref:e=>r.push(e),onKeyDown:u,onClick:h,...s,className:(0,i.A)("tabs__item",c.tabItem,s?.className,{"tabs__item--active":n===e}),children:t??e},e)))})}function h({lazy:e,children:t,selectedValue:n}){const l=(Array.isArray(t)?t:[t]).filter(Boolean);if(e){const e=l.find((e=>e.props.value===n));return e?(0,s.cloneElement)(e,{className:(0,i.A)("margin-top--md",e.props.className)}):null}return(0,d.jsx)("div",{className:"margin-top--md",children:l.map(((e,t)=>(0,s.cloneElement)(e,{key:t,hidden:e.props.value!==n})))})}function u(e){const t=(0,o.u)(e);return(0,d.jsxs)("div",{className:(0,i.A)("tabs-container",c.tabList),children:[(0,d.jsx)(a,{...t,...e}),(0,d.jsx)(h,{...t,...e})]})}function p(e){const t=(0,r.default)();return(0,d.jsx)(u,{...e,children:(0,o.v)(e.children)},String(t))}},28453:(e,t,n)=>{n.d(t,{R:()=>o,x:()=>r});var s=n(96540);const i={},l=s.createContext(i);function o(e){const t=s.useContext(l);return s.useMemo((function(){return"function"==typeof e?e(t):{...t,...e}}),[t,e])}function r(e){let t;return t=e.disableParentContext?"function"==typeof e.components?e.components(i):e.components||i:o(e.components),s.createElement(l.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.