. Defaults to `3333`. | `-p` | | `--serve` | Starts the [Integrated Dev Server](https://stenciljs.com/docs/next/dev-server)
. | | | `--stats` | Write stats about the project to `stencil-stats.json`. The stats file is written in the same location as the config. | | | `--verbose` | Logs additional information about each step of the build. | | | `--watch` | Watches files during development and triggers a rebuild when files are updated. | | `stencil docs`[](https://stenciljs.com/docs/next/cli#stencil-docs "Direct link to stencil-docs") -------------------------------------------------------------------------------------------------- Performs a one-time generation of documentation for your project. For more information on documentation generation, please see the [Documentation Generation section](https://stenciljs.com/docs/next/doc-generation) . info This command runs with dev mode enabled, which does not run a full build. As a result, documentation that needs to be built first, like CSS styles, will not be generated. You will need to run `npx stencil build --docs` to generate documentation that requires building. `stencil generate`[](https://stenciljs.com/docs/next/cli#stencil-generate "Direct link to stencil-generate") -------------------------------------------------------------------------------------------------------------- Alias: `stencil g` Starts the interactive generator for a new Stencil component. The generator will ask you for a name for your component, and whether any stylesheets or testing files should be generated. If you wish to skip the interactive generator, a component tag name may be provided on the command line: stencil generate my-new-component All components will be generated within the `src/components` folder. Within `src/components`, a directory will be created with the same name as the component tag name you provided containing the generated files. For example, if you specify `page-home` as the component tag name, the files will be generated in `src/components/page-home`: src└── components └── page-home ├── page-home.css ├── page-home.e2e.ts ├── page-home.spec.ts └── page-home.tsx It is also possible to specify one or more sub-folders to generate the component in. For example, if you specify `pages/page-home` as the component tag name, the files will be generated in `src/components/pages/page-home`: stencil generate pages/page-home The command above will result in the following directory structure: src└── components └── pages └── page-home ├── page-home.css ├── page-home.e2e.ts ├── page-home.spec.ts └── page-home.tsx `stencil help`[](https://stenciljs.com/docs/next/cli#stencil-help "Direct link to stencil-help") -------------------------------------------------------------------------------------------------- Aliases: `stencil --help`, `stencil -h` Prints various tasks that can be run and their associated flags to the terminal. `stencil test`[](https://stenciljs.com/docs/next/cli#stencil-test "Direct link to stencil-test") -------------------------------------------------------------------------------------------------- Tests a Stencil project. The flags below are the available options for the `test` command. | Flag | Description | | --- | --- | | `--spec` | Tests `.spec.ts` files using [Jest](https://jestjs.io/)
. | | `--e2e` | Tests `.e2e.ts` files using [Puppeteer](https://developers.google.com/web/tools/puppeteer)
and [Jest](https://jestjs.io/)
. | | `--no-build` | Skips the build process before running end-to-end tests. When using this flag, it is assumed that your Stencil project has been built prior to running `stencil test`. Unit tests do not require this flag. | | `--devtools` | Opens the dev tools panel in Chrome for end-to-end tests. Setting this flag will disable `--headless` | | `--headless` | Sets the headless mode to use in Chrome for end-to-end tests. `--headless` and `--headless=true` will enable the "old" headless mode in Chrome, that was used by default prior to Chrome v112. `--headless=new` will enable the new headless mode introduced in Chrome v112. See [this article](https://developer.chrome.com/articles/new-headless/)
for more information on Chrome's new headless mode. | `stencil version`[](https://stenciljs.com/docs/next/cli#stencil-version "Direct link to stencil-version") ----------------------------------------------------------------------------------------------------------- Aliases: `stencil -v`, `stencil --version` Prints the version of Stencil to the terminal. Contents -------- * [`stencil build`](https://stenciljs.com/docs/next/cli#stencil-build) * [`stencil docs`](https://stenciljs.com/docs/next/cli#stencil-docs) * [`stencil generate`](https://stenciljs.com/docs/next/cli#stencil-generate) * [`stencil help`](https://stenciljs.com/docs/next/cli#stencil-help) * [`stencil test`](https://stenciljs.com/docs/next/cli#stencil-test) * [`stencil version`](https://stenciljs.com/docs/next/cli#stencil-version) * * * [Edit this page](https://github.com/ionic-team/stencil-site/tree/main/docs/config/cli.md) --- # Stencil Core Dev Server API | Stencil [Skip to main content](https://stenciljs.com/docs/next/dev-server-api#__docusaurus_skipToContent_fallback) [An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none) This is unreleased documentation for Stencil **Next** version. For up-to-date documentation, see the **[latest version](https://stenciljs.com/docs/dev-server-api) ** (v4.35). Version: Next On this page The CLI API can be found at `@stencil/core/dev-server`. start()[](https://stenciljs.com/docs/next/dev-server-api#start "Direct link to start()") ------------------------------------------------------------------------------------------ start(stencilDevServerConfig: StencilDevServerConfig, logger: Logger, watcher?: CompilerWatcher): Promise
...
...
...
); }}
* [**h()**](https://stenciljs.com/docs/next/templating-jsx)
: It's used within the `render()` to turn the JSX into Virtual DOM elements.
* **render()**: a utility method to render a virtual DOM created by `h()` into a container.
**Type:** `(vnode: VNode, container: Element) => void` **Example:**
import { render } from '@stencil/core'const vdom = ( Hello World!
)render(vdom, document.body)
* [**readTask()**](https://developers.google.com/web/fundamentals/performance/rendering/avoid-large-complex-layouts-and-layout-thrashing)
: Schedules a DOM-read task. The provided callback will be executed in the best moment to perform DOM reads without causing layout thrashing.
**Type:** `(task: Function) => void`
* [**writeTask()**](https://developers.google.com/web/fundamentals/performance/rendering/avoid-large-complex-layouts-and-layout-thrashing)
: Schedules a DOM-write task. The provided callback will be executed in the best moment to perform DOM mutations without causing layout thrashing.
**Type:** `(task: Function) => void`
* **forceUpdate()**: Schedules a new render of the given instance or element even if no state changed. Notice `forceUpdate()` is not synchronous and might perform the DOM render in the next frame.
**Type:** `(ref: any) => void`
**Example:**
import { forceUpdate } from '@stencil/core'// inside a class component functionforceUpdate(this);
* **getAssetPath()**: Gets the path to local assets. Refer to the [Assets](https://stenciljs.com/docs/next/assets#getassetpath)
page for usage info.
**Type:** `(path: string) => string`
**Example:**
import { Component, Prop, getAssetPath, h } from '@stencil/core'@Component({ tag: 'cmp-asset',})export class CmpAsset { @Prop() icon: string; render() { return ( }){kind=icon}
); }}
* **setAssetPath()**: Sets the path for Stencil to resolve local assets. Refer to the [Assets](https://stenciljs.com/docs/next/assets#setassetpath)
page for usage info.
**Type:** `(path: string) => string`
**Example:**
import { setAssetPath } from '@stencil/core';setAssetPath(`{window.location.origin}/`);
* **setMode()**: Sets the style mode of a component. Refer to the [Styling](https://stenciljs.com/docs/next/styling#style-modes)
page for usage info.
**Type:** `((elm: HTMLElement) => string | undefined | null) => void`
**Example:**
import { setMode } from '@stencil/core'// set mode based on a propertysetMode((el) => el.getAttribute('mode'));
* **getMode()**: Get the current style mode of your application. Refer to the [Styling](https://stenciljs.com/docs/next/styling#style-modes)
page for usage info.
**Type:** `(ref: any) => string | undefined`
**Example:**
import { getMode } from '@stencil/core'getMode(this);
* **getElement()**: Retrieve a Stencil element for a given reference.
**Type:** `(ref: any) => HTMLStencilElement`
**Example:**
import { getElement } from '@stencil/core'const stencilComponent = getElement(document.querySelector('my-cmp'))if (stencilComponent) { stencilComponent.componentOnReady().then(() => { ... })}
Contents
--------
* [Decorators](https://stenciljs.com/docs/next/api#decorators)
* [Lifecycle hooks](https://stenciljs.com/docs/next/api#lifecycle-hooks)
* [componentOnReady()](https://stenciljs.com/docs/next/api#componentonready)
* [The `appload` event](https://stenciljs.com/docs/next/api#the-appload-event)
* [Other](https://stenciljs.com/docs/next/api#other)
* * *
[Edit this page](https://github.com/ionic-team/stencil-site/tree/main/docs/components/api.md)
---
# Documentation Generation Config | Stencil
[Skip to main content](https://stenciljs.com/docs/next/docs-config#__docusaurus_skipToContent_fallback)
[An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none)
This is unreleased documentation for Stencil **Next** version.
For up-to-date documentation, see the **[latest version](https://stenciljs.com/docs/docs-config)
** (v4.35).
Version: Next
On this page
The `docs` config option allows global configuration of certain behaviors related to [documentation generation output targets](https://stenciljs.com/docs/next/doc-generation)
.
note
These configurations are **global** and will be applied to all output target instances including those defined in the [`outputTargets`](https://stenciljs.com/docs/next/output-targets)
configuration, as well as those injected by CLI flags (like `--docs`).
markdown[](https://stenciljs.com/docs/next/docs-config#markdown "Direct link to markdown")
--------------------------------------------------------------------------------------------
The `markdown` config object allows certain customizations for markdown files generated by the [`docs-readme` output target](https://stenciljs.com/docs/next/docs-readme)
or the `--docs` CLI flag.
### targetComponent[](https://stenciljs.com/docs/next/docs-config#targetcomponent "Direct link to targetComponent")
**Optional**
**Default: `{ textColor: '#333', background: '#f9f' }`**
This option allows you to change the colors used when generating the dependency graph mermaid diagrams for components. Any hex color string is a valid value.
stencil.config.ts
import { Config } from '@stencil/core';export const config: Config = { docs: { markdown: { targetComponent: { textColor: '#fff', background: '#000', }, }, },};
Contents
--------
* [markdown](https://stenciljs.com/docs/next/docs-config#markdown)
* [targetComponent](https://stenciljs.com/docs/next/docs-config#targetcomponent)
* * *
[Edit this page](https://github.com/ionic-team/stencil-site/tree/main/docs/config/docs.md)
---
# Component Decorator | Stencil
[Skip to main content](https://stenciljs.com/docs/next/component#__docusaurus_skipToContent_fallback)
[An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none)
This is unreleased documentation for Stencil **Next** version.
For up-to-date documentation, see the **[latest version](https://stenciljs.com/docs/component)
** (v4.35).
Version: Next
On this page
`@Component()` is a decorator that designates a TypeScript class as a Stencil component. Every Stencil component gets transformed into a web component at build time.
import { Component } from '@stencil/core';@Component({ tag: 'todo-list', // additional options})export class TodoList { // implementation omitted}
Component Options[](https://stenciljs.com/docs/next/component#component-options "Direct link to Component Options")
---------------------------------------------------------------------------------------------------------------------
The `@Component()` decorator takes one argument, an object literal containing configuration options for the component. This allows each component to be individually configured to suit the unique needs of each project.
Each option, its type, and whether it's required is described below.
### tag[](https://stenciljs.com/docs/next/component#tag "Direct link to tag")
**Required**
**Type: `string`**
**Details:**
This value sets the name of the custom element that Stencil will generate. To adhere to the [HTML spec](https://html.spec.whatwg.org/#valid-custom-element-name)
, the tag name must contain a dash ('-').
Ideally, the tag name is a globally unique value. Having a globally unique value helps prevent naming collisions with the global `CustomElementsRegistry`, where all custom elements are defined. It's recommended to choose a unique prefix for all your components within the same collection.
**Example**:
import { Component } from '@stencil/core';@Component({ tag: 'todo-list',})export class TodoList { // implementation omitted}
After compilation, the component defined in `TodoList` can be used in HTML or another TSX file:
My favorite color is {this.color}
); }}
import { Component, h } from '@stencil/core';@Component({ tag: 'my-parent-component'})export class MyParentComponent { render() { return ( , written in Markdown files in the `usages/` directory adjacent to the current component. | | `props` | Array of metadata objects for each usage of the [`@Prop` decorator](https://stenciljs.com/docs/next/properties#the-prop-decorator-prop)
on the current component. | | `methods` | Array of metadata objects for each usage of the [`@Method` decorator](https://stenciljs.com/docs/next/methods)
on the current component. | | `events` | Array of metadata objects for each usage of the [`@Event` decorator](https://stenciljs.com/docs/next/events#event-decorator)
on the current component. | | `listeners` | Array of metadata objects for each usage of the [`@Listen` decorator](https://stenciljs.com/docs/next/events#listen-decorator)
on the current component. | | `styles` | Array of objects documenting annotated [CSS variables](https://stenciljs.com/docs/next/docs-json#css-variables)
used in the current component's CSS. | | `slots` | Array of objects documenting [slots](https://stenciljs.com/docs/next/docs-json#slots)
which are tagged with `@slot` in the current component's JSDoc comment. | | `parts` | Array of objects derived from `@part` tags in the current component's JSDoc comment. | | `dependents` | Array of components where current component is used | | `dependencies` | Array of components which is used in current component | | `dependencyGraph` | Describes a tree of components coupling | Contents -------- * [Config](https://stenciljs.com/docs/next/docs-custom#config) * [JsonDocs](https://stenciljs.com/docs/next/docs-custom#jsondocs) * [JsonDocsComponent](https://stenciljs.com/docs/next/docs-custom#jsondocscomponent) * * * [Edit this page](https://github.com/ionic-team/stencil-site/tree/main/docs/documentation-generation/docs-custom.md) --- # Content Security Policy Nonces | Stencil [Skip to main content](https://stenciljs.com/docs/next/csp-nonce#__docusaurus_skipToContent_fallback) [An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none) This is unreleased documentation for Stencil **Next** version. For up-to-date documentation, see the **[latest version](https://stenciljs.com/docs/csp-nonce) ** (v4.35). Version: Next On this page [Content Security Policies (CSPs)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) can help protect an application from Cross-Site Scripting (XSS) attacks by adding a security layer to help prevent unauthorized code from running in the browser. An application that is served with a CSP other than 'unsafe-inline' and contains web components without a Shadow DOM will likely run into errors on load. This is often first detected in the browser's console, which reports an error stating that certain styles or scripts violate the effective CSP. To resolve this issue, Stencil supports using [CSP nonces](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/nonce) in many of the output targets. caution NOTE: CSPs and some CSP strategies are not supported by certain browsers. For a more detailed list, please see the [CSP browser compatibility table](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP#browser_compatibility) . How to Use a Nonce[](https://stenciljs.com/docs/next/csp-nonce#how-to-use-a-nonce "Direct link to How to Use a Nonce") ------------------------------------------------------------------------------------------------------------------------ The actual generation of the nonce value and enforcement of the correct CSP are not the responsibility of Stencil. Instead, the server of the application will need to generate the nonce value for each page view, construct the CSP, and then correctly handle passing the generated nonce to Stencil based on which output target is being consumed. There are many resources available that walk through setting up a CSP and using the nonce behavior. [This](https://towardsdatascience.com/content-security-policy-how-to-create-an-iron-clad-nonce-based-csp3-policy-with-webpack-and-nginx-ce5a4605db90) article walks through the process using Nginx and Webpack. Obviously, these resources don't account for the Stencil specifics, but any specifics will be called out in this guide. Per the [MDN Guide on nonces](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/nonce#generating_values) , a nonce should be "a random base64-encoded string of at least 128 bits of data from a cryptographically secure random number generator". ### Output Targets[](https://stenciljs.com/docs/next/csp-nonce#output-targets "Direct link to Output Targets") Using nonces may differ slightly between output targets, so please be sure to use the correct pattern based on the context in which your Stencil components are consumed. #### Dist[](https://stenciljs.com/docs/next/csp-nonce#dist "Direct link to Dist") Consuming a `nonce` in the `dist` output target is easy using the provided `setNonce` helper function. This function is exported from the index file of the output target's designated output directory. This function simply accepts the `nonce` string value that you want set for every `style` and `script` tag. This is an example of consuming the `dist` output in an Angular app's entrypoint: // main.tsimport { defineCustomElements, setNonce } from 'my-lib/loader';// Will set the `nonce` attribute for all scripts/style tags// i.e. will run styleTag.setAttribute('nonce', 'r4nd0m')// Obviously, you should use the nonce generated by your serversetNonce('r4nd0m');// Generic Angular bootstrappingplatformBrowserDynamic() .bootstrapModule(AppModule) .catch(err => console.log(err));defineCustomElements(); #### Custom Elements[](https://stenciljs.com/docs/next/csp-nonce#custom-elements "Direct link to Custom Elements") Consuming a `nonce` in the `dist-custom-elements` output target is easy using the provided `setNonce` helper function. This function is exported from the index file of the output target's designated output directory. This function simply accepts the `nonce` string value that you want set for every `style` and `script` tag. This is an example of consuming the `dist-custom-elements` output in an Angular app's entrypoint: // main.tsimport { defineCustomElements, setNonce } from 'my-lib/dist/components';// Assume `customElementsExportBehavior: 'auto-define-custom-elements'` is setimport 'my-lib/dist/components/my-component';// Will set the `nonce` attribute for all scripts/style tags// i.e. will run styleTag.setAttribute('nonce', 'r4nd0m')// Obviously, you should use the nonce generated by your serversetNonce('r4nd0m');// Generic Angular bootstrappingplatformBrowserDynamic() .bootstrapModule(AppModule) .catch(err => console.log(err)); #### WWW[](https://stenciljs.com/docs/next/csp-nonce#www "Direct link to WWW") Unfortunately, setting `nonce` attributes gets a bit trickier when it comes to [SSR and SSG](https://stenciljs.com/docs/next/static-site-generation) . As a `nonce` needs to be unique per page view, it cannot be defined/set at build time. So, this responsibility now falls on the [hydrate app](https://stenciljs.com/docs/next/hydrate-app) 's execution of runtime code. **SSR** Since there is not an easy way (or any way) of exposing and executing helper functions to manipulate the outcome of the runtime code, Stencil has fallback behavior for pulling the `nonce` off of a `meta` tag in the DOM head. So, for SSR, your app can simply inject a `meta` element into the header _on each page request_. Yes, this does involve some manual configuration for the code served by your server. To work correctly, the created tag must be generated as follows: This isn't a security risk because, for an attacker to execute a script to pull the nonce from the meta tag, they would have needed to know the nonce _ahead_ of the script's execution. **SSG** Stencil cannot support CSP nonces with SSG. Because all of the code is generated during [pre-rendering](https://stenciljs.com/docs/next/static-site-generation#how-static-site-generation-and-prerendering-works) , Stencil doesn't generate the `style` or `script` tags at runtime. If an application wants to leverage nonces in SSG, they can build a mechanism to scrape the pre-rendered code and apply the attribute server-side before it is served to the client. Contents -------- * [How to Use a Nonce](https://stenciljs.com/docs/next/csp-nonce#how-to-use-a-nonce) * [Output Targets](https://stenciljs.com/docs/next/csp-nonce#output-targets) * * * [Edit this page](https://github.com/ionic-team/stencil-site/tree/main/docs/guides/csp-nonce.md) --- # VS Code Documentation | Stencil [Skip to main content](https://stenciljs.com/docs/next/docs-vscode#__docusaurus_skipToContent_fallback) [An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none) This is unreleased documentation for Stencil **Next** version. For up-to-date documentation, see the **[latest version](https://stenciljs.com/docs/docs-vscode) ** (v4.35). Version: Next On this page One of the core features of web components is the ability to create [custom elements](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements) , which allow developers to reuse custom functionality defined in their components. When Stencil compiles a project, it generates a custom element for each component in the project. Each of these [custom elements has an associated `tag` name](https://stenciljs.com/docs/next/component#component-options) that allows the custom element to be used in HTML files. By default, integrated development environments (IDEs) like VS Code are not aware of a project's custom elements when authoring HTML. In order to enable more intelligent features in VS Code, such as auto-completion, hover tooltips, etc., developers need to inform it of their project's custom elements. The `docs-vscode` output target tells Stencil to generate a JSON file containing this information. This is an opt-in feature and will save a JSON file containing [custom data](https://github.com/microsoft/vscode-custom-data) in a directory specified by the output target. Once the feature is enabled and VS Code is informed of the JSON file's location, HTML files can gain code editing features similar to TSX files. Enabling[](https://stenciljs.com/docs/next/docs-vscode#enabling "Direct link to Enabling") -------------------------------------------------------------------------------------------- To generate custom element information for VS Code, add the `docs-vscode` output target to your `stencil.config.ts`: import { Config } from '@stencil/core';export const config: Config = { outputTargets: [ { type: 'docs-vscode', file: 'vscode-data.json', } ]}; where `file` is the name & location of the file to be generated. By default, Stencil assumes that the file will be generated in the project's root directory. To generate the JSON file, have Stencil build your project. Configuring VS Code[](https://stenciljs.com/docs/next/docs-vscode#configuring-vs-code "Direct link to Configuring VS Code") ----------------------------------------------------------------------------------------------------------------------------- Once the `docs-vscode` output target has been enabled and the JSON file generated, VS Code needs to be informed of it. Recent versions of VS Code have a settings option named `html.customData`, which resolves to a list of JSON files to use when augmenting the default list of HTML elements. Add the path to the generated JSON file for your project's types to be added: { "html.customData": [ "./vscode-data.json" ]} Contents -------- * [Enabling](https://stenciljs.com/docs/next/docs-vscode#enabling) * [Configuring VS Code](https://stenciljs.com/docs/next/docs-vscode#configuring-vs-code) * * * [Edit this page](https://github.com/ionic-team/stencil-site/tree/main/docs/documentation-generation/docs-vscode.md) --- # Config | Stencil [Skip to main content](https://stenciljs.com/docs/next/config#__docusaurus_skipToContent_fallback) [An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none) This is unreleased documentation for Stencil **Next** version. For up-to-date documentation, see the **[latest version](https://stenciljs.com/docs/config) ** (v4.35). Version: Next On this page In most cases, the `stencil.config.ts` file does not require any customization since Stencil comes with great default values out-of-the-box. In general, it's preferred to keep the config as minimal as possible. In fact, you could even delete the `stencil.config.ts` file entirely and an app would compile just fine. But at the same time, the compiler can be configured at the lowest levels using this config. Below are the many _optional_ config properties. Example `stencil.config.ts`: import { Config } from '@stencil/core';export const config: Config = { namespace: 'MyApp', srcDir: 'src'}; buildDist[](https://stenciljs.com/docs/next/config#builddist "Direct link to buildDist") ------------------------------------------------------------------------------------------ _default: true (prod), false (dev)_ Sets whether or not Stencil will execute output targets and write output to `dist/` when `stencil build` is called. Defaults to `false` when building for development and `true` when building for production. If set to `true` then Stencil will always build all output targets, regardless of whether the build is in dev or prod mode or using watch mode. buildDist: true buildEs5[](https://stenciljs.com/docs/next/config#buildes5 "Direct link to buildEs5") --------------------------------------------------------------------------------------- Sets if the ES5 build should be generated or not. It defaults to `false`. Setting `buildEs5` to `true` will also create ES5 builds for both dev and prod modes. Setting `buildEs5` to `prod` will only build ES5 in prod mode. buildEs5: boolean | 'prod' bundles[](https://stenciljs.com/docs/next/config#bundles "Direct link to bundles") ------------------------------------------------------------------------------------ By default, Stencil will statically analyze the application and generate a component graph of how all the components are interconnected. From the component graph it is able to best decide how components should be grouped depending on their usage with one another within the app. By doing so it's able to bundle components together in order to reduce network requests. However, bundles can be manually generated using the `bundles` config. The `bundles` config is an array of objects that represent how components are grouped together in lazy-loaded bundles. This config is rarely needed as Stencil handles this automatically behind the scenes. bundles: [ { components: ['ion-button'] }, { components: ['ion-card', 'ion-card-header'] }] cacheDir[](https://stenciljs.com/docs/next/config#cachedir "Direct link to cacheDir") --------------------------------------------------------------------------------------- _default: '.stencil'_ The directory where sub-directories will be created for caching when [`enableCache`](https://stenciljs.com/docs/next/config#enablecache) is set `true` or if using [Stencil's Screenshot Connector](https://stenciljs.com/docs/next/screenshot-connector) . A Stencil config like the following: stencil.config.ts import { Config } from '@stencil/core';export const config: Config = { ..., enableCache: true, cacheDir: '.cache', testing: { screenshotConnector: 'connector.js' }} Will result in the following file structure: stencil-project-root└── .cache ├── .build <-- Where build related file caching is written | └── screenshot-cache.json <-- Where screenshot caching is written devServer[](https://stenciljs.com/docs/next/config#devserver "Direct link to devServer") ------------------------------------------------------------------------------------------ Please see the [Dev-Server docs](https://stenciljs.com/docs/next/dev-server) . docs[](https://stenciljs.com/docs/next/config#docs "Direct link to docs") --------------------------------------------------------------------------- Please see the [docs config](https://stenciljs.com/docs/next/docs-config) . enableCache[](https://stenciljs.com/docs/next/config#enablecache "Direct link to enableCache") ------------------------------------------------------------------------------------------------ _default: `true`_ Stencil will cache build results in order to speed up rebuilds. To disable this feature, set `enableCache` to `false`. enableCache: true extras[](https://stenciljs.com/docs/next/config#extras "Direct link to extras") --------------------------------------------------------------------------------- Please see the [Extras docs](https://stenciljs.com/docs/next/config-extras) . env[](https://stenciljs.com/docs/next/config#env "Direct link to env") ------------------------------------------------------------------------ _default: `{}`_ An object that can hold environment variables for your components to import and use. These variables can hold data objects depending on the environment you compile the components for. For example, let's say we want to provide an URL to our API based on a specific environment, we could provide it as such: stencil.config.ts import { Config } from '@stencil/core';export const config: Config = { ..., env: { API_BASE_URL: process.env.API_BASE_URL }} Now when you build your components with this environment variable set, you can import it in your component as follows: import { Component, h, Env, Host } from '@stencil/core';@Component({ tag: 'api-component',})export class APIComponent { async connectedCallback () { const res = await fetch(Env.API_BASE_URL) // ... }} generateExportMaps[](https://stenciljs.com/docs/next/config#generateexportmaps "Direct link to generateExportMaps") --------------------------------------------------------------------------------------------------------------------- _default: `false`_ Stencil will generate [export maps](https://nodejs.org/api/packages.html#packages_exports) that correspond with various output target outputs. This includes the root entry point based on the [primary output target](https://stenciljs.com/docs/next/output-targets#primary-package-output-target-validation) (or first eligible output target if not specified), the entry point for the lazy-loader (if using the `dist` output target), and entry points for each component (if using `dist-custom-elements`). globalScript[](https://stenciljs.com/docs/next/config#globalscript "Direct link to globalScript") --------------------------------------------------------------------------------------------------- The global script config option takes a file path as a string. The global script runs once before your library/app loads, so you can do things like setting up a connection to an external service or configuring a library you are using. The code to be executed should be placed within a default function that is exported by the global script. Ensure all of the code in the global script is wrapped in the function that is exported: export default function() { // or export default async function() initServerConnection();} note The exported function can also be `async` but be aware that this can have implications on the performance of your application as all rendering operations will be deferred until after the global script finishes. Imported methods from Stencil, such as `setMode`, `BUILD` and others, can only be accessed within the function exported by the script. They will not be available in the global scope outside of this function. import { setMode, BUILD } from '@stencil/core';// ❌ This won't work as Stencil primitives are not initialized at this point// console.log('Build mode:', BUILD.isDev);export default function() { // ✅ This works - Stencil methods are available within the exported function if (BUILD.isDev) { console.log('Development mode detected'); setMode((elm) => elm.getAttribute('mode') || 'dev'); } else { console.log('Production mode'); setMode((elm) => elm.getAttribute('mode') || 'prod'); }} globalStyle[](https://stenciljs.com/docs/next/config#globalstyle "Direct link to globalStyle") ------------------------------------------------------------------------------------------------ Stencil is traditionally used to compile many components into an app, and each component comes with its own compartmentalized styles. However, it's still common to have styles which should be "global" across all components and the website. A global CSS file is often useful to set [CSS Variables](https://stenciljs.com/docs/next/styling) . Additionally, the `globalStyle` config can be used to precompile styles with Sass, PostCSS, etc. Below is an example folder structure containing a webapp's global css file, named `app.css`. src/ components/ global/ app.css The global style config takes a file path as a string. The output from this build will go to the `buildDir`. In this example it would be saved to `www/build/app.css`. Additionally, these global styles are automatically applied to all components with shadow roots via constructable stylesheets, allowing you to style shadow DOM components directly. globalStyle: 'src/global/app.css' Check out the [styling docs](https://stenciljs.com/docs/next/styling#global-styles) of how to use global styles in your app. hashedFileNameLength[](https://stenciljs.com/docs/next/config#hashedfilenamelength "Direct link to hashedFileNameLength") --------------------------------------------------------------------------------------------------------------------------- _default: `8`_ When the `hashFileNames` config is set to `true`, and it is a production build, the `hashedFileNameLength` config is used to determine how many characters the file name's hash should be. hashedFileNameLength: 8 hashFileNames[](https://stenciljs.com/docs/next/config#hashfilenames "Direct link to hashFileNames") ------------------------------------------------------------------------------------------------------ _default: `true`_ During production builds, the content of each generated file is hashed to represent the content, and the hashed value is used as the filename. If the content isn't updated between builds, then it receives the same filename. When the content is updated, then the filename is different. By doing this, deployed apps can "forever-cache" the build directory and take full advantage of content delivery networks (CDNs) and heavily caching files for faster apps. hashFileNames: true hydratedFlag[](https://stenciljs.com/docs/next/config#hydratedflag "Direct link to hydratedFlag") --------------------------------------------------------------------------------------------------- When using the [lazy build](https://stenciljs.com/docs/distribution) Stencil has support for automatically applying a class or attribute to a component and all of its child components when they have finished hydrating. This can be used to prevent a [flash of unstyled content (FOUC)](https://en.wikipedia.org/wiki/Flash_of_unstyled_content) , a typically-undesired 'flicker' of unstyled HTML that might otherwise occur during component rendering while various components are asynchronously downloaded and rendered. By default, Stencil will add the `hydrated` CSS class to elements to indicate hydration. The `hydratedFlag` config field allows this behavior to be customized, by changing the name of the applied CSS class, setting it to use an attribute to indicate hydration, or changing which type of CSS properties and values are assigned before and after hydrating. This config can also be used to turn off this behavior by setting it to `null`. If a Stencil configuration does not supply a value for `hydratedFlag` then Stencil will automatically generate the following default configuration: const defaultHydratedFlag: HydratedFlag = { hydratedValue: 'inherit', initialValue: 'hidden', name: 'hydrated', property: 'visibility', selector: 'class',}; If `hydratedFlag` is explicitly set to `null`, Stencil will not set a default configuration and the behavior of marking hydration with a class or attribute will be disabled. hydratedFlag: null | { name?: string, selector?: 'class' | 'attribute', property?: string, initialValue?: string, hydratedValue?: string} The supported options are as follows: ### name[](https://stenciljs.com/docs/next/config#name "Direct link to name") _default: 'hydrated'_ The name which Stencil will use for the attribute or class that it sets on elements to indicate that they are hydrated. name: string ### selector[](https://stenciljs.com/docs/next/config#selector "Direct link to selector") _default: 'class'_ The way that Stencil will indicate that a component has been hydrated. When `'class'`, Stencil will set the `name` option on the element as a class, and when `'attribute'`, Stencil will similarly set the `name` option as an attribute. selector: 'class' | 'attribute' ### property[](https://stenciljs.com/docs/next/config#property "Direct link to property") _default: 'visibility'_ The CSS property used to show and hide components. This defaults to the CSS `visibility` property. Other possible CSS properties might include `display` with the `initialValue` setting as `none`, or `opacity` with the `initialValue` as `0`. Defaults to `visibility`. property: string ### initialValue[](https://stenciljs.com/docs/next/config#initialvalue "Direct link to initialValue") _default: 'hidden'_ This is the value which should be set for the property specified by `property` on all components before hydration. initialValue: string ### hydratedValue[](https://stenciljs.com/docs/next/config#hydratedvalue "Direct link to hydratedValue") _default: 'inherit'_ This is the value which should be set for the property specified by `property` on all components once they've completed hydration. hydratedValue: string invisiblePrehydration[](https://stenciljs.com/docs/next/config#invisibleprehydration "Direct link to invisiblePrehydration") ------------------------------------------------------------------------------------------------------------------------------ _default: `true`_ When `true`, `invisiblePrehydration` will visually hide components before they are hydrated by adding an automatically injected style tag to the document's head. Setting `invisiblePrehydration` to `false` will not inject the style tag into the head, allowing you to style your web components pre-hydration. note Setting `invisiblePrehydration` to `false` will cause everything to be visible when your page is loaded, causing a more prominent Flash of Unstyled Content (FOUC). However, you can style your web component's fallback content to your preference. invisiblePrehydration: true minifyCss[](https://stenciljs.com/docs/next/config#minifycss "Direct link to minifyCss") ------------------------------------------------------------------------------------------ _default: `true` in production_ When `true`, the browser CSS file will be minified. minifyJs[](https://stenciljs.com/docs/next/config#minifyjs "Direct link to minifyJs") --------------------------------------------------------------------------------------- _default: `true` in production_ When `true`, the browser JS files will be minified. Stencil uses [Terser](https://terser.org/) under-the-hood for file minification. namespace[](https://stenciljs.com/docs/next/config#namespace "Direct link to namespace") ------------------------------------------------------------------------------------------ _default: `App`_ The `namespace` config is a `string` representing a namespace for the app. For apps that are not meant to be a library of reusable components, the default of `App` is just fine. However, if the app is meant to be consumed as a third-party library, such as `Ionic`, a unique namespace is required. namespace: "Ionic" outputTargets[](https://stenciljs.com/docs/next/config#outputtargets "Direct link to outputTargets") ------------------------------------------------------------------------------------------------------ Please see the [Output Target docs](https://stenciljs.com/docs/next/output-targets) . plugins[](https://stenciljs.com/docs/next/config#plugins "Direct link to plugins") ------------------------------------------------------------------------------------ Please see the [Plugin docs](https://stenciljs.com/docs/next/plugins) . preamble[](https://stenciljs.com/docs/next/config#preamble "Direct link to preamble") --------------------------------------------------------------------------------------- _default: `undefined`_ Used to help to persist a banner or add relevant information about the resulting build, the `preamble` configuration field is a `string` that will be converted into a pinned comment and placed at the top of all emitted JavaScript files, with the exception of any emitted polyfills. Escaped newlines may be placed in the provided value for this field and will be honored by Stencil. Example: preamble: 'Built with Stencil\nCopyright (c) SomeCompanyInc.' Will generate the following comment: /*! * Built with Stencil * Copyright (c) SomeCompanyInc. */ sourceMap[](https://stenciljs.com/docs/next/config#sourcemap "Direct link to sourceMap") ------------------------------------------------------------------------------------------ _default: `true`_ When omitted or set to `true`, sourcemaps will be generated for a project. When set to `false`, sourcemaps will not be generated. sourceMap: true | false Sourcemaps create a translation between Stencil components that are written in TypeScript/JSX and the resulting JavaScript that is output by Stencil. Enabling source maps in your project allows for an improved debugging experience for Stencil components. For example, they allow external tools (such as an Integrated Development Environment) to add breakpoints directly in the original source code, which allows you to 'step through' your code line-by-line, to inspect the values held in variables, to observe logic flow, and more. Please note: Stencil will always attempt to minify a component's source code as much as possible during compilation. When `sourceMap` is enabled, it is possible that a slightly different minified result will be produced by Stencil when compared to the minified result produced when `sourceMap` is not enabled. Developers are responsible for determining whether or not they choose to serve sourcemaps in each environment their components are served and implementing their decision accordingly. srcDir[](https://stenciljs.com/docs/next/config#srcdir "Direct link to srcDir") --------------------------------------------------------------------------------- _default: `src`_ The `srcDir` config specifies the directory which should contain the source typescript files for each component. The standard for Stencil apps is to use `src`, which is the default. srcDir: 'src' taskQueue[](https://stenciljs.com/docs/next/config#taskqueue "Direct link to taskQueue") ------------------------------------------------------------------------------------------ _default: `async`_ Sets the task queue used by stencil's runtime. The task queue schedules DOM read and writes across the frames to efficiently render and reduce layout thrashing. By default, the `async` is used. It's recommended to also try each setting to decide which works best for your use-case. In all cases, if your app has many CPU intensive tasks causing the main thread to periodically lock-up, it's always recommended to try [Web Workers](https://stenciljs.com/docs/next/web-workers) for those tasks. * `congestionAsync`: DOM reads and writes are scheduled in the next frame to prevent layout thrashing. When the app is heavily tasked and the queue becomes congested it will then split the work across multiple frames to prevent blocking the main thread. However, it can also introduce unnecessary reflows in some cases, especially during startup. `congestionAsync` is ideal for apps running animations while also simultaneously executing intensive tasks which may lock-up the main thread. * `async`: DOM read and writes are scheduled in the next frame to prevent layout thrashing. During intensive CPU tasks it will not reschedule rendering to happen in the next frame. `async` is ideal for most apps, and if the app has many intensive tasks causing the main thread to lock-up, it's recommended to try [Web Workers](https://stenciljs.com/docs/next/web-workers) rather than the congestion async queue. * `immediate`: Makes writeTask() and readTask() callbacks to be executed synchronously. Tasks are not scheduled to run in the next frame, but do note there is at least one microtask. The `immediate` setting is ideal for apps that do not provide long-running and smooth animations. Like the async setting, if the app has intensive tasks causing the main thread to lock-up, it's recommended to try [Web Workers](https://stenciljs.com/docs/next/web-workers) . taskQueue: 'async' testing[](https://stenciljs.com/docs/next/config#testing "Direct link to testing") ------------------------------------------------------------------------------------ Please see the [testing config docs](https://stenciljs.com/docs/next/testing-config) . transformAliasedImportPaths[](https://stenciljs.com/docs/next/config#transformaliasedimportpaths "Direct link to transformAliasedImportPaths") ------------------------------------------------------------------------------------------------------------------------------------------------ _default: `true`_ This sets whether or not Stencil should transform [path aliases](https://www.typescriptlang.org/docs/handbook/module-resolution.html#path-mapping) set in a project's `tsconfig.json` from the assigned module aliases to resolved relative paths. This will not transform external imports (like `@stencil/core`) or relative imports (like `'../utils'`). This option applies globally and will affect all code processed by Stencil, including `.d.ts` files and spec tests. An example of path transformation could look something like the following. First, a set of `paths` aliases in `tsconfig.json`: tsconfig.json { "compilerOptions": { "paths": { "@utils": [ "../path/to/utils" ] } }} Then with the following input: src/my-module.ts import { utilFunc, UtilInterface } from '@utils'export function util(arg: UtilInterface) { utilFunc(arg)} Stencil will produce the following output: dist/my-module.js import { utilFunc } from '../path/to/utils';export function util(arg) { utilFunc(arg);} dist/my-module.d.ts import { UtilInterface } from '../path/to/utils';export declare function util(arg: UtilInterface): void; validatePrimaryPackageOutputTarget[](https://stenciljs.com/docs/next/config#validateprimarypackageoutputtarget "Direct link to validatePrimaryPackageOutputTarget") --------------------------------------------------------------------------------------------------------------------------------------------------------------------- _default: `false`_ When `true`, validation for common `package.json` fields will occur based on setting an output target's `isPrimaryPackageOutputTarget` flag. For more information on package validation, please see the [output target docs](https://stenciljs.com/docs/next/output-targets#primary-package-output-target-validation) . rollupConfig[](https://stenciljs.com/docs/next/config#rollupconfig "Direct link to rollupConfig") --------------------------------------------------------------------------------------------------- Passes custom configuration down to rollup itself. The following options can be overwritten: * `inputOptions`: [`context`](https://rollupjs.org/configuration-options/#context) , [`external`](https://rollupjs.org/configuration-options/#external) , [`moduleContext`](https://rollupjs.org/configuration-options/#modulecontext) [`treeshake`](https://rollupjs.org/configuration-options/#treeshake) * `outputOptions`: [`globals`](https://rollupjs.org/configuration-options/#output-globals) _default: `{}`_ watchIgnoredRegex[](https://stenciljs.com/docs/next/config#watchignoredregex "Direct link to watchIgnoredRegex") ------------------------------------------------------------------------------------------------------------------ _default: `[]`_ _type: `RegExp | RegExp[]`_ A regular expression (or array of regular expressions) that can be used to omit files from triggering a rebuild in watch mode. During compile-time, each file in the Stencil project will be tested against each regular expression to determine if changes to the file (or directory) should trigger a project rebuild. note If you want to ignore TS files such as `.ts`/`.js` or `.tsx`/`.jsx` extensions, these files will also need to be specified in your project's tsconfig's [`watchOptions`](https://www.typescriptlang.org/docs/handbook/configuring-watch.html#configuring-file-watching-using-a-tsconfigjson) _in addition_ to the `watchIgnoredRegex` option. For instance, if we wanted to ignore the `my-component.tsx` file, we'd specify: tsconfig.json { ..., "watchOptions": { "excludeFiles": ["src/components/my-component/my-component.tsx"] }} Contents -------- * [buildDist](https://stenciljs.com/docs/next/config#builddist) * [buildEs5](https://stenciljs.com/docs/next/config#buildes5) * [bundles](https://stenciljs.com/docs/next/config#bundles) * [cacheDir](https://stenciljs.com/docs/next/config#cachedir) * [devServer](https://stenciljs.com/docs/next/config#devserver) * [docs](https://stenciljs.com/docs/next/config#docs) * [enableCache](https://stenciljs.com/docs/next/config#enablecache) * [extras](https://stenciljs.com/docs/next/config#extras) * [env](https://stenciljs.com/docs/next/config#env) * [generateExportMaps](https://stenciljs.com/docs/next/config#generateexportmaps) * [globalScript](https://stenciljs.com/docs/next/config#globalscript) * [globalStyle](https://stenciljs.com/docs/next/config#globalstyle) * [hashedFileNameLength](https://stenciljs.com/docs/next/config#hashedfilenamelength) * [hashFileNames](https://stenciljs.com/docs/next/config#hashfilenames) * [hydratedFlag](https://stenciljs.com/docs/next/config#hydratedflag) * [name](https://stenciljs.com/docs/next/config#name) * [selector](https://stenciljs.com/docs/next/config#selector) * [property](https://stenciljs.com/docs/next/config#property) * [initialValue](https://stenciljs.com/docs/next/config#initialvalue) * [hydratedValue](https://stenciljs.com/docs/next/config#hydratedvalue) * [invisiblePrehydration](https://stenciljs.com/docs/next/config#invisibleprehydration) * [minifyCss](https://stenciljs.com/docs/next/config#minifycss) * [minifyJs](https://stenciljs.com/docs/next/config#minifyjs) * [namespace](https://stenciljs.com/docs/next/config#namespace) * [outputTargets](https://stenciljs.com/docs/next/config#outputtargets) * [plugins](https://stenciljs.com/docs/next/config#plugins) * [preamble](https://stenciljs.com/docs/next/config#preamble) * [sourceMap](https://stenciljs.com/docs/next/config#sourcemap) * [srcDir](https://stenciljs.com/docs/next/config#srcdir) * [taskQueue](https://stenciljs.com/docs/next/config#taskqueue) * [testing](https://stenciljs.com/docs/next/config#testing) * [transformAliasedImportPaths](https://stenciljs.com/docs/next/config#transformaliasedimportpaths) * [validatePrimaryPackageOutputTarget](https://stenciljs.com/docs/next/config#validateprimarypackageoutputtarget) * [rollupConfig](https://stenciljs.com/docs/next/config#rollupconfig) * [watchIgnoredRegex](https://stenciljs.com/docs/next/config#watchignoredregex) * * * [Edit this page](https://github.com/ionic-team/stencil-site/tree/main/docs/config/01-overview.md) --- # Design Systems | Stencil [Skip to main content](https://stenciljs.com/docs/next/design-systems#__docusaurus_skipToContent_fallback) [An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none) This is unreleased documentation for Stencil **Next** version. For up-to-date documentation, see the **[latest version](https://stenciljs.com/docs/design-systems) ** (v4.35). Version: Next On this page What is a Design System?[](https://stenciljs.com/docs/next/design-systems#what-is-a-design-system "Direct link to What is a Design System?") ---------------------------------------------------------------------------------------------------------------------------------------------- A Design System consists of UI components and a clearly defined visual style, released as both code implementations and design artifacts. When adopted by all product teams, a more cohesive customer experience emerges. There are several aspects that Design Systems consist of: ### Components[](https://stenciljs.com/docs/next/design-systems#components "Direct link to Components") A component is a standalone UI element designed to be reusable across many projects. Its goal is to do one thing well, while remaining abstract enough to allow for a variety of use cases. Developers can use them as building blocks to build new user experiences. One of the key benefits of reusable components is that developers don't have to worry about the core design and functionality of each component every time they use them. Examples include buttons, links, forms, input fields, and modals. ### Patterns[](https://stenciljs.com/docs/next/design-systems#patterns "Direct link to Patterns") A pattern is an opinionated use of components. Often, multiple components are combined in order to create a standardized user experience (UX). As a result, they improve both the user and developer experience. After implementing patterns, users will understand the application better and accomplish their tasks faster. When the development team understands the proper way to use components together, software applications become easier to use. Examples include saving data to the system, capturing data from forms, and filtering and analyzing data. ### Visual Language[](https://stenciljs.com/docs/next/design-systems#visual-language "Direct link to Visual Language") A cohesive company brand strengthens its value in the minds of the customer. In the context of design systems, this means defining various aspects of the visual style, including colors, typography, and icons. Defining primary, secondary, and tertiary colors helps an application stand out and is more user-friendly. The right typography ensures users are not distracted while using an app. Finally, icons increase engagement in a product and make it “pop” visually. ### Design Artifacts and Code Implementations[](https://stenciljs.com/docs/next/design-systems#design-artifacts-and-code-implementations "Direct link to Design Artifacts and Code Implementations") By leveraging the components, patterns, and visual language of the design system, designers can create design artifacts representing UI workflows. Developers refer to the artifacts as guidance for implementing the design with code. The Value of Design Systems[](https://stenciljs.com/docs/next/design-systems#the-value-of-design-systems "Direct link to The Value of Design Systems") -------------------------------------------------------------------------------------------------------------------------------------------------------- With a design system in place, its true value is revealed. The entire product development team is freed up to focus on what matters most: solving customer problems and delivering value. Additionally, the avoidance of having teams working in parallel, recreating the same UI elements over and over, has a real-world project impact in terms of reduced time to market and increased cost savings. Design systems allow project teams to work better together. Designers define a centralized “source of truth” for software application best practices which can be referenced by anyone in a product organization. Developers no longer need to spend time rethinking how to build common app scenarios, such as application search or data table grids. When the business inevitably makes changes to the design system, they can easily be applied to all projects. The end result is a better product for your users. Using Stencil to Build a Design System[](https://stenciljs.com/docs/next/design-systems#using-stencil-to-build-a-design-system "Direct link to Using Stencil to Build a Design System") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- There’s a lot that goes into creating amazing UI components. Performance, accessibility, cross-platform capabilities, and user experience (not only of the UI component itself but how it fits into the entire design system) all must be considered. These aspects take real effort to do well. Enter Stencil, a robust and highly extensible tool for building components and patterns, the building blocks of a design system. With its intentionally minimalistic tooling and API footprint, it’s simple to incorporate into your existing development workflows. It brings substantial performance out of the box by leveraging a tiny runtime. Most importantly, all UI components built with Stencil are based 100% on open web standards. ### The Importance of Open Web Standards[](https://stenciljs.com/docs/next/design-systems#the-importance-of-open-web-standards "Direct link to The Importance of Open Web Standards") By using the web components standard, supported in all modern browsers, Stencil-built UI components offer many distinct advantages for use in a design system, namely: * They work on any platform or device * They work with any front-end framework, so they can easily be used across teams and projects using different tech stacks * They facilitate the creation of one company-wide code implementation instead of one per framework or platform Learn more about why web components are ideal for design systems in [this blog post](https://blog.ionicframework.com/5-reasons-web-components-are-perfect-for-design-systems/) . ### How to Get Started[](https://stenciljs.com/docs/next/design-systems#how-to-get-started "Direct link to How to Get Started") Stencil’s out-the-box features will help you build your own library of universal UI components that will work across platforms, devices, and front-end frameworks. Review the documentation on this site to get started. Contents -------- * [What is a Design System?](https://stenciljs.com/docs/next/design-systems#what-is-a-design-system) * [Components](https://stenciljs.com/docs/next/design-systems#components) * [Patterns](https://stenciljs.com/docs/next/design-systems#patterns) * [Visual Language](https://stenciljs.com/docs/next/design-systems#visual-language) * [Design Artifacts and Code Implementations](https://stenciljs.com/docs/next/design-systems#design-artifacts-and-code-implementations) * [The Value of Design Systems](https://stenciljs.com/docs/next/design-systems#the-value-of-design-systems) * [Using Stencil to Build a Design System](https://stenciljs.com/docs/next/design-systems#using-stencil-to-build-a-design-system) * [The Importance of Open Web Standards](https://stenciljs.com/docs/next/design-systems#the-importance-of-open-web-standards) * [How to Get Started](https://stenciljs.com/docs/next/design-systems#how-to-get-started) * * * [Edit this page](https://github.com/ionic-team/stencil-site/tree/main/docs/guides/design-systems.md) --- # Ember Integration with Stencil | Stencil [Skip to main content](https://stenciljs.com/docs/next/ember#__docusaurus_skipToContent_fallback) [An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none) This is unreleased documentation for Stencil **Next** version. For up-to-date documentation, see the **[latest version](https://stenciljs.com/docs/ember) ** (v4.35). Version: Next On this page For Monorepos (recommended)[](https://stenciljs.com/docs/next/ember#for-monorepos-recommended "Direct link to For Monorepos (recommended)") --------------------------------------------------------------------------------------------------------------------------------------------- It's recommended to use the [getting started](https://stenciljs.com/docs/getting-started) docs for creating a Stencil project using the native Stencil tooling. This way, in your Ember project, you don't need to configure anything extra, and you can use Stencil components natively. For example, if using the [Ionic Framework](https://ionicframework.com/) in your Ember project: 1. Add the Ionic Framework to your app: * npm * Yarn * pnpm npm install @ionic/core yarn add @ionic/core pnpm add @ionic/core 2. Install the components from the library: app/app.js import '@ionic/core'; // installs all the components from Ionic Framework 3. Use the components anywhere: app/components/example.gjs
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. This file can be used as the root module when distributing your component library, see [Publishing](https://stenciljs.com/docs/publishing)
for more details. | note At this time, components that do not use JSX cannot be automatically defined. This is a known limitation of Stencil that users should be aware of. ### dir[](https://stenciljs.com/docs/next/custom-elements#dir "Direct link to dir") _default: `'dist/components'`_ This config option allows you to change the output directory where the compiled output for this output target will be written. ### empty[](https://stenciljs.com/docs/next/custom-elements#empty "Direct link to empty") _default: `true`_ Setting this flag to `true` will remove the contents of the [output directory](https://stenciljs.com/docs/next/custom-elements#dir) between builds. ### externalRuntime[](https://stenciljs.com/docs/next/custom-elements#externalruntime "Direct link to externalRuntime") _default: `true`_ Setting this flag to `true` results in the following behaviors: 1. Minification will follow what is specified in the [Stencil config](https://stenciljs.com/docs/next/config#minifyjs) . 2. Filenames will not be hashed. 3. All imports from packages under `@stencil/core/*` will be marked as external and therefore not included in the generated Rollup bundle. Ensure that `@stencil/core` is included in your list of dependencies if you set this option to `true`. This is crucial to prevent any runtime errors. ### generateTypeDeclarations[](https://stenciljs.com/docs/next/custom-elements#generatetypedeclarations "Direct link to generateTypeDeclarations") _default: `true`_ By default, Stencil will generate type declaration files (`.d.ts` files) as a part of the `dist-custom-elements` output target through the `generateTypeDeclarations` field on the target options. Type declaration files will be placed in the `dist/types` directory in the root of a Stencil project. At this time, this output destination is not able to be configured. Setting this flag to `false` will not generate type declaration files for the `dist-custom-elements` output target. note When set to generate type declarations, Stencil respects the export behavior selected via `customElementsExportBehavior` and generates type declarations specific to the content of the generated [output directory's](https://stenciljs.com/docs/next/custom-elements#dir) `index.js` file. ### includeGlobalScripts[](https://stenciljs.com/docs/next/custom-elements#includeglobalscripts "Direct link to includeGlobalScripts") _default: `false`_ Setting this flag to `true` will include [global scripts](https://stenciljs.com/docs/next/config#globalscript) in the bundle and execute them once the bundle entry point in loaded. ### isPrimaryPackageOutputTarget[](https://stenciljs.com/docs/next/custom-elements#isprimarypackageoutputtarget "Direct link to isPrimaryPackageOutputTarget") _default: `false`_ If `true`, this output target will be used to validate `package.json` fields for your project's distribution. See the overview of [primary package output target validation](https://stenciljs.com/docs/next/output-targets#primary-package-output-target-validation) for more information. ### minify[](https://stenciljs.com/docs/next/custom-elements#minify "Direct link to minify") _default: `false`_ Setting this flag to `true` will cause file minification to follow what is specified in the [Stencil config](https://stenciljs.com/docs/next/config#minifyjs) . _However_, if [`externalRuntime`](https://stenciljs.com/docs/next/custom-elements#externalruntime) is enabled, it will override this option and always result in minification being disabled. Making Assets Available[](https://stenciljs.com/docs/next/custom-elements#making-assets-available "Direct link to Making Assets Available") --------------------------------------------------------------------------------------------------------------------------------------------- For performance reasons, the generated bundle does not include [local assets](https://stenciljs.com/docs/next/assets) built within the JavaScript output, but instead it's recommended to keep static assets as external files. By keeping them external this ensures they can be requested on-demand, rather than either welding their content into the JS file, or adding many URLs for the bundler to add to the output. One method to ensure [assets](https://stenciljs.com/docs/next/assets) are available to external builds and http servers is to set the asset path using `setAssetPath()`. The `setAssetPath()` function is used to manually set the base path where static assets can be found. For the lazy-loaded output target the asset path is automatically set and assets copied to the correct build directory. However, for custom elements builds, the `setAssetPath(path)` should be used to customize the asset path depending on where they are found on the http server. If the component's script is a `type="module"`, it's recommended to use `import.meta.url`, such as `setAssetPath(import.meta.url)`. Other options include `setAssetPath(document.currentScript.src)`, or using a bundler's replace plugin to dynamically set the path at build time, such as `setAssetPath(process.env.ASSET_PATH)`. import { setAssetPath } from 'my-library/dist/components';setAssetPath(document.currentScript.src); 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 bundling, and where your assets can be loaded from. How the files are copied to the production build directory depends on the bundler or tooling. The configs below provide examples of how to do this automatically with popular bundlers. Example Bundler Configs[](https://stenciljs.com/docs/next/custom-elements#example-bundler-configs "Direct link to Example Bundler Configs") --------------------------------------------------------------------------------------------------------------------------------------------- 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. The following examples assume your component library is published to NPM as `my-library`. You should change this to the name you actually publish your library with. Users will need to install your library before importing them. * npm * Yarn * pnpm npm install my-library yarn add my-library pnpm add my-library ### webpack.config.js[](https://stenciljs.com/docs/next/custom-elements#webpackconfigjs "Direct link to webpack.config.js") A webpack config will look something like the one below. Note how assets are copied from the library's `node_module` folder to `dist/assets` via the `CopyPlugin` utility. This is important if your library includes [local assets](https://stenciljs.com/docs/next/assets) . const path = require('path');const CopyPlugin = require('copy-webpack-plugin');module.exports = { entry: './src/index.js', output: { filename: 'main.js', path: path.resolve(__dirname, 'dist'), }, module: { rules: [ { test: /\.css$/i, use: ['style-loader', 'css-loader'], }, ], }, plugins: [ new CopyPlugin({ patterns: [ { from: path.resolve(__dirname, 'node_modules/my-library/dist/my-library/assets'), to: path.resolve(__dirname, 'dist/assets'), }, ], }), ],}; ### rollup.config.js[](https://stenciljs.com/docs/next/custom-elements#rollupconfigjs "Direct link to rollup.config.js") A Rollup config will look something like the one below. Note how assets are copied from the library's `node_module` folder to `dist/assets` via the `rollup-copy-plugin` utility. This is important if your library includes [local assets](https://stenciljs.com/docs/next/assets) . import path from 'path';import commonjs from '@rollup/plugin-commonjs';import copy from 'rollup-plugin-copy';import postcss from 'rollup-plugin-postcss';import resolve from '@rollup/plugin-node-resolve';export default { input: 'src/index.js', output: [{ dir: path.resolve('dist/'), format: 'es' }], plugins: [ resolve(), commonjs(), postcss({ extensions: ['.css'], }), copy({ targets: [ { src: path.resolve(__dirname, 'node_modules/my-library/dist/my-library/assets'), dest: path.resolve(__dirname, 'dist'), }, ], }), ],}; Contents -------- * [Config](https://stenciljs.com/docs/next/custom-elements#config) * [copy](https://stenciljs.com/docs/next/custom-elements#copy) * [customElementsExportBehavior](https://stenciljs.com/docs/next/custom-elements#customelementsexportbehavior) * [dir](https://stenciljs.com/docs/next/custom-elements#dir) * [empty](https://stenciljs.com/docs/next/custom-elements#empty) * [externalRuntime](https://stenciljs.com/docs/next/custom-elements#externalruntime) * [generateTypeDeclarations](https://stenciljs.com/docs/next/custom-elements#generatetypedeclarations) * [includeGlobalScripts](https://stenciljs.com/docs/next/custom-elements#includeglobalscripts) * [isPrimaryPackageOutputTarget](https://stenciljs.com/docs/next/custom-elements#isprimarypackageoutputtarget) * [minify](https://stenciljs.com/docs/next/custom-elements#minify) * [Making Assets Available](https://stenciljs.com/docs/next/custom-elements#making-assets-available) * [Example Bundler Configs](https://stenciljs.com/docs/next/custom-elements#example-bundler-configs) * [webpack.config.js](https://stenciljs.com/docs/next/custom-elements#webpackconfigjs) * [rollup.config.js](https://stenciljs.com/docs/next/custom-elements#rollupconfigjs) * * * [Edit this page](https://github.com/ionic-team/stencil-site/tree/main/docs/output-targets/custom-elements.md) --- # Docs JSON Data Output Target | Stencil [Skip to main content](https://stenciljs.com/docs/next/docs-json#__docusaurus_skipToContent_fallback) [An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none) This is unreleased documentation for Stencil **Next** version. For up-to-date documentation, see the **[latest version](https://stenciljs.com/docs/docs-json) ** (v4.35). Version: Next On this page Stencil supports automatically [generating `README` files](https://stenciljs.com/docs/next/docs-readme) in your project which pull in [JSDoc comments](https://jsdoc.app/) and provide a straightforward way to document your components. If you need more flexibility, Stencil can also write documentation to a JSON file which you could use for a custom downstream documentation website. You can try this out is using the `--docs-json` CLI flag like so: stencil build --docs-json path/to/docs.json You can also add the `docs-json` output target to your project's configuration file in order to auto-generate this file every time you build: stencil.config.ts import { Config } from '@stencil/core';export const config: Config = { outputTargets: [ { type: 'docs-json', file: 'path/to/docs.json' } ]}; The JSON file output by Stencil conforms to the [`JsonDocs` interface in Stencil's public TypeScript declarations](https://github.com/ionic-team/stencil/blob/main/src/declarations/stencil-public-docs.ts) . `supplementalPublicTypes`[](https://stenciljs.com/docs/next/docs-json#supplementalpublictypes "Direct link to supplementalpublictypes") ----------------------------------------------------------------------------------------------------------------------------------------- As of Stencil v4 the JSON documentation generation functionality in Stencil supports a new configuration option, `supplementalPublicTypes`. This functionality makes it easy to automatically document types and interfaces which otherwise wouldn't be included in the documentation that Stencil generates. By default, Stencil includes extensive information about the types used in the public APIs of all your components, meaning the properties on your components decorated with `@Watch`, `@Event`, `@Prop` and so on. This makes it easy to document your components' APIs; however, if your project uses other types which aren't found in the public API of a component then those types won't be included. The new `supplementalPublicTypes` option fills in this gap by allowing you to designate a file of types which should be included in the output of the `docs-json` output target. This information will be found in a top-level property called `typeLibrary` on the JSON output and will conform to the [`JsonDocsTypeLibrary` interface in Stencil's public TypeScript declarations](https://github.com/ionic-team/stencil/blob/main/src/declarations/stencil-public-docs.ts) . Using this option could look something like this: stencil.config.ts import { Config } from '@stencil/core';export const config: Config = { outputTargets: [ { type: 'docs-json', file: 'path/to/docs.json', supplementalPublicTypes: 'src/public-interfaces.ts', } ]}; CSS Variables[](https://stenciljs.com/docs/next/docs-json#css-variables "Direct link to CSS Variables") --------------------------------------------------------------------------------------------------------- Stencil can document CSS variables if you annotate them with JSDoc-style comments in your CSS/SCSS files. If, for instance, you had a component with a CSS file like the following: src/components/my-button/my-button.css :host { /** * @prop --background: Background of the button * @prop --background-activated: Background of the button when activated * @prop --background-focused: Background of the button when focused */ --background: pink; --background-activated: aqua; --background-focused: fuchsia;} Then you'd get the following in the JSON output: Example docs-json Output [ { "name": "--background", "annotation": "prop", "docs": "Background of the button" }, { "name": "--background-activated", "annotation": "prop", "docs": "Background of the button when activated" }, { "name": "--background-focused", "annotation": "prop", "docs": "Background of the button when focused" }] If the style sheet is configured to be used with [a specific mode](https://stenciljs.com/docs/next/styling) , the mode associated with the CSS property will be provided as well: Example docs-json Output with Mode [ { "name": "--background", "annotation": "prop", "docs": "Background of the button"+ "mode": "ios", }, { "name": "--background-activated", "annotation": "prop", "docs": "Background of the button when activated"+ "mode": "ios", }, { "name": "--background-focused", "annotation": "prop", "docs": "Background of the button when focused"+ "mode": "ios", }] note This functionality works with both standard CSS and with Sass, although for the latter you'll need to have the [@stencil/sass](https://github.com/ionic-team/stencil-sass) plugin installed and configured. Slots[](https://stenciljs.com/docs/next/docs-json#slots "Direct link to Slots") --------------------------------------------------------------------------------- If one of your Stencil components makes use of [slots](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/slot) for rendering children you can document them by using the `@slot` JSDoc tag in the component's comment. For instance, if you had a `my-button` component with a slot you might document it like so: src/components/my-button/my-button.tsx import { Component, h } from '@stencil/core';/** * @slot buttonContent - Slot for the content of the button */@Component({ tag: 'my-button', styleUrl: 'my-button.css', shadow: true,})export class MyButton { render() { return }} This would show up in the generated JSON file like so: "slots": { "name": "buttonContent", "docs": "Slot for the content of the button"} caution Stencil does not check that the slots you document in a component's JSDoc comment using the `@slot` tag are actually present in the JSX returned by the component's `render` function. It is up to you as the component author to ensure the `@slot` tags on a component are kept up to date. Usage[](https://stenciljs.com/docs/next/docs-json#usage "Direct link to Usage") --------------------------------------------------------------------------------- You can save usage examples for a component in the `usage/` subdirectory within that component's directory. The content of these files will be added to the `usage` property of the generated JSON. This allows you to keep examples right next to the code, making it easy to include them in a documentation site or other downstream consumer(s) of your docs. caution Stencil doesn't check that your usage examples are up-to-date! If you make any changes to your component's API you'll need to remember to update your usage examples manually. If, for instance, you had a usage example like this: src/components/my-button/usage/my-button-usage.md # How to use `my-button`A button is often a great help in adding interactivity to an app!You could use it like this:```html
`. | |
| `inlineExternalStyleSheets` | External stylesheets from `` are instead inlined into ` * * * * ``` */
#### renderToString Options[](https://stenciljs.com/docs/v4.33/hydrate-app#rendertostring-options "Direct link to renderToString Options")
##### `approximateLineWidth`[](https://stenciljs.com/docs/v4.33/hydrate-app#approximatelinewidth "Direct link to approximatelinewidth")
**Type:** `number`
Determines when line breaks are being set when serializing the component.
##### `prettyHtml`[](https://stenciljs.com/docs/v4.33/hydrate-app#prettyhtml "Direct link to prettyhtml")
**Default:** `false`
**Type:** `boolean`
If set to `true` it prettifies the serialized HTML code, intends elements and escapes text nodes.
##### `removeAttributeQuotes`[](https://stenciljs.com/docs/v4.33/hydrate-app#removeattributequotes "Direct link to removeattributequotes")
**Type:** `boolean`
**Default:** `false`
If set to `true` it removes attribute quotes when possible, e.g. replaces `someAttribute="foo"` to `someAttribute=foo`.
##### `removeEmptyAttributes`[](https://stenciljs.com/docs/v4.33/hydrate-app#removeemptyattributes "Direct link to removeemptyattributes")
**Type:** `boolean`
**Default:** `true`
If set to `true` it removes attribute that don't have values, e.g. remove `class=""`.
##### `removeHtmlComments`[](https://stenciljs.com/docs/v4.33/hydrate-app#removehtmlcomments "Direct link to removehtmlcomments")
**Type:** `boolean`
**Default:** `false`
If set to `true` it removes any abundant HTML comments. Stencil still requires to insert hydration comments to be able to reconcile the component.
##### `beforeHydrate`[](https://stenciljs.com/docs/v4.33/hydrate-app#beforehydrate "Direct link to beforehydrate")
**Type:** `(document: Document, url: URL) => | Promise`
Allows to modify the document and all its containing components to be modified before the hydration process starts. This allows e.g. to assign properties to the components dynamically:
await renderToString(response.body, { beforeHydrate: (doc: Document) => { doc.querySelector(`my-component`).someComplexThing = new Map(...) },})
##### `afterHydrate`[](https://stenciljs.com/docs/v4.33/hydrate-app#afterhydrate "Direct link to afterhydrate")
**Type:** `(document: Document, url: URL, results: PrerenderUrlResults) => | Promise`
Allows to modify the document and all its containing components after the component was rendered in the virtual DOM and before the serialization process starts.
##### `serializeShadowRoot`[](https://stenciljs.com/docs/v4.33/hydrate-app#serializeshadowroot "Direct link to serializeshadowroot")
**Default:** `'declarative-shadow-dom'`
**Type:**
'declarative-shadow-dom' | 'scoped' | { 'declarative-shadow-dom'?: string[]; scoped?: string[]; default: 'declarative-shadow-dom' | 'scoped';} | false;
Configure how Stencil serializes a component's shadow-root:
* `declarative-shadow-dom` - all `shadow: true` components will be rendered with a [Declarative Shadow DOM](https://developer.chrome.com/docs/css-ui/declarative-shadow-dom)
.
* `scoped` - all `shadow: true` components will be rendered with Stencil's custom scoped behavior; a light-dom tree and single `` during SSR which is converted into a shadow-root during client-side hydration.
* Alternatively you can mix `scoped` and `declarative-shadow-dom` behavior, for example:
* `{ 'declarative-shadow-dom': ['tag-1'], default: 'scoped'; }` will render component `tag-1` with DSD, but all others with Stencil's scoped behavior.
* `{ 'scoped': ['tag-1'], default: 'declarative-shadow-dom'; }` will render component tag `tag-1` with Stencil's scoped behavior, but all others with DSD.
* `false`, will not render any `shadow: true` component on the server; delaying hydration until runtime.
**Declarative Shadow DOM Example:**
const results = await hydrate.renderToString( ` * * * * ``` */
**Scoped Example:**
const results = await hydrate.renderToString( ` * * * * ``` */
##### `fullDocument`[](https://stenciljs.com/docs/v4.33/hydrate-app#fulldocument "Direct link to fulldocument")
**Type:** `boolean`
**Default:** `true`
If set to `true`, Stencil will serialize a complete HTML document for a server to respond. If set to `false` it will only render the components within the given template.
Contents
--------
* [How to Use the Hydrate App](https://stenciljs.com/docs/v4.33/hydrate-app#how-to-use-the-hydrate-app)
* [hydrateDocument](https://stenciljs.com/docs/v4.33/hydrate-app#hydratedocument)
* [renderToString](https://stenciljs.com/docs/v4.33/hydrate-app#rendertostring)
* * *
[Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.33/guides/hydrate-app.md)
---
# Stencil Core CLI API | Stencil
[Skip to main content](https://stenciljs.com/docs/cli-api#__docusaurus_skipToContent_fallback)
[An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none)
Version: v4.35
On this page
The CLI API can be found at `@stencil/core/cli` and ran by `bin/stencil`.
createNodeLogger()[](https://stenciljs.com/docs/cli-api#createnodelogger "Direct link to createNodeLogger()")
---------------------------------------------------------------------------------------------------------------
createNodeLogger(process: any): Logger
Creates a "logger", based off of NodeJS APIs, that will be used by the compiler and dev-server. By default the CLI uses this method to create the NodeJS logger. The NodeJS "process" object should be provided as the first argument.
createNodeSystem()[](https://stenciljs.com/docs/cli-api#createnodesystem "Direct link to createNodeSystem()")
---------------------------------------------------------------------------------------------------------------
createNodeSystem(process: any): CompilerSystem
Creates the "system", based off of NodeJS APIs, used by the compiler. This includes any and all file system reads and writes using NodeJS. The compiler itself is unaware of Node's `fs` module. Other system APIs include any use of `crypto` to hash content. The NodeJS "process" object should be provided as the first argument.
parseFlags()[](https://stenciljs.com/docs/cli-api#parseflags "Direct link to parseFlags()")
---------------------------------------------------------------------------------------------
parseFlags(args: string[]): ConfigFlags
Used by the CLI to parse command-line arguments into a typed `ConfigFlags` object. This is an example of how it's used internally: `parseFlags(process.argv.slice(2))`.
run()[](https://stenciljs.com/docs/cli-api#run "Direct link to run()")
------------------------------------------------------------------------
run(init: CliInitOptions): Promise
Runs the CLI with the given options. This is used by Stencil's default `bin/stencil` file, but can be used externally too.
runTask()[](https://stenciljs.com/docs/cli-api#runtask "Direct link to runTask()")
------------------------------------------------------------------------------------
runTask(process: any, config: Config, task: TaskCommand, sys?: CompilerSystem): Promise
Runs individual tasks giving a NodeJS `process`, Stencil `config`, and task command. You can optionally pass in the `sys` that's used by the compiler. See [createNodeSystem()](https://stenciljs.com/docs/cli-api#createnodesystem)
for more details.
Contents
--------
* [createNodeLogger()](https://stenciljs.com/docs/cli-api#createnodelogger)
* [createNodeSystem()](https://stenciljs.com/docs/cli-api#createnodesystem)
* [parseFlags()](https://stenciljs.com/docs/cli-api#parseflags)
* [run()](https://stenciljs.com/docs/cli-api#run)
* [runTask()](https://stenciljs.com/docs/cli-api#runtask)
* * *
[Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.35/core/cli-api.md)
---
# Stencil Goals and Objectives | Stencil
[Skip to main content](https://stenciljs.com/docs/v4.34/goals-and-objectives#__docusaurus_skipToContent_fallback)
[An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none)
This is documentation for Stencil **v4.34**, which is no longer actively maintained.
For up-to-date documentation, see the **[latest version](https://stenciljs.com/docs/goals-and-objectives)
** (v4.35).
Version: v4.34
On this page
Stencil aims to combine the best concepts of the most popular frontend frameworks into a compile-time tool rather than run-time tool. It's important to stress that Stencil's goal is to _not_ become or be seen as a "framework", but rather our goal is to provide a great developer experience and tooling expected from a framework, while using web-standards within the browser at run-time. In many cases, Stencil can be used as a drop in replacement for traditional frontend frameworks given the capabilities now available in the browser, though using it as such is certainly not required.
Web Standards[](https://stenciljs.com/docs/v4.34/goals-and-objectives#web-standards "Direct link to Web Standards")
---------------------------------------------------------------------------------------------------------------------
Components generated by Stencil in the end are built on top of web components, so they work in any major framework or with no framework at all. Additionally, other standards heavily relied on include ES Modules and dynamic imports which have proven to replace traditional bundlers which add unnecessary complexities and run-time JavaScript. By using web-standards, developers can learn and adopt a standard API documented across the world, rather than custom framework APIs that continue to change.
Automatic Optimizations[](https://stenciljs.com/docs/v4.34/goals-and-objectives#automatic-optimizations "Direct link to Automatic Optimizations")
---------------------------------------------------------------------------------------------------------------------------------------------------
There are countless optimizations and tweaks developers must do to improve performance of components and websites. With a compiler, Stencil is able to analyze component code as an input, and generate optimized components as an output.
Future-Friendly[](https://stenciljs.com/docs/v4.34/goals-and-objectives#future-friendly "Direct link to Future-Friendly")
---------------------------------------------------------------------------------------------------------------------------
As the world of software development continues to evolve, so too can the compiler. Instead of requiring complete rewrites of components, the compiler can continue to make optimizations using the standard component model as the common input. The compiler allows developers to create future-friendly components, while still staying up-to-date on the latest optimizations without starting over again and again. Additionally, if something changes about any API, the compiler is able to make automatic adjustments and notify the developer exactly what needs to be updated.
Run-time Performance[](https://stenciljs.com/docs/v4.34/goals-and-objectives#run-time-performance "Direct link to Run-time Performance")
------------------------------------------------------------------------------------------------------------------------------------------
Instead of writing custom client-side JavaScript which every user needs to download and parse for the app to work, Stencil instead prefers to use the already amazing APIs built directly within the browser. These APIs include Custom Elements.
Tiny API[](https://stenciljs.com/docs/v4.34/goals-and-objectives#tiny-api "Direct link to Tiny API")
------------------------------------------------------------------------------------------------------
Stencil purposely does not come with a large custom API which needs to be learned and re-learned, but rather heavily relies on, you guessed it, web-standards. Again, our goal is to not create yet-another-framework, but rather provide tooling for developers to generate future-friendly components using APIs already baked within the browser. The smaller the API, the easier to learn, and the less that can be broken.
Framework Features During Development[](https://stenciljs.com/docs/v4.34/goals-and-objectives#framework-features-during-development "Direct link to Framework Features During Development")
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
If you haven't noticed already we think web-standards are great and offer many benefits. While using web-standards without any structure is certainly possible, and there are actually many use-cases where this would be appropriate, we found that as apps and teams scale it quickly becomes difficult to manage. Developers often gravitate to frameworks because of their great tooling, defined structure, and ability to allow developers to build apps quickly. One of the largest goals of Stencil is to be that intersection of having great framework features and first-class tooling during development but generating future-proof web-standard code, rather than custom framework specific code.
Wide Browser Support[](https://stenciljs.com/docs/v4.34/goals-and-objectives#wide-browser-support "Direct link to Wide Browser Support")
------------------------------------------------------------------------------------------------------------------------------------------
For the small minority of browsers that do not support modern browser features and APIs, Stencil will automatically polyfill them on-demand. What this means is that for browsers that already support the feature natively, they will not have to download and parse any unnecessary JavaScript. The great news is that in today's web landscape, most modern APIs are already shipping for what Stencil requires.
Contents
--------
* [Web Standards](https://stenciljs.com/docs/v4.34/goals-and-objectives#web-standards)
* [Automatic Optimizations](https://stenciljs.com/docs/v4.34/goals-and-objectives#automatic-optimizations)
* [Future-Friendly](https://stenciljs.com/docs/v4.34/goals-and-objectives#future-friendly)
* [Run-time Performance](https://stenciljs.com/docs/v4.34/goals-and-objectives#run-time-performance)
* [Tiny API](https://stenciljs.com/docs/v4.34/goals-and-objectives#tiny-api)
* [Framework Features During Development](https://stenciljs.com/docs/v4.34/goals-and-objectives#framework-features-during-development)
* [Wide Browser Support](https://stenciljs.com/docs/v4.34/goals-and-objectives#wide-browser-support)
* * *
[Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.34/introduction/02-goals-and-objectives.md)
---
# Stencil Goals and Objectives | Stencil
[Skip to main content](https://stenciljs.com/docs/v4.33/goals-and-objectives#__docusaurus_skipToContent_fallback)
[An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none)
This is documentation for Stencil **v4.33**, which is no longer actively maintained.
For up-to-date documentation, see the **[latest version](https://stenciljs.com/docs/goals-and-objectives)
** (v4.35).
Version: v4.33
On this page
Stencil aims to combine the best concepts of the most popular frontend frameworks into a compile-time tool rather than run-time tool. It's important to stress that Stencil's goal is to _not_ become or be seen as a "framework", but rather our goal is to provide a great developer experience and tooling expected from a framework, while using web-standards within the browser at run-time. In many cases, Stencil can be used as a drop in replacement for traditional frontend frameworks given the capabilities now available in the browser, though using it as such is certainly not required.
Web Standards[](https://stenciljs.com/docs/v4.33/goals-and-objectives#web-standards "Direct link to Web Standards")
---------------------------------------------------------------------------------------------------------------------
Components generated by Stencil in the end are built on top of web components, so they work in any major framework or with no framework at all. Additionally, other standards heavily relied on include ES Modules and dynamic imports which have proven to replace traditional bundlers which add unnecessary complexities and run-time JavaScript. By using web-standards, developers can learn and adopt a standard API documented across the world, rather than custom framework APIs that continue to change.
Automatic Optimizations[](https://stenciljs.com/docs/v4.33/goals-and-objectives#automatic-optimizations "Direct link to Automatic Optimizations")
---------------------------------------------------------------------------------------------------------------------------------------------------
There are countless optimizations and tweaks developers must do to improve performance of components and websites. With a compiler, Stencil is able to analyze component code as an input, and generate optimized components as an output.
Future-Friendly[](https://stenciljs.com/docs/v4.33/goals-and-objectives#future-friendly "Direct link to Future-Friendly")
---------------------------------------------------------------------------------------------------------------------------
As the world of software development continues to evolve, so too can the compiler. Instead of requiring complete rewrites of components, the compiler can continue to make optimizations using the standard component model as the common input. The compiler allows developers to create future-friendly components, while still staying up-to-date on the latest optimizations without starting over again and again. Additionally, if something changes about any API, the compiler is able to make automatic adjustments and notify the developer exactly what needs to be updated.
Run-time Performance[](https://stenciljs.com/docs/v4.33/goals-and-objectives#run-time-performance "Direct link to Run-time Performance")
------------------------------------------------------------------------------------------------------------------------------------------
Instead of writing custom client-side JavaScript which every user needs to download and parse for the app to work, Stencil instead prefers to use the already amazing APIs built directly within the browser. These APIs include Custom Elements.
Tiny API[](https://stenciljs.com/docs/v4.33/goals-and-objectives#tiny-api "Direct link to Tiny API")
------------------------------------------------------------------------------------------------------
Stencil purposely does not come with a large custom API which needs to be learned and re-learned, but rather heavily relies on, you guessed it, web-standards. Again, our goal is to not create yet-another-framework, but rather provide tooling for developers to generate future-friendly components using APIs already baked within the browser. The smaller the API, the easier to learn, and the less that can be broken.
Framework Features During Development[](https://stenciljs.com/docs/v4.33/goals-and-objectives#framework-features-during-development "Direct link to Framework Features During Development")
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
If you haven't noticed already we think web-standards are great and offer many benefits. While using web-standards without any structure is certainly possible, and there are actually many use-cases where this would be appropriate, we found that as apps and teams scale it quickly becomes difficult to manage. Developers often gravitate to frameworks because of their great tooling, defined structure, and ability to allow developers to build apps quickly. One of the largest goals of Stencil is to be that intersection of having great framework features and first-class tooling during development but generating future-proof web-standard code, rather than custom framework specific code.
Wide Browser Support[](https://stenciljs.com/docs/v4.33/goals-and-objectives#wide-browser-support "Direct link to Wide Browser Support")
------------------------------------------------------------------------------------------------------------------------------------------
For the small minority of browsers that do not support modern browser features and APIs, Stencil will automatically polyfill them on-demand. What this means is that for browsers that already support the feature natively, they will not have to download and parse any unnecessary JavaScript. The great news is that in today's web landscape, most modern APIs are already shipping for what Stencil requires.
Contents
--------
* [Web Standards](https://stenciljs.com/docs/v4.33/goals-and-objectives#web-standards)
* [Automatic Optimizations](https://stenciljs.com/docs/v4.33/goals-and-objectives#automatic-optimizations)
* [Future-Friendly](https://stenciljs.com/docs/v4.33/goals-and-objectives#future-friendly)
* [Run-time Performance](https://stenciljs.com/docs/v4.33/goals-and-objectives#run-time-performance)
* [Tiny API](https://stenciljs.com/docs/v4.33/goals-and-objectives#tiny-api)
* [Framework Features During Development](https://stenciljs.com/docs/v4.33/goals-and-objectives#framework-features-during-development)
* [Wide Browser Support](https://stenciljs.com/docs/v4.33/goals-and-objectives#wide-browser-support)
* * *
[Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.33/introduction/02-goals-and-objectives.md)
---
# Stencil - A Compiler for Web Components | Stencil
[Skip to main content](https://stenciljs.com/docs/v4.33/introduction#__docusaurus_skipToContent_fallback)
[An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none)
This is documentation for Stencil **v4.33**, which is no longer actively maintained.
For up-to-date documentation, see the **[latest version](https://stenciljs.com/docs/introduction)
** (v4.35).
Version: v4.33
On this page
Stencil: A Web Components Compiler[](https://stenciljs.com/docs/v4.33/introduction#stencil-a-web-components-compiler "Direct link to Stencil: A Web Components Compiler")
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Stencil is a compiler that generates Web Components (more specifically, Custom Elements). Stencil combines the best concepts of the most popular frameworks into a simple build-time tool.
Stencil uses TypeScript, JSX, and CSS to create standards-compliant Web Components that can be used to craft high quality component libraries.
Web Components generated with Stencil can be used with popular frameworks right out of the box. In addition, Stencil can generate framework-specific wrappers that allow Stencil components to be used with a framework-specific developer experience.
Compared with using the [Custom Elements APIs](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements)
directly, Stencil provides [convenient APIs](https://stenciljs.com/docs/v4.33/api)
which make writing fast components simpler. With a Virtual DOM, JSX, and async rendering, it is easy to create fast and powerful components which are still 100% compatible with Web Components standards. In addition to making it easier to author Custom Elements, Stencil also adds a number of key capabilities on top of Web Components, such as prerendering and objects-as-properties (instead of just strings).
The developer experience is also tuned, and comes with live reload and a small dev server baked into the compiler.
How can I use Stencil?[](https://stenciljs.com/docs/v4.33/introduction#how-can-i-use-stencil "Direct link to How can I use Stencil?")
---------------------------------------------------------------------------------------------------------------------------------------
### Design Systems & Component Libraries[](https://stenciljs.com/docs/v4.33/introduction#design-systems--component-libraries "Direct link to Design Systems & Component Libraries")
Stencil's primary objective is providing amazing tools for design systems and component libraries. Components as a concept provide similar language for engineers and designers to have productive conversations about design implementation. [Visit the Stencil for Design Systems page to learn more.](https://stenciljs.com/docs/v4.33/design-systems)
The History of Stencil[](https://stenciljs.com/docs/v4.33/introduction#the-history-of-stencil "Direct link to The History of Stencil")
----------------------------------------------------------------------------------------------------------------------------------------
Stencil was originally created by the **[Ionic Framework](http://ionicframework.com/)
** team in order to build faster, more capable components that worked across every major framework.
The emergence of Progressive Web Apps as a rapidly growing target for web developers demanded a different approach to web app development performance. With Ionic's classic use of traditional frameworks and bundling techniques, the team was struggling to meet latency and code size demands for Progressive Web Apps that ran equally well on fast and slow networks, across a diversity of platforms and devices.
Additionally, framework fragmentation had created a web development interoperability nightmare, where components built for one framework didn't work with another framework.
Web Components offered a solution to both problems, pushing more work to the browser for better performance, and targeting a standards-based component model that all frameworks could use.
Web Components by themselves, however, weren't enough. Building fast web apps required innovations that were previously locked up inside of traditional web frameworks. Stencil was built to pull these features out of traditional frameworks and bring them to the fast emerging Web Component standard. While Stencil is intended to be used primarily to build design systems and component libraries, these innovations allowed entire applications to be built using only Stencil.
Contents
--------
* [Stencil: A Web Components Compiler](https://stenciljs.com/docs/v4.33/introduction#stencil-a-web-components-compiler)
* [How can I use Stencil?](https://stenciljs.com/docs/v4.33/introduction#how-can-i-use-stencil)
* [Design Systems & Component Libraries](https://stenciljs.com/docs/v4.33/introduction#design-systems--component-libraries)
* [The History of Stencil](https://stenciljs.com/docs/v4.33/introduction#the-history-of-stencil)
* * *
[Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.33/introduction/01-overview.md)
---
# Functional Components | Stencil
[Skip to main content](https://stenciljs.com/docs/v4.33/functional-components#__docusaurus_skipToContent_fallback)
[An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none)
This is documentation for Stencil **v4.33**, which is no longer actively maintained.
For up-to-date documentation, see the **[latest version](https://stenciljs.com/docs/functional-components)
** (v4.35).
Version: v4.33
On this page
Functional components are quite different to normal Stencil web components because they are a part of Stencil's JSX compiler. A functional component is basically a function that takes an object of props and turns it into JSX.
const Hello = props =>
Stencil provides a `FunctionalComponent` generic type that allows to specify an interface for the component's properties.
// Hello.tsximport { FunctionalComponent, h } from '@stencil/core';interface HelloProps { name: string;}export const Hello: FunctionalComponent = ({ name }) => (
* * Hello, World! I'm Stencil 'Don't call me a framework' JS *
* * * * * Hello, World! I'm Stencil 'Don't call me a framework' JS *
* * * * * Hello, World! I'm Stencil 'Don't call me a framework' JS *
* Hello, {props.name}!
; When the JSX transpiler encounters such a component, it will take its attributes, pass them into the function as the `props` object, and replace the component with the JSX that is returned by the function.Hello, {props.name}
, children]; The JSX transpiler passes all child elements of the component as an array into the function's `children` argument.I'm a child element.
Hello, {name}!
); Working with children[](https://stenciljs.com/docs/v4.33/functional-components#working-with-children "Direct link to Working with children") ---------------------------------------------------------------------------------------------------------------------------------------------- The second argument of a functional component receives the passed children, but in order to work with them, `FunctionalComponent` provides a utils object that exposes a `map()` method to transform the children, and a `forEach()` method to read them. Reading the `children` array is not recommended since the stencil compiler can rename the vNode properties in prod mode. export interface FunctionalUtilities { forEach: (children: VNode[], cb: (vnode: ChildNode, index: number, array: ChildNode[]) => void) => void; map: (children: VNode[], cb: (vnode: ChildNode, index: number, array: ChildNode[]) => ChildNode) => VNode[];}export interface ChildNode { vtag?: string | number | Function; vkey?: string | number; vtext?: string; vchildren?: VNode[]; vattrs?: any; vname?: string;} **Example:** export const AddClass: FunctionalComponent = (_, children, utils) => ( utils.map(children, child => ({ ...child, vattrs: { ...child.vattrs, class: `${child.vattrs.class} add-class` } } ))); note When using a functional component in JSX, its name must start with a capital letter. Therefore it makes sense to export it as such. Disclaimer[](https://stenciljs.com/docs/v4.33/functional-components#disclaimer "Direct link to Disclaimer") ------------------------------------------------------------------------------------------------------------- There are a few major differences between functional components and class components. Since functional components are just syntactic sugar within JSX, they... * aren't compiled into web components, * don't create a DOM node, * don't have a Shadow DOM or scoped styles, * don't have lifecycle hooks, * are stateless. When deciding whether to use functional components, one concept to keep in mind is that often the UI of your application can be a function of its state, i. e., given the same state, it always renders the same UI. If a component has to hold state, deal with events, etc, it should probably be a class component. If a component's purpose is to simply encapsulate some markup so it can be reused across your app, it can probably be a functional component (especially if you're using a component library and thus don't need to style it). caution Stencil does not support re-exporting a functional component from a "barrel file" and dynamically rendering it in another component. This is a [known limitation](https://github.com/ionic-team/stencil/issues/5246) within Stencil. Instead, either use class components and remove the import or import the functional component directly. Contents -------- * [Working with children](https://stenciljs.com/docs/v4.33/functional-components#working-with-children) * [Disclaimer](https://stenciljs.com/docs/v4.33/functional-components#disclaimer) * * * [Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.33/components/functional-components.md) --- # Prerender Config | Stencil [Skip to main content](https://stenciljs.com/docs/v4.34/prerender-config#__docusaurus_skipToContent_fallback) [An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none) This is documentation for Stencil **v4.34**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](https://stenciljs.com/docs/prerender-config) ** (v4.35). Version: v4.34 On this page As of `1.13.0`, the optional prerender config can be used while prerendering a `www` output target. The `prerender.config.ts` file can further update the parsed document of each page, before it is serialized to HTML. Within `stencil.config.ts`, set the path to the prerendering config file path using the `prerenderConfig` property, such as: import { Config } from '@stencil/core';export const config: Config = { outputTargets: [ { type: 'www', baseUrl: 'https://stenciljs.com/', prerenderConfig: './prerender.config.ts', } ]}; Next, inside of the `prerender.config.ts` file, it should export a `config` object using the `PrerenderConfig` interface. import { PrerenderConfig } from '@stencil/core';export const config: PrerenderConfig = { ...}; | Config | Description | Default | | --- | --- | --- | | `afterHydrate(document, url)` | Run after each `document` is hydrated, but before it is serialized into an HTML string. Hook is passed the `document` and its `URL`. | | | `beforeHydrate(document, url)` | Run before each `document` is hydrated. Hook is passed the `document` it's `URL`. | | | `afterSerializeTemplate(html)` | Runs after the template Document object has serialize into an HTML formatted string. Returns an HTML string to be used as the base template for all prerendered pages. | | | `beforeSerializeTemplate(document)` | Runs before the template Document object is serialize into an HTML formatted string. Returns the Document to be serialized which will become the base template html for all prerendered pages. | | | `canonicalUrl(url)` | A hook to be used to generate the canonical `` tag which goes in the `` of every prerendered page. Returning `null` will not add a canonical url tag to the page. | | | `crawlUrls` | While prerendering, crawl same-origin URLs found within `` elements. | `true` | | `entryUrls` | URLs to start the prerendering from. By default the root URL of `/` is used. | `['/']` | | `filterAnchor(attrs, base)` | Return `true` the given `` element should be crawled or not. | | | `filterUrl(url, base)` | Return `true` if the given URL should be prerendered or not. | | | `filePath(url, filePath)` | Returns the file path which the prerendered HTML content should be written to. | | | `hydrateOptions(url)` | Returns the hydrate options to use for each individual prerendered page. | | | `loadTemplate(filePath)` | Returns the template file's content. The template is the base HTML used for all prerendered pages. | | | `normalizeUrl(href, base)` | Used to normalize the page's URL from a given a string and the current page's base URL. Largely used when reading an anchor's `href` attribute value and normalizing it into a `URL`. | | | `staticSite` | Static Site Generated (SSG). Does not include Stencil's client-side JavaScript, custom elements or preload modules. | `false` | | `trailingSlash` | If the prerendered URLs should have a trailing "/"" or not | `false` | Individual Page Hydrate Options[](https://stenciljs.com/docs/v4.34/prerender-config#individual-page-hydrate-options "Direct link to Individual Page Hydrate Options") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- Beyond settings for the entire prerendering process with `prerender.config.ts`, you can also set individual hydrate options per each page. The `hydrateOptions(url)` hook can be used to further configure each page. Below is an example of the prerender config with the `hydrateOptions()` hook, which returns options for each page. import { PrerenderConfig } from '@stencil/core';export const config: PrerenderConfig = { hydrateOptions(url) { return { prettyHtml: true }; }}; | Option | Description | Default | | --- | --- | --- | | `addModulePreloads` | Adds `` for modules that will eventually be requested. | `true` | | `approximateLineWidth` | Sets an approximate line width the HTML should attempt to stay within. Note that this is "approximate", in that HTML may often not be able to be split at an exact line width. Additionally, new lines created is where HTML naturally already has whitespace, such as before an attribute or spaces between words. | `100` | | `canonicalUrl` | Sets the `href` attribute on the `` tag within the ``. If the value is not defined it will ensure a canonical link tag is no included in the ``. | | | `clientHydrateAnnotations` | Include the HTML comments and attributes used by the client-side JavaScript to read the structure of the HTML and rebuild each component. | `true` | | `constrainTimeouts` | Constrain `setTimeout()` to 1ms, but still async. Also only allows `setInterval()` to fire once, also constrained to 1ms. | `true` | | `cookie` | Sets `document.cookie`. | | | `direction` | Sets the `dir` attribute on the top level ``. | | | `excludeComponents` | Component tag names listed here will not be prerendered, nor will hydrated on the client-side. Components listed here will be ignored as custom elements and treated no differently than a ``. | |
| `inlineExternalStyleSheets` | External stylesheets from `` are instead inlined into `
| `string` | `undefined` | The properties section will be placed after the [usage examples section](https://stenciljs.com/docs/docs-readme#usage-examples) of the README. If a component does not use the `@Prop()` decorator, this section will be omitted from the generated README. ### @Event() Details[](https://stenciljs.com/docs/docs-readme#event-details "Direct link to @Event() Details") Usages of Stencil's [`@Event()` decorator](https://stenciljs.com/docs/events) are described in a table containing the following information for each usage of `@Event()`: * **Event**: The name of the property on the TypeScript class decorated with `@Event()`. * **Description**: A description of the property, if one was given in a JSDoc comment for the property. * **Type**: The TypeScript type of the property. For the following usages of `@Event()` in a component: export class MyComponent { /** * Emitted when an event is completed */ @Event() todoCompleted: EventEmitter; /** * @deprecated */ @Event() todoUndo: EventEmitter; // ...}
The following section will be generated:
## Events| Event | Description | Type || --------------- | ---------------------------------------------------------- | --------------------- || `todoCompleted` | Emitted when an event is completed | `CustomEvent` || `todoUndo` | **[DEPRECATED]**
| `CustomEvent` |
The events section will be placed after the [@Prop() section](https://stenciljs.com/docs/docs-readme#prop-details)
of the README.
If a component does not use the `@Event()` decorator, this section will be omitted from the generated README.
### @Method() Details[](https://stenciljs.com/docs/docs-readme#method-details "Direct link to @Method() Details")
Components that use Stencil's [`@Method()` decorator](https://stenciljs.com/docs/methods)
will have a section describing each usage `@Method`.
Each usage of `@Method` will be documented with its own subsection containing the following:
* The method signature will be used as the heading for each subsection
* A description of the method will immediately follow, if one was provided in a JSDoc
* A 'Parameters' section that contains a table the describes the name, TypeScript type, and description of each parameter of the method
* A 'Returns' section that contains the return type of the method, along with a description of the returned value.
For the following usages of `@Method()` in a component:
export class MyComponent { /** * Scroll by a specified X/Y distance in the component. * * @param x The amount to scroll by on the horizontal axis. * @param y The amount to scroll by on the vertical axis. * @param duration The amount of time to take scrolling by that amount. * @returns the total distance travelled */ @Method() async scrollByPoint(x: number, y: number, duration: number): Promise { /* omitted */ } // ...}
The following section will be generated:
## Methods### `scrollByPoint(x: number, y: number, duration: number) => Promise`Scroll by a specified X/Y distance in the component.#### Parameters| Name | Type | Description || ---------- | -------- | ---------------------------------------------------- || `x` | `number` | The amount to scroll by on the horizontal axis. || `y` | `number` | The amount to scroll by on the vertical axis. || `duration` | `number` | The amount of time to take scrolling by that amount. |#### ReturnsType: `Promise`the total distance travelled
The methods section will be placed after the [@Event section](https://stenciljs.com/docs/docs-readme#event-details)
of the README.
If a component does not use the `@Method()` decorator, this section will be omitted from the generated README.
### @slot Details[](https://stenciljs.com/docs/docs-readme#slot-details "Direct link to @slot Details")
A component that uses [slots](https://stenciljs.com/docs/templating-jsx#slots)
may describe its slots in the component's JSDoc using the Stencil-specific `@slot` JSDoc tag. The `@slot` tag follows the following format:
@slot [slot-name] - [description]
where `slot-name` corresponds to the name of the slot in the markup, and `description` describes the usage of the slot.
For this JSDoc tag to be read properly, the following is required:
1. Either `slot-name` or `description` must be included. Both may be included though.
2. The '-' separating the two is required.
For the default slot, omit the `slot-name`.
This information is presented in a table containing the following columns:
* **Slot**: The name of the slot. The default slot will have no name/be empty.
* **Description**: A description of the slot, if one was given.
For the following usages of `@slot()` in a component:
/** * @slot - Content is placed between the named slots if provided without a slot. * @slot primary - Content is placed to the left of the main slotted-in text. * @slot secondary - Content is placed to the right of the main slotted-in text. */@Component({ tag: 'my-component', shadow: true,})export class MyComponent { // ... render() { return ( ); }}
The following table is generated:
## Slots| Slot | Description || ------------- | --------------------------------------------------------------------- || | Content is placed between the named slots if provided without a slot. || `"primary"` | Content is placed to the left of the main slotted-in text. || `"secondary"` | Content is placed to the right of the main slotted-in text. |
The slots section will be placed after the [@Method section](https://stenciljs.com/docs/docs-readme#method-details)
of the README.
If a component's top-level JSDoc does not use `@slot` tags, this section will be omitted from the generated README.
### Shadow Parts[](https://stenciljs.com/docs/docs-readme#shadow-parts "Direct link to Shadow Parts")
A component that uses [CSS shadow parts](https://stenciljs.com/docs/styling#css-parts)
may describe the component's shadow parts in the component's JSDoc using the Stencil-specific `@part` JSDoc tag. The `@part` tag follows the following format:
@part [part-name] - [description]
where `part-name` corresponds to the name of the shadow part in the markup, and `description` describes its usage.
For this tag to be read properly, the following is required:
1. Either `part-name` or `description` must be included, although using both is strongly encouraged.
2. The '-' separating the two is required.
This information is presented in a table containing the following columns:
* **Part**: The name of the shadow part.
* **Description**: A description of the shadow part, if one was given.
For the following usages of `@part()` in a component:
/** * @part label - The label text describing the component. */@Component({ tag: 'my-component', styleUrl: 'my-component.css', shadow: true,})export class MyComponent { // ... render() { return ( ` example above we use the [`setFormValue`](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/setFormValue)
method to set a value in the surrounding form. This will read the `name` attribute off of the element and use it when setting the value, so the value typed by a user into the `input` will added to the form under the `"my-custom-input"` name.
This example just scratches the surface, and a great deal more is possible with the `ElementInternals` API, including [setting the element's validity](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/setValidity)
, reading the validity state of the form, reading other form values, and more.
Lifecycle Callbacks[](https://stenciljs.com/docs/v4.33/form-associated#lifecycle-callbacks "Direct link to Lifecycle Callbacks")
----------------------------------------------------------------------------------------------------------------------------------
Stencil allows developers building form-associated custom elements to define a [standard series of lifecycle callbacks](https://html.spec.whatwg.org/multipage/custom-elements.html#custom-element-reactions)
which enable their components to react dynamically to events in their lifecycle. These could allow fetching data when a form loads, changing styles when a form's `disabled` state is toggled, resetting form data cleanly, and more.
### `formAssociatedCallback`[](https://stenciljs.com/docs/v4.33/form-associated#formassociatedcallback "Direct link to formassociatedcallback")
This callback is called when the browser both associates the element with and disassociates the element from a form element. The function is called with the form element as an argument. This could be used to set an `ariaLabel` when the form is ready to use, like so:
src/components/form-associated-cb.tsx
import { Component, h, AttachInternals } from '@stencil/core';@Component({ tag: 'form-associated', formAssociated: true,})export class FormAssociatedCmp { @AttachInternals() internals: ElementInternals; formAssociatedCallback(form) { form.ariaLabel = 'formAssociated called'; } render() { return ; }}
### `formDisabledCallback`[](https://stenciljs.com/docs/v4.33/form-associated#formdisabledcallback "Direct link to formdisabledcallback")
This is called whenever the `disabled` state on the element _changes_. This could be used to keep a CSS class in sync with the disabled state, like so:
src/components/form-disabled-cb.tsx
import { Component, h, State } from '@stencil/core';@Component({ tag: 'form-disabled-cb', formAssociated: true,})export class MyComponent { @State() cssClass: string = ""; formDisabledCallback(disabled: boolean) { if (disabled) { this.cssClass = "background-mode"; } else { this.cssClass = ""; } } render() { return }}
### `formResetCallback`[](https://stenciljs.com/docs/v4.33/form-associated#formresetcallback "Direct link to formresetcallback")
This is called when the form is reset, and should be used to reset the form-associated component's internal state and validation. For example, you could do something like the following:
src/components/form-reset-cb.tsx
import { Component, h, AttachInternals } from '@stencil/core';@Component({ tag: 'form-reset-cb', formAssociated: true,})export class MyComponent { @AttachInternals() internals: ElementInternals; formResetCallback() { this.internals.setValidity({}); this.internals.setFormValue(""); } render() { return }}
### `formStateRestoreCallback`[](https://stenciljs.com/docs/v4.33/form-associated#formstaterestorecallback "Direct link to formstaterestorecallback")
This method will be called in the event that the browser automatically fills out your form element, an event that could take place in two different scenarios. The first is that the browser can restore the state of an element after navigating or restarting, and the second is that an input was made using a form auto-filling feature.
In either case, in order to correctly reset itself your form-associated component will need the previously selected value, but other state may also be necessary. For instance, the form value to be submitted for a date picker component would be a specific date, but in order to correctly restore the component's visual state it might also be necessary to know whether the picker should display a week or month view.
The [`setFormValue`](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/setFormValue)
method on `ElementInternals` provides some support for this use-case, allowing you to submit both a _value_ and a _state_, where the _state_ is not added to the form data sent to the server but could be used for storing some client-specific state. For instance, a pseudocode sketch of a date picker component that correctly restores whether the 'week' or 'month' view is active could look like:
src/components/fa-date-picker.tsx
import { Component, h, State, AttachInternals } from '@stencil/core';@Component({ tag: 'fa-date-picker', formAssociated: true,})export class MyDatePicker { @State() value: string = ""; @State() view: "weeks" | "months" = "weeks"; @AttachInternals() internals: ElementInternals; onInputChange(e) { e.preventDefault(); const date = e.target.value; this.setValue(date); } setValue(date: string) { // second 'state' parameter is used to store both // the input value (`date`) _and_ the current view this.internals.setFormValue(date, `${date}#${this.view}`); } formStateRestoreCallback(state, _mode) { const [date, view] = state.split("#"); this.view = view; this.setValue(date); } render() { return ;}
; componentWillLoad() { this.parseMyObjectProp(this.myObject); this.parseMyArrayProp(this.myArray); } @Watch('myObject') parseMyObjectProp(newValue: string) { if (newValue) this.myInnerObject = JSON.parse(newValue); } @Watch('myArray') parseMyArrayProp(newValue: string) { if (newValue) this.myInnerArray = JSON.parse(newValue); }}
; todoCompletedHandler(todo: Todo) { this.todoCompleted.emit(todo); }}
The code above will dispatch a custom DOM event called `todoCompleted`.
The `Event(opts: EventOptions)` decorator optionally accepts an options object to shape the behavior of dispatched events. The options and defaults are described below.
export interface EventOptions { /** * A string custom event name to override the default. */ eventName?: string; /** * A Boolean indicating whether the event bubbles up through the DOM or not. */ bubbles?: boolean; /** * A Boolean indicating whether the event is cancelable. */ cancelable?: boolean; /** * A Boolean value indicating whether or not the event can bubble across the boundary between the shadow DOM and the regular DOM. */ composed?: boolean;}
Example:
import { Event, EventEmitter } from '@stencil/core';...export class TodoList { // Event called 'todoCompleted' that is "composed", "cancellable" and it will bubble up! @Event({ eventName: 'todoCompleted', composed: true, cancelable: true, bubbles: true, }) todoCompleted: EventEmitter; todoCompletedHandler(todo: Todo) { const event = this.todoCompleted.emit(todo); if(!event.defaultPrevented) { // if not prevented, do some default handling code } }}
note
In the case where the Stencil `Event` type conflicts with the native web `Event` type, there are two possible solutions:
1. Import aliasing:
import { Event as StencilEvent, EventEmitter } from '@stencil/core';@StencilEvent() myEvent: EventEmitter<{value: string, ev: Event}>;
2. Namespace the native web `Event` type with `globalThis`:
@Event() myEvent: EventEmitter<{value: string, ev: globalThis.Event}>;
Listen Decorator[](https://stenciljs.com/docs/v4.34/events#listen-decorator "Direct link to Listen Decorator")
----------------------------------------------------------------------------------------------------------------
The `Listen()` decorator is for listening to DOM events, including the ones dispatched from `@Events`. The event listeners are automatically added and removed when the component gets added or removed from the DOM.
In the example below, assume that a child component, `TodoList`, emits a `todoCompleted` event using the `EventEmitter`.
import { Listen } from '@stencil/core';...export class TodoApp { @Listen('todoCompleted') todoCompletedHandler(event: CustomEvent) { console.log('Received the custom todoCompleted event: ', event.detail); }}
### Listen's options[](https://stenciljs.com/docs/v4.34/events#listens-options "Direct link to Listen's options")
The `@Listen(eventName, opts?: ListenOptions)` includes a second optional argument that can be used to configure how the DOM event listener is attached.
export interface ListenOptions { target?: 'body' | 'document' | 'window'; capture?: boolean; passive?: boolean;}
The available options are `target`, `capture` and `passive`:
#### target[](https://stenciljs.com/docs/v4.34/events#target "Direct link to target")
Handlers can also be registered for an event other than the host itself. The `target` option can be used to change where the event listener is attached, this is useful for listening to application-wide events.
In the example below, we're going to listen for the scroll event, emitted from `window`:
@Listen('scroll', { target: 'window' }) handleScroll(ev) { console.log('the body was scrolled', ev); }
#### passive[](https://stenciljs.com/docs/v4.34/events#passive "Direct link to passive")
By default, Stencil uses several heuristics to determine if it must attach a `passive` event listener or not. The `passive` option can be used to change the default behavior.
Please check out [https://developers.google.com/web/updates/2016/06/passive-event-listeners](https://developers.google.com/web/updates/2016/06/passive-event-listeners)
for further information.
#### capture[](https://stenciljs.com/docs/v4.34/events#capture "Direct link to capture")
Event listener attached with `@Listen` does not "capture" by default. When a event listener is set to "capture", it means the event will be dispatched during the "capture phase". Check out [https://www.quirksmode.org/js/events\_order.html](https://www.quirksmode.org/js/events_order.html)
for further information.
@Listen('click', { capture: true }) handleClick(ev) { console.log('click'); }
Keyboard events[](https://stenciljs.com/docs/v4.34/events#keyboard-events "Direct link to Keyboard events")
-------------------------------------------------------------------------------------------------------------
For keyboard events, you can use the standard `keydown` event in `@Listen()` and use `event.keyCode` or `event.which` to get the key code, or `event.key` for the string representation of the key.
@Listen('keydown')handleKeyDown(ev: KeyboardEvent){ if (ev.key === 'ArrowDown'){ console.log('down arrow pressed') }}
More info on event key strings can be found in the [w3c spec](https://www.w3.org/TR/uievents-key/#named-key-attribute-values)
.
Using events in JSX[](https://stenciljs.com/docs/v4.34/events#using-events-in-jsx "Direct link to Using events in JSX")
-------------------------------------------------------------------------------------------------------------------------
Within a stencil compiled application or component you can also bind listeners to events directly in JSX. This works very similar to normal DOM events such as `onClick`.
Let's use our TodoList component from above:
import { Event, EventEmitter } from '@stencil/core';...export class TodoList { @Event() todoCompleted: EventEmitter; todoCompletedHandler(todo: Todo) { this.todoCompleted.emit(todo); }}
We can now listen to this event directly on the component in our JSX using the following syntax:
this.someMethod(ev)} />
This property is generated automatically and is prefixed with "on". For example, if the event emitted is called `todoDeleted` the property will be called `onTodoDeleted`:
this.someOtherMethod(ev)} />
Listening to events from a non-JSX element[](https://stenciljs.com/docs/v4.34/events#listening-to-events-from-a-non-jsx-element "Direct link to Listening to events from a non-JSX element")
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
(initialState)`[](https://stenciljs.com/docs/v4.33/stencil-store#createstoretinitialstate "Direct link to createstoretinitialstate")
Create a new store with the given initial state. The type is inferred from `initialState`, or can be passed as the generic type `T`.
Returns a `store` object with the following properties.
### `store.state`[](https://stenciljs.com/docs/v4.33/stencil-store#storestate "Direct link to storestate")
The state object is proxied, I.E. you can directly get and set properties and Store will automatically take care of component re-rendering when the state object is changed.
### `store.on(event, listener)`[](https://stenciljs.com/docs/v4.33/stencil-store#storeonevent-listener "Direct link to storeonevent-listener")
Add a listener to the store for a certain action.
### `store.onChange(propName, listener)`[](https://stenciljs.com/docs/v4.33/stencil-store#storeonchangepropname-listener "Direct link to storeonchangepropname-listener")
Add a listener that is called when a specific property changes.
### `store.get(propName)`[](https://stenciljs.com/docs/v4.33/stencil-store#storegetpropname "Direct link to storegetpropname")
Get a property's value from the store.
### `store.set(propName, value)`[](https://stenciljs.com/docs/v4.33/stencil-store#storesetpropname-value "Direct link to storesetpropname-value")
Set a property's value in the store.
### `store.reset()`[](https://stenciljs.com/docs/v4.33/stencil-store#storereset "Direct link to storereset")
Reset the store to its initial state.
### `store.use(...subscriptions)`[](https://stenciljs.com/docs/v4.33/stencil-store#storeusesubscriptions "Direct link to storeusesubscriptions")
Use the given subscriptions in the store. A subscription is an object that defines one or more of the properties `get`, `set` or `reset`.
Testing[](https://stenciljs.com/docs/v4.33/stencil-store#testing "Direct link to Testing")
--------------------------------------------------------------------------------------------
Like any global state library, state should be reset between each spec test. Use the `dispose()` API in the `beforeEach` hook.
import store from '../store';beforeEach(() => { store.dispose();});
Contents
--------
* [Installation](https://stenciljs.com/docs/v4.33/stencil-store#installation)
* [Example](https://stenciljs.com/docs/v4.33/stencil-store#example)
* [API](https://stenciljs.com/docs/v4.33/stencil-store#api)
* [`createStore(initialState)`](https://stenciljs.com/docs/v4.33/stencil-store#createstoretinitialstate)
* [`store.state`](https://stenciljs.com/docs/v4.33/stencil-store#storestate)
* [`store.on(event, listener)`](https://stenciljs.com/docs/v4.33/stencil-store#storeonevent-listener)
* [`store.onChange(propName, listener)`](https://stenciljs.com/docs/v4.33/stencil-store#storeonchangepropname-listener)
* [`store.get(propName)`](https://stenciljs.com/docs/v4.33/stencil-store#storegetpropname)
* [`store.set(propName, value)`](https://stenciljs.com/docs/v4.33/stencil-store#storesetpropname-value)
* [`store.reset()`](https://stenciljs.com/docs/v4.33/stencil-store#storereset)
* [`store.use(...subscriptions)`](https://stenciljs.com/docs/v4.33/stencil-store#storeusesubscriptions)
* [Testing](https://stenciljs.com/docs/v4.33/stencil-store#testing)
* * *
[Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.33/guides/store.md)
---
# Distributing Web Components Built with Stencil | Stencil
[Skip to main content](https://stenciljs.com/docs/distribution#__docusaurus_skipToContent_fallback)
[An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none)
Version: v4.35
On this page
The `dist` type is to generate the component(s) as a reusable library that can be self-lazy loading, such as [Ionic](https://www.npmjs.com/package/@ionic/core)
. When creating a distribution, the project's `package.json` will also have to be updated. However, the generated bundle is tree-shakable, ensuring that only imported components will end up in the build.
outputTargets: [ { type: 'dist' }]
Config[](https://stenciljs.com/docs/distribution#config "Direct link to Config")
----------------------------------------------------------------------------------
### collectionDir[](https://stenciljs.com/docs/distribution#collectiondir "Direct link to collectionDir")
The `collectionDir` config specifies the output directory within the [distribution directory](https://stenciljs.com/docs/distribution#dir)
where the transpiled output of Stencil components will be written.
This option defaults to `collection` when omitted from a Stencil configuration file.
### dir[](https://stenciljs.com/docs/distribution#dir "Direct link to dir")
The `dir` config specifies the public distribution directory. This directory is commonly the `dist` directory found within [npm packages](https://docs.npmjs.com/getting-started/packages)
. This directory is built and rebuilt directly from the source files. Additionally, since this is a build target, all files will be deleted and rebuilt after each build, so it's best to always copy source files into this directory. It's recommended that this directory not be committed to a repository.
This option defaults to `dist` when omitted from a Stencil configuration file.
### empty[](https://stenciljs.com/docs/distribution#empty "Direct link to empty")
By default, before each build the `dir` directory will be emptied of all files. To prevent this directory from being emptied, change this value to `false`.
This flag defaults to `true` when omitted from a Stencil configuration file.
### isPrimaryPackageOutputTarget[](https://stenciljs.com/docs/distribution#isprimarypackageoutputtarget "Direct link to isPrimaryPackageOutputTarget")
_default: `false`_
If `true`, this output target will be used to validate `package.json` fields for your project's distribution. See the overview of [primary package output target validation](https://stenciljs.com/docs/output-targets#primary-package-output-target-validation)
for more information.
### transformAliasedImportPathsInCollection[](https://stenciljs.com/docs/distribution#transformaliasedimportpathsincollection "Direct link to transformAliasedImportPathsInCollection")
_default: `true`_
This option will allow [path aliases](https://www.typescriptlang.org/docs/handbook/module-resolution.html#path-mapping)
defined in a project's `tsconfig.json` to be transformed into relative paths in the code output under the [collectionDir](https://stenciljs.com/docs/distribution#collectiondir)
subdirectory for this output target. This does not affect imports for external packages.
An example of path transformation could look something like:
// Source codeimport * as utils from '@utils';// Output codeimport * as utils from '../path/to/utils';
tip
If using the `dist-collection` output target directly, the same result can be achieved using the [`transformAliasedImportPaths`](https://stenciljs.com/docs/distribution#transformaliasedimportpathsincollection)
flag on the target's config.
### esmLoaderPath[](https://stenciljs.com/docs/distribution#esmloaderpath "Direct link to esmLoaderPath")
_default: `/dist/loader`_
Provide a custom path for the ESM loader directory, containing files you can import in an initiation script within your application to register all your components for lazy loading. Read more about the loader directory in the [section below](https://stenciljs.com/docs/distribution#loader)
.
If you don't use a custom [exports](https://nodejs.org/api/packages.html#exports)
map, users would have to import the loader script via:
import { defineCustomElements } from 'stencil-library/dist/loader'
By setting `esmLoaderPath` to e.g. `../loader` you can shorten or rename the import path to:
import { defineCustomElements } from 'stencil-library/loader'
Publishing[](https://stenciljs.com/docs/distribution#publishing "Direct link to Publishing")
----------------------------------------------------------------------------------------------
Next you can publish your library to [Node Package Manager (NPM)](https://www.npmjs.com/)
. For more information about setting up the `package.json` file, and publishing, see: [Publishing A Component Library](https://stenciljs.com/docs/publishing)
.
Loader[](https://stenciljs.com/docs/distribution#loader "Direct link to Loader")
----------------------------------------------------------------------------------
The `dist` output target generates a loader directory that exports `setNonce`, `applyPolyfills` and `defineCustomElements` helper functions when imported within an ESM context. This allows you to register all components of your library to be used in your project in an application setup script, e.g.:
import { applyPolyfills, defineCustomElements, setNonce } from 'stencil-library/loader';// Will set the `nonce` attribute for all scripts/style tags// i.e. will run styleTag.setAttribute('nonce', 'r4nd0m')// Obviously, you should use the nonce generated by your serversetNonce('r4nd0m');applyPolyfills().then(() => { defineCustomElements();});
This is an alternative approach to e.g. loading the components directly through a script tag as mentioned below. Read more about `setNonce` and when to set it in our guide on [Content Security Policy Nonces](https://stenciljs.com/docs/csp-nonce)
.
Distribution Options[](https://stenciljs.com/docs/distribution#distribution-options "Direct link to Distribution Options")
----------------------------------------------------------------------------------------------------------------------------
Each output target's form of bundling and distribution has its own pros and cons. Luckily you can just worry about writing good source code for your component. Stencil will handle generating the various bundles and consumers of your library can decide how to apply your components to their external projects. Below are a few of the options.
### Script tag[](https://stenciljs.com/docs/distribution#script-tag "Direct link to Script tag")
* Use a script tag linked to a CDN copy of your published NPM module, for example: ``.
* The initial script itself is extremely tiny and does not represent the entire library. It's only a small registry.
* You can use any or all components within your library anywhere within that webpage.
* It doesn't matter if the actual component was written within the HTML or created with vanilla JavaScript, jQuery, React, etc.
* Only the components used on that page will be requested and lazy-loaded.
### Importing the `dist` library using a bundler[](https://stenciljs.com/docs/distribution#importing-the-dist-library-using-a-bundler "Direct link to importing-the-dist-library-using-a-bundler")
* Run `npm install my-name --save`
* Add an `import` within the root component: `import my-component`;
* Stencil will automatically setup the lazy-loading capabilities for the Stencil library.
* Then you can use the element anywhere in your template, JSX, HTML etc.
### Importing the `dist` library into another Stencil app[](https://stenciljs.com/docs/distribution#importing-the-dist-library-into-another-stencil-app "Direct link to importing-the-dist-library-into-another-stencil-app")
* Run `npm install my-name --save`
* Add an `import` within the root component: `import my-component`;
* Stencil will automatically setup the lazy-loading capabilities for the Stencil library.
* Then you can use the element anywhere in your template, JSX, HTML etc.
Contents
--------
* [Config](https://stenciljs.com/docs/distribution#config)
* [collectionDir](https://stenciljs.com/docs/distribution#collectiondir)
* [dir](https://stenciljs.com/docs/distribution#dir)
* [empty](https://stenciljs.com/docs/distribution#empty)
* [isPrimaryPackageOutputTarget](https://stenciljs.com/docs/distribution#isprimarypackageoutputtarget)
* [transformAliasedImportPathsInCollection](https://stenciljs.com/docs/distribution#transformaliasedimportpathsincollection)
* [esmLoaderPath](https://stenciljs.com/docs/distribution#esmloaderpath)
* [Publishing](https://stenciljs.com/docs/distribution#publishing)
* [Loader](https://stenciljs.com/docs/distribution#loader)
* [Distribution Options](https://stenciljs.com/docs/distribution#distribution-options)
* [Script tag](https://stenciljs.com/docs/distribution#script-tag)
* [Importing the `dist` library using a bundler](https://stenciljs.com/docs/distribution#importing-the-dist-library-using-a-bundler)
* [Importing the `dist` library into another Stencil app](https://stenciljs.com/docs/distribution#importing-the-dist-library-into-another-stencil-app)
* * *
[Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.35/output-targets/dist.md)
---
# Internal state | Stencil
[Skip to main content](https://stenciljs.com/docs/v4.34/state#__docusaurus_skipToContent_fallback)
[An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none)
This is documentation for Stencil **v4.34**, which is no longer actively maintained.
For up-to-date documentation, see the **[latest version](https://stenciljs.com/docs/state)
** (v4.35).
Version: v4.34
On this page
'State' is a general term that refers to the values and objects that are stored on a class or an instance of a class for use now or in the future.
Like a regular TypeScript class, a Stencil component may have one or more internal class members for holding value(s) that make up the component's state. Stencil allows developers to optionally mark class members holding some part of the class's state with the `@State()` decorator to trigger a rerender when the state changes.
The State Decorator (`@State`)[](https://stenciljs.com/docs/v4.34/state#the-state-decorator-state "Direct link to the-state-decorator-state")
-----------------------------------------------------------------------------------------------------------------------------------------------
Stencil provides a decorator to trigger a rerender when certain class members change. A component's class members that should trigger a rerender must be decorated using Stencil's `@State()` decorator, like so:
// First, we import State from '@stencil/core'import { Component, State, h } from '@stencil/core';@Component({ tag: 'current-time',})export class CurrentTime { // Second, we decorate a class member with @State() // When `currentTime` changes, a rerender will be // triggered @State() currentTime: number = Date.now(); render() { // Within the component's class, its members are // accessed via `this`. This allows us to render // the value stored in `currentTime` const time = new Date(this.currentTime).toLocaleTimeString(); return ( {time} ); }}
In the example above, `@State()` is placed before (decorates) the `currentTime` class member, which is a number. This marks `currentTime` so that any time its value changes, the component rerenders.
However, the example above doesn't demonstrate the real power of using `@State`. `@State` members are meant to only be updated within a class, which the example above never does after the initial assignment of `currentTime`. This means that our `current-time` component will never rerender! We fix that in the example below to update `current-time` every 1000 milliseconds (1 second):
import { Component, State, h } from '@stencil/core';@Component({ tag: 'current-time',})export class CurrentTime { timer: number; // `currentTime` is decorated with `@State()`, // as we need to trigger a rerender when its // value changes to show the latest time @State() currentTime: number = Date.now(); connectedCallback() { this.timer = window.setInterval(() => { // the assignment to `this.currentTime` // will trigger a re-render this.currentTime = Date.now(); }, 1000); } disconnectedCallback() { window.clearInterval(this.timer); } render() { const time = new Date(this.currentTime).toLocaleTimeString(); return ( {time} ); }}
The example above makes use of the [connectedCallback() lifecycle method](https://stenciljs.com/docs/v4.34/component-lifecycle#connectedcallback)
to set `currentTime` to the value of `Date.now()` every 1000 milliseconds (or, every one second). Because the value of `currentTime` changes every second, Stencil calls the `render` function on `current-time`, which pretty-prints the current time.
The example above also makes use of the [disconnectedCallback() lifecycle method](https://stenciljs.com/docs/v4.34/component-lifecycle#disconnectedcallback)
to properly clean up the timer that was created using `setInterval` in `connectedCallback()`. This isn't necessary for using `@State`, but is a general good practice when using `setInterval`.
When to Use `@State()`?[](https://stenciljs.com/docs/v4.34/state#when-to-use-state "Direct link to when-to-use-state")
------------------------------------------------------------------------------------------------------------------------
`@State()` should be used for all class members that should trigger a rerender when they change. However, not all internal state might need to be decorated with `@State()`. If you know for sure that the value will either not change or that it does not need to trigger a re-rendering, `@State()` is not necessary. It is considered a 'best practice' to only use `@State()` when absolutely necessary. Revisiting our `current-time` component:
import { Component, State, h } from '@stencil/core';@Component({ tag: 'current-time',})export class CurrentTime { // `timer` is not decorated with `@State()`, as // we do not wish to trigger a rerender when its // value changes timer: number; // `currentTime` is decorated with `@State()`, // as we need to trigger a rerender when its // value changes to show the latest time @State() currentTime: number = Date.now(); connectedCallback() { // the assignment to `this.timer` will not // trigger a re-render this.timer = window.setInterval(() => { // the assignment to `this.currentTime` // will trigger a re-render this.currentTime = Date.now(); }, 1000); } disconnectedCallback() { window.clearInterval(this.timer); } render() { const time = new Date(this.currentTime).toLocaleTimeString(); return ( {time} ); }}
Examples[](https://stenciljs.com/docs/v4.34/state#examples "Direct link to Examples")
---------------------------------------------------------------------------------------
### Using `@State()` with `@Listen()`[](https://stenciljs.com/docs/v4.34/state#using-state-with-listen "Direct link to using-state-with-listen")
This example makes use of `@State` and [`@Listen`](https://stenciljs.com/docs/v4.34/events#listen-decorator)
decorators. We define a class member called `isOpen` and decorate it with `@State()`. With the use of `@Listen()`, we respond to click events toggling the value of `isOpen`.
import { Component, Listen, State, h } from '@stencil/core';@Component({ tag: 'my-toggle-button'})export class MyToggleButton { // `isOpen` is decorated with `@State()`, // changes to it will trigger a rerender @State() isOpen: boolean = true; @Listen('click', { capture: true }) handleClick() { // whenever a click event occurs on // the component, update `isOpen`, // triggering the rerender this.isOpen = !this.isOpen; } render() { return ; }}
### Complex Types[](https://stenciljs.com/docs/v4.34/state#complex-types "Direct link to Complex Types")
For more advanced use cases, `@State()` can be used with a complex type. In the example below, we print a list of `Item` entries. Although we start with zero `Item`s initially, we use the same pattern as we did before to add a new `Item` to `ItemList`'s `items` array once every 2000 milliseconds (2 seconds). Every time a new entry is added to `items`, a rerender occurs:
import { Component, State, h } from '@stencil/core';// a user defined, complex type describing an 'Item'type Item = { id: number; description: string,}@Component({ tag: 'item-list',})export class ItemList { // `timer` is not decorated with `@State()`, as // we do not wish to trigger a rerender when its // value changes timer: number; // `items` will trigger a rerender if // the value assigned to the variable changes @State() items: Item[] = []; connectedCallback() { // the assignment to `this.timer` will not // trigger a re-render this.timer = window.setInterval(() => { const newTodo: Item = { description: "Item", id: this.items.length + 1 }; // the assignment to `this.items` will // trigger a re-render. the assignment // using '=' is important here, as we // need that to make sure the rerender // occurs this.items = [...this.items, newTodo]; }, 2000); } disconnectedCallback() { window.clearInterval(this.timer); } render() { return ( ); }}
It's important to note that it's the reassignment of `this.items` that is causing the rerender in `connectedCallback()`:
this.items = [...this.items, newTodo];
Mutating the existing reference to `this.items` like in the examples below will not cause a rerender, as Stencil will not know that the contents of the array has changed:
// updating `items` either of these ways will not// cause a rerenderthis.items.push(newTodo);this.items[this.items.length - 1] = newTodo;
Similar to the examples above, this code sample makes use of the [connectedCallback() lifecycle method](https://stenciljs.com/docs/v4.34/component-lifecycle#connectedcallback)
to create a new `Item` and add it to `items` every 2000 milliseconds (every two seconds). The example above also makes use of the [disconnectedCallback() lifecycle method](https://stenciljs.com/docs/v4.34/component-lifecycle#disconnectedcallback)
to properly clean up the timer that was created using `setInterval` in `connectedCallback()`.
Contents
--------
* [The State Decorator (`@State`)](https://stenciljs.com/docs/v4.34/state#the-state-decorator-state)
* [When to Use `@State()`?](https://stenciljs.com/docs/v4.34/state#when-to-use-state)
* [Examples](https://stenciljs.com/docs/v4.34/state#examples)
* [Using `@State()` with `@Listen()`](https://stenciljs.com/docs/v4.34/state#using-state-with-listen)
* [Complex Types](https://stenciljs.com/docs/v4.34/state#complex-types)
* * *
[Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.34/components/state.md)
---
# Server Side Rendering | Stencil
[Skip to main content](https://stenciljs.com/docs/v4.33/server-side-rendering#__docusaurus_skipToContent_fallback)
[An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none)
This is documentation for Stencil **v4.33**, which is no longer actively maintained.
For up-to-date documentation, see the **[latest version](https://stenciljs.com/docs/server-side-rendering)
** (v4.35).
Version: v4.33
On this page
Stencil provides server-side rendering (SSR) support for React and Vue Output Targets. If you're using frameworks like [Vite](https://vite.dev/)
, [Remix](https://remix.run/)
, [Next.js](https://nextjs.org/)
or [Nuxt](https://nuxt.com/)
, Stencil automatically enhances these frameworks to render components on the server using a [Declarative Shadow DOM](https://web.dev/articles/declarative-shadow-dom)
or in [scoped mode](https://stenciljs.com/docs/styling#scoped-css)
.
The first step to enable server side rendering is to generate a hydrate module of your components.
Hydrate Module[](https://stenciljs.com/docs/v4.33/server-side-rendering#hydrate-module "Direct link to Hydrate Module")
-------------------------------------------------------------------------------------------------------------------------
The Hydrate Module is a standalone bundle of all your components that uses a JavaScript implementation of various HTML and DOM standards to render Stencil components in a Node.js environment. To create this bundle you have to add `dist-hydrate-script` to your Stencil configuration:
stencil.config.ts
import { Config } from '@stencil/core';export const config: Config = { outputTargets: [ { type: 'dist-hydrate-script', dir: './hydrate', }, // ... ]};
This will create the Hydrate Module which you can export separately via:
package.json
{ "name": "component-library", ... "exports": { ... "./hydrate": { "types": "./hydrate/index.d.ts", "import": "./hydrate/index.mjs", "require": "./hydrate/index.js", "default": "./hydrate/index.js" }, ... }, ...}
Two SSR Approaches[](https://stenciljs.com/docs/v4.33/server-side-rendering#two-ssr-approaches "Direct link to Two SSR Approaches")
-------------------------------------------------------------------------------------------------------------------------------------
Stencil provides two distinct strategies for server-side rendering, each designed to solve different challenges and use cases. These approaches emerged from the complex nature of rendering Web Components on the server, where traditional browser APIs don't exist.
### Strategy 1: The Compiler Approach (Universal SSR)[](https://stenciljs.com/docs/v4.33/server-side-rendering#strategy-1-the-compiler-approach-universal-ssr "Direct link to Strategy 1: The Compiler Approach (Universal SSR)")
The compiler-based approach, implemented in the `@stencil/ssr` package, works as a build-time plugin that intercepts your code and performs AST (Abstract Syntax Tree) transformations. It transforms components at compile time.
#### How It Works[](https://stenciljs.com/docs/v4.33/server-side-rendering#how-it-works "Direct link to How It Works")
1. **Build-time interception**: The plugin (Vite or Webpack) receives your JSX code after transformation
2. **AST analysis**: Parses JavaScript into an Abstract Syntax Tree to identify Stencil components
3. **Prop analysis**: Analyzes the props being passed to each component
4. **Pre-rendering**: Calls Stencil's hydrate module to render the component server-side
5. **Code replacement**: Replaces the original component with a wrapper containing pre-rendered HTML
#### When to Use Compiler-Based SSR[](https://stenciljs.com/docs/v4.33/server-side-rendering#when-to-use-compiler-based-ssr "Direct link to When to Use Compiler-Based SSR")
✅ **Multiple framework support**: Need to support Vite, Remix, Next.js, and other meta-frameworks
✅ **Performance critical applications**: Where response speed is paramount
✅ **Predictable props**: Components with static or build-time determinable data
✅ **"Set it and forget it" solutions**: Want minimal runtime complexity
#### Advantages[](https://stenciljs.com/docs/v4.33/server-side-rendering#advantages "Direct link to Advantages")
* **Universal compatibility**: Works with any React meta-framework
* **Zero runtime overhead**: No server processing during requests
* **Handles deep nesting**: Excellent at rendering complex component compositions
* **Clean separation**: Clear distinction between build-time and runtime concerns
* **Consistent performance**: Predictable response times
#### Disadvantages[](https://stenciljs.com/docs/v4.33/server-side-rendering#disadvantages "Direct link to Disadvantages")
* **Static props only**: Cannot resolve dynamic props at compile time (e.g., `prop={calculateValue()}`)
* **Build-time configuration required**: Needs plugin setup
* **Hydration mismatches**: Still prone to occasional client/server differences
### Strategy 2: The Runtime Approach (Next.js Server Components)[](https://stenciljs.com/docs/v4.33/server-side-rendering#strategy-2-the-runtime-approach-nextjs-server-components "Direct link to Strategy 2: The Runtime Approach (Next.js Server Components)")
The runtime approach leverages Next.js Server Components to perform real-time SSR. When the server encounters a Stencil component, it renders it on-demand during the request cycle.
#### How It Works[](https://stenciljs.com/docs/v4.33/server-side-rendering#how-it-works-1 "Direct link to How It Works")
1. **Component interception**: Next.js hits a Stencil component during server rendering
2. **Prop serialization**: Uses `serializeProperty` to handle complex objects, Maps, Sets, and even `Infinity`
3. **Children transformation**: Attempts to transform React children into strings using `react-dom/server`
4. **Async rendering**: Calls Stencil's `renderToString` (Promise-based) on the server
5. **React node recreation**: Parses resulting HTML back into React nodes using `html-react-parser`
#### When to Use Runtime-Based SSR[](https://stenciljs.com/docs/v4.33/server-side-rendering#when-to-use-runtime-based-ssr "Direct link to When to Use Runtime-Based SSR")
✅ **Next.js commitment**: When you're fully invested in the Next.js ecosystem
✅ **Dynamic values**: Props that are highly dynamic or computed at runtime
✅ **Light DOM access**: Need to include children in server rendering
#### Advantages[](https://stenciljs.com/docs/v4.33/server-side-rendering#advantages-1 "Direct link to Advantages")
* **Full prop access**: All props available with resolved values at runtime
* **Light DOM inclusion**: Can include children during serialization
* **Dynamic value support**: Handles runtime-computed values perfectly
* **True isomorphic rendering**: Complete server-client parity
* **Complex object handling**: Built-in serialization for advanced data types
#### Disadvantages[](https://stenciljs.com/docs/v4.33/server-side-rendering#disadvantages-1 "Direct link to Disadvantages")
* **Next.js only**: Requires Server Components support
* **Dual component management**: Must maintain both client and server wrappers
* **Performance overhead**: Runtime serialization adds latency
* **Additional Setup**: Requires importing components from a separate export path, e.g. `my-react-components/next`
### Choosing Your Strategy[](https://stenciljs.com/docs/v4.33/server-side-rendering#choosing-your-strategy "Direct link to Choosing Your Strategy")
Here's the battle-tested decision tree from real-world implementation:
#### Use the Compiler Approach when:[](https://stenciljs.com/docs/v4.33/server-side-rendering#use-the-compiler-approach-when "Direct link to Use the Compiler Approach when:")
* You need to support multiple frameworks beyond Next.js
* Performance is your top priority
* Your components have predictable, static props
* You want a "set it and forget it" solution
* You're building a content-focused site (marketing, docs, blogs)
#### Use the Runtime Approach when:[](https://stenciljs.com/docs/v4.33/server-side-rendering#use-the-runtime-approach-when "Direct link to Use the Runtime Approach when:")
* You're committed to Next.js and Server Components
* You need full Light DOM access for complex compositions
* Your props are highly dynamic or computed at runtime
* You're okay with additional complexity for more rendering power
* You're building highly interactive, data-driven applications
Enable SSR for StencilJS[](https://stenciljs.com/docs/v4.33/server-side-rendering#enable-ssr-for-stenciljs "Direct link to Enable SSR for StencilJS")
-------------------------------------------------------------------------------------------------------------------------------------------------------
For serializing Stencil components on the server, Stencil uses a package called `@stencil/ssr` which you can install via:
npm install --save-dev @stencil/ssr
It exports compiler plugins for Vite based projects, e.g. Remix or Webpack based ones like Next.js. The plugin requires the following options:
#### `module`[](https://stenciljs.com/docs/v4.33/server-side-rendering#module "Direct link to module")
The import of the package that exports all your Stencil React components. It helps the package to understand which components can be server side rendered.
#### `from`[](https://stenciljs.com/docs/v4.33/server-side-rendering#from "Direct link to from")
The name of the package that exports all your Stencil React components. Stencil will look up all imports from that package and transforms the statement to use a server side rendered version of the component.
#### `hydrateModule`[](https://stenciljs.com/docs/v4.33/server-side-rendering#hydratemodule "Direct link to hydratemodule")
Your generated hydrate module that gives the package the primitives to serialize a given Stencil component.
#### `serializeShadowRoot`[](https://stenciljs.com/docs/v4.33/server-side-rendering#serializeshadowroot "Direct link to serializeshadowroot")
**optional**
**default: **declarative-shadow-dom****
Configurations on how the components should be rendered on the server, e.g. as Declarative Shadow DOM, as scoped components or as a mixture of both.
### Vite[](https://stenciljs.com/docs/v4.33/server-side-rendering#vite "Direct link to Vite")
If your project is based on the Vite compiler, this includes frameworks like [Remix](https://remix.run/)
that are rely on Vite under the hood, you can use the `@stencil/ssr` package to enable SSR support for Stencil components by adding the plugin to the configuration:
vite.config.ts
import { defineConfig } from 'vite';import { stencilSSR } from '@stencil/ssr';import react from '@vitejs/plugin-react';// https://vite.dev/config/export default defineConfig({ plugins: [ react(), stencilSSR({ module: import('component-library-react'), from: 'component-library-react', hydrateModule: import('component-library/hydrate'), serializeShadowRoot: { 'scoped': ['my-counter'], default: 'declarative-shadow-dom', }, }), ],})
or in case of a Remix project:
vite.config.ts
import { vitePlugin as remix } from "@remix-run/dev";import { defineConfig } from "vite";import { stencilSSR } from "@stencil/ssr";declare module "@remix-run/node" { interface Future { v3_singleFetch: true; }}export default defineConfig({ plugins: [ remix(), stencilSSR({ module: import('component-library-react'), from: 'component-library-react', hydrateModule: import('component-library/hydrate'), serializeShadowRoot: { 'scoped': ['my-counter'], default: 'declarative-shadow-dom', }, }), ],});
### Next.js[](https://stenciljs.com/docs/v4.33/server-side-rendering#nextjs "Direct link to Next.js")
When using Stencil with Next.js, you can server-side render (SSR) components in two ways: **at runtime** or **at compile time**. Each approach has its trade-offs, and the best choice depends on your component architecture.
* If your components rely heavily on **slots**, the **compiler-based** SSR approach is generally more reliable.
* If your components use **dynamically computed attributes**, the **runtime-based** SSR approach is more flexible.
#### Runtime-Based SSR[](https://stenciljs.com/docs/v4.33/server-side-rendering#runtime-based-ssr "Direct link to Runtime-Based SSR")
In this method, Stencil serializes the component to a **Declarative Shadow DOM** during runtime, as Next.js renders the component on the server. Since Next.js supports asynchronous server components, this allows Stencil to perform serialization as part of the render process.
To enable runtime SSR, set the `hydrateModule` option in your React output target:
import { Config } from '@stencil/core';import { reactOutputTarget } from '@stencil/react-output-target';export const config: Config = { namespace: 'component-library', outputTargets: [ reactOutputTarget({ /** * tell Stencil where to generate the `components.ts` and `components.server.ts` files */ outDir: '../component-library-react/src', /** * give Stencil the import name of the hydrate module */ hydrateModule: 'component-library/hydrate', /** * tell the server component where it would import the client version of the components */ clientModule: 'component-library-react', serializeShadowRoot: { /* options */ }, }), ],};
This will generate:
* `components.ts` — for use on the client
* `components.server.ts` — for server-side rendering
If you distribute your React wrapper as a separate package, consider exposing the server entry point via a custom export path in your `package.json`:
{ "name": "component-library-react", "version": "0.0.0", "type": "module", "exports": { ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js", "node": "./dist/components.server.js" }, "./next": { "types": "./dist/components.server.d.ts", "import": "./dist/components.server.js" } }}
Now you can use the server-optimized components in your Next.js app:
/src/app/page.tsx
import { MyComponent } from 'component-library-react/next';export default function Home() { return ( <> ... >export const withSSR = (nextConfig: NextConfig): NextConfig => { return stencilConfig({ from: '@placid/react', module: import('./components.js'), hydrateModule: import('@placid/core/hydrate'), })(nextConfig)}
Then expose framework-specific helpers through clean export paths:
packages/react/package.json
{ "name": "@your-company/react", "exports": { ".": { "import": "./dist/components.js", "types": "./dist/components.d.ts" }, "./next": { "import": "./dist/next.js", "types": "./dist/next.d.ts" }, "./vite": { "import": "./dist/vite.js", "types": "./dist/vite.d.ts" }, "./server": { "import": "./dist/components.server.js", "types": "./dist/components.server.d.ts" } }, "dependencies": { "@your-company/core": "workspace:*", "@stencil/react-output-target": "^1.0.3", "@stencil/ssr": "^0.1.1" }}
**Note:** the exports path `./next` and `./vite` export above example for either Vite or Next.js based setups.
With this approach, consumers have a much cleaner experience:
next.config.mjs
import { withSSR } from '@your-company/react/next';const nextConfig = { // your existing Next.js configuration};export default withSSR(nextConfig);
Limitations[](https://stenciljs.com/docs/v4.33/server-side-rendering#limitations "Direct link to Limitations")
----------------------------------------------------------------------------------------------------------------
When server-side rendering Stencil components, there are a few potential pitfalls and limitations you might encounter. To help you avoid these issues, here are some key tips and best practices.
### Performance[](https://stenciljs.com/docs/v4.33/server-side-rendering#performance "Direct link to Performance")
By default Stencil server-side renders a component into a [Declarative Shadow DOM](https://web.dev/articles/declarative-shadow-dom)
, which includes all structural information and styles. While this ensures accurate rendering, it can significantly increase document size if not managed carefully.
For example, consider a button component:
import { Component, Fragment, h } from '@stencil/core'@Component({ tag: 'my-btn', styleUrl: './button.css'})export class MyBtn { render() { return ( <> ); }}
And this `button.css` which imports additional common styles:
/* button.css */@import "../css/base.css";@import "../css/tokens.css";@import "../css/animations.css";@import "../css/utilities.css";/* component-specific styles */button { ...}
When SSR is performed, the entire CSS (including imports) is bundled with the component's declarative shadow DOM. Rendering multiple instances of this button in SSR can lead to repeated inclusion of styles, bloating the document size and delaying [First Contentful Paint (FCP)](https://web.dev/articles/fcp)
.
Here are some ways to mitigate this:
* **Use CSS Variables**: CSS variables can pierce the Shadow DOM, reducing the need for redundant styles.
* **Use the `::part` pseudo-element**: This allows you to style parts of the Shadow DOM from outside the component, minimizing the internal CSS.
* **Optimize Component-Specific CSS**: Only include the necessary styles for each component.
* **Limit SSR Scope**: In Next.js, apply `use client` to sections that don't need SSR to reduce unnecessary rendering.
Compared to many other web-component frameworks Stencil understands to render a component as actual web component as well as a scoped component. A scoped component doesn't use a Shadow DOM and style encapsulation is emulated. This provides an advantage in the SSR context as you don't have to ship the same styles multiple times when you render specific components in different places.
With the `serializeShadowRoot` of the `@stencil/ssr` package you can define which components should be rendered as actual web-component in a declarative shadow DOM and which should be rendered as a scoped component. You can define certain components that appear a lot in your initial DOM as scoped components to avoid sending duplicate styles for them, e.g.:
next.config.js
import stencilSSR from '@stencil/ssr/next';/** @type {import('next').NextConfig} */const nextConfig = { // ...};export default stencilSSR({ module: import('component-library-react'), from: 'component-library-react', hydrateModule: import('component-library/hydrate'), serializeShadowRoot: { /** * By default all Stencil components are rendered with a Declarative Shadow DOM */ default: 'declarative-shadow-dom', /** * However, you can define a set of components that will be rendered in scoped mode, * allowing to send only one set of styles that are applied to all components. */ scoped: ['my-button'], },})(nextConfig);
Once the Stencil runtime activates, it transforms the scoped component back into a classic web component with a Shadow-DOM and reformats its styles.
### Avoid Non-Primitive Parameters[](https://stenciljs.com/docs/v4.33/server-side-rendering#avoid-non-primitive-parameters "Direct link to Avoid Non-Primitive Parameters")
When building components, it's common to pass complex data structures like objects to components as props. For example, a footer menu could be structured as an object rather than as separate components for each menu item:
const menu = generateMenuData({ ... })return ( )
While this approach works fine in the browser, it poses challenges for SSR. While Stencil generally **supports** the serialization of complex objects within parameters, it can't resolve the value of any function calls, e.g. here `generateMenuData(...)` during the SSR process (except when using runtime based SSR within Next.js applications).
We recommend to **not** depend on external data structures when it comes to rendering Stencil components.
### Cross-Component State Handling[](https://stenciljs.com/docs/v4.33/server-side-rendering#cross-component-state-handling "Direct link to Cross-Component State Handling")
When propagating state between parent and child components, patterns like reducers or context providers (as in React) are often used. However, this can be problematic with SSR in frameworks like Next.js, where each component is rendered independently.
Consider the following structure:
When ParentComponent is rendered on the server, Stencil will attempt to stringify its children (e.g., ChildComponent) for the light DOM. The intermediate markup may look like this:
...
At this stage, ParentComponent can access and manipulate its children. However, when ChildComponent is rendered in isolation, it won't have access to the parent's state or context, potentially leading to inconsistencies.
To prevent this, ensure that components rendered on the server don't depend on external state or context. If the component relies on data fetched at runtime, it's better to display a loading placeholder during SSR.
Contents
--------
* [Hydrate Module](https://stenciljs.com/docs/v4.33/server-side-rendering#hydrate-module)
* [Two SSR Approaches](https://stenciljs.com/docs/v4.33/server-side-rendering#two-ssr-approaches)
* [Strategy 1: The Compiler Approach (Universal SSR)](https://stenciljs.com/docs/v4.33/server-side-rendering#strategy-1-the-compiler-approach-universal-ssr)
* [Strategy 2: The Runtime Approach (Next.js Server Components)](https://stenciljs.com/docs/v4.33/server-side-rendering#strategy-2-the-runtime-approach-nextjs-server-components)
* [Choosing Your Strategy](https://stenciljs.com/docs/v4.33/server-side-rendering#choosing-your-strategy)
* [Enable SSR for StencilJS](https://stenciljs.com/docs/v4.33/server-side-rendering#enable-ssr-for-stenciljs)
* [Vite](https://stenciljs.com/docs/v4.33/server-side-rendering#vite)
* [Next.js](https://stenciljs.com/docs/v4.33/server-side-rendering#nextjs)
* [Nuxt](https://stenciljs.com/docs/v4.33/server-side-rendering#nuxt)
* [Custom Config Wrapper](https://stenciljs.com/docs/v4.33/server-side-rendering#custom-config-wrapper)
* [Limitations](https://stenciljs.com/docs/v4.33/server-side-rendering#limitations)
* [Performance](https://stenciljs.com/docs/v4.33/server-side-rendering#performance)
* [Avoid Non-Primitive Parameters](https://stenciljs.com/docs/v4.33/server-side-rendering#avoid-non-primitive-parameters)
* [Cross-Component State Handling](https://stenciljs.com/docs/v4.33/server-side-rendering#cross-component-state-handling)
* * *
[Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.33/guides/server-side-rendering.md)
---
# Custom Docs Generation | Stencil
[Skip to main content](https://stenciljs.com/docs/v4.33/docs-custom#__docusaurus_skipToContent_fallback)
[An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none)
This is documentation for Stencil **v4.33**, which is no longer actively maintained.
For up-to-date documentation, see the **[latest version](https://stenciljs.com/docs/docs-custom)
** (v4.35).
Version: v4.33
On this page
Stencil exposes an output target titled `docs-custom` where users can access the generated docs json data. This feature can be used to generate custom markdown or to execute other logic on the json data during the build. As with other docs output targets, `strict` mode is supported.
To make use of this output target, simply add the following to your Stencil configuration.
import { Config } from '@stencil/core';export const config: Config = { outputTargets: [ { type: 'docs-custom', generator: (docs: JsonDocs) => { // Custom logic goes here } } ]};
Config[](https://stenciljs.com/docs/v4.33/docs-custom#config "Direct link to Config")
---------------------------------------------------------------------------------------
| Property | Description | Default |
| --- | --- | --- |
| `generator` | A function with the docs json data as argument. | |
| `strict` | If set to true, Stencil will output a warning whenever there is missing documentation. | `false` |
Custom Docs Data Model
======================
The generated docs JSON data will in the type of `JsonDocs` which consists of main `components` array which consists of components that stencil core found and meta information such as `timestamp` and `compiler`
JsonDocs[](https://stenciljs.com/docs/v4.33/docs-custom#jsondocs "Direct link to JsonDocs")
---------------------------------------------------------------------------------------------
| Property | Description |
| --- | --- |
| `components` | Array with type of `JsonDocsComponent[]` which consists component information |
| `timestamp` | `string` with timestamp |
| `compiler` | `Object` with `typescriptVersion`, `compiler`, and `version` |
JsonDocsComponent[](https://stenciljs.com/docs/v4.33/docs-custom#jsondocscomponent "Direct link to JsonDocsComponent")
------------------------------------------------------------------------------------------------------------------------
| Property | Description |
| --- | --- |
| `dirPath` | Component directory path |
| `fileName` | File name |
| `filePath` | File path |
| `readmePath` | Readme file path |
| `usagesDir` | Stencil looks in a directory named `usages/` in the same directory as your component to find usage examples. This holds the full path to that directory. |
| `encapsulation` | Component `encapsulation` type. Possible values are `shadow`, `scoped`, `none` |
| `tag` | Component tag described in `.tsx` file |
| `readme` | Component readme file first line content |
| `docs` | Description written in top of `@Component` e.g. /\*\* Documentation Example \*/. If no JSDoc is present, default to any manually written text in the component's markdown file. Empty otherwise. |
| `docsTags` | Annotations (In the way of JSDoc ) written in `.tsx` file will be collected here |
| `overview` | Description written in top of `@Component` e.g. /\*\* Documentation Example \*/ |
| `usage` | Array of [usage examples](https://stenciljs.com/docs/v4.33/docs-json#usage)
, written in Markdown files in the `usages/` directory adjacent to the current component. | | `props` | Array of metadata objects for each usage of the [`@Prop` decorator](https://stenciljs.com/docs/v4.33/properties#the-prop-decorator-prop)
on the current component. | | `methods` | Array of metadata objects for each usage of the [`@Method` decorator](https://stenciljs.com/docs/v4.33/methods)
on the current component. | | `events` | Array of metadata objects for each usage of the [`@Event` decorator](https://stenciljs.com/docs/v4.33/events#event-decorator)
on the current component. | | `listeners` | Array of metadata objects for each usage of the [`@Listen` decorator](https://stenciljs.com/docs/v4.33/events#listen-decorator)
on the current component. | | `styles` | Array of objects documenting annotated [CSS variables](https://stenciljs.com/docs/v4.33/docs-json#css-variables)
used in the current component's CSS. | | `slots` | Array of objects documenting [slots](https://stenciljs.com/docs/v4.33/docs-json#slots)
which are tagged with `@slot` in the current component's JSDoc comment. | | `parts` | Array of objects derived from `@part` tags in the current component's JSDoc comment. | | `dependents` | Array of components where current component is used | | `dependencies` | Array of components which is used in current component | | `dependencyGraph` | Describes a tree of components coupling | Contents -------- * [Config](https://stenciljs.com/docs/v4.33/docs-custom#config) * [JsonDocs](https://stenciljs.com/docs/v4.33/docs-custom#jsondocs) * [JsonDocsComponent](https://stenciljs.com/docs/v4.33/docs-custom#jsondocscomponent) * * * [Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.33/documentation-generation/docs-custom.md) --- # Methods | Stencil [Skip to main content](https://stenciljs.com/docs/v4.34/methods#__docusaurus_skipToContent_fallback) [An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none) This is documentation for Stencil **v4.34**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](https://stenciljs.com/docs/methods) ** (v4.35). Version: v4.34 On this page The `@Method()` decorator is used to expose methods on the public API. Functions decorated with the `@Method()` decorator can be called directly from the element, i.e. they are intended to be callable from the outside! note Developers should try to rely on publicly exposed methods as little as possible, and instead default to using properties and events as much as possible. As an app scales, we've found it's easier to manage and pass data through @Prop rather than public methods. import { Method } from '@stencil/core';export class TodoList { @Method() async showPrompt() { // show a prompt }} Call the method like this: note Developers should ensure that the component is defined by using the whenDefined method of the custom element registry before attempting to call public methods. (async () => { await customElements.whenDefined('todo-list'); const todoListElement = document.querySelector('todo-list'); await todoListElement.showPrompt();})(); Public methods must be async[](https://stenciljs.com/docs/v4.34/methods#public-methods-must-be-async "Direct link to Public methods must be async") ----------------------------------------------------------------------------------------------------------------------------------------------------- Stencil's architecture is async at all levels which allows for many performance benefits and ease of use. By ensuring publicly exposed methods using the `@Method` decorator return a promise: * Developers can call methods before the implementation was downloaded without componentOnReady(), which queues the method calls and resolves after the component has finished loading. * Interaction with the component is the same whether it still needs to be lazy-loaded, or is already fully hydrated. * By keeping a component's public API async, apps could move the components transparently to [Web Worker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API) and the API would still be the same. * Returning a promise is only required for publicly exposed methods which have the `@Method` decorator. All other component methods are private to the component and are not required to be async. // VALID: using async@Method()async myMethod() { return 42;}// VALID: using Promise.resolve()@Method()myMethod2() { return Promise.resolve(42);}// VALID: even if it returns nothing, it needs to be async@Method()async myMethod3() { console.log(42);}// INVALID@Method()notOk() { return 42;} Private methods[](https://stenciljs.com/docs/v4.34/methods#private-methods "Direct link to Private methods") -------------------------------------------------------------------------------------------------------------- Non-public methods can still be used to organize the business logic of your component and they do NOT have to return a Promise. class Component { // Since `getData` is not a public method exposed with @Method // it does not need to be async getData() { return this.someData; } render() { return ( ); }}const MyGlobalCounter = () => { return ( );};
API[](https://stenciljs.com/docs/v4.34/stencil-store#api "Direct link to API")
--------------------------------------------------------------------------------
### `createStore(initialState)`[](https://stenciljs.com/docs/v4.34/stencil-store#createstoretinitialstate "Direct link to createstoretinitialstate")
Create a new store with the given initial state. The type is inferred from `initialState`, or can be passed as the generic type `T`.
Returns a `store` object with the following properties.
### `store.state`[](https://stenciljs.com/docs/v4.34/stencil-store#storestate "Direct link to storestate")
The state object is proxied, I.E. you can directly get and set properties and Store will automatically take care of component re-rendering when the state object is changed.
### `store.on(event, listener)`[](https://stenciljs.com/docs/v4.34/stencil-store#storeonevent-listener "Direct link to storeonevent-listener")
Add a listener to the store for a certain action.
### `store.onChange(propName, listener)`[](https://stenciljs.com/docs/v4.34/stencil-store#storeonchangepropname-listener "Direct link to storeonchangepropname-listener")
Add a listener that is called when a specific property changes.
### `store.get(propName)`[](https://stenciljs.com/docs/v4.34/stencil-store#storegetpropname "Direct link to storegetpropname")
Get a property's value from the store.
### `store.set(propName, value)`[](https://stenciljs.com/docs/v4.34/stencil-store#storesetpropname-value "Direct link to storesetpropname-value")
Set a property's value in the store.
### `store.reset()`[](https://stenciljs.com/docs/v4.34/stencil-store#storereset "Direct link to storereset")
Reset the store to its initial state.
### `store.use(...subscriptions)`[](https://stenciljs.com/docs/v4.34/stencil-store#storeusesubscriptions "Direct link to storeusesubscriptions")
Use the given subscriptions in the store. A subscription is an object that defines one or more of the properties `get`, `set` or `reset`.
Testing[](https://stenciljs.com/docs/v4.34/stencil-store#testing "Direct link to Testing")
--------------------------------------------------------------------------------------------
Like any global state library, state should be reset between each spec test. Use the `dispose()` API in the `beforeEach` hook.
import store from '../store';beforeEach(() => { store.dispose();});
Contents
--------
* [Installation](https://stenciljs.com/docs/v4.34/stencil-store#installation)
* [Example](https://stenciljs.com/docs/v4.34/stencil-store#example)
* [API](https://stenciljs.com/docs/v4.34/stencil-store#api)
* [`createStore(initialState)`](https://stenciljs.com/docs/v4.34/stencil-store#createstoretinitialstate)
* [`store.state`](https://stenciljs.com/docs/v4.34/stencil-store#storestate)
* [`store.on(event, listener)`](https://stenciljs.com/docs/v4.34/stencil-store#storeonevent-listener)
* [`store.onChange(propName, listener)`](https://stenciljs.com/docs/v4.34/stencil-store#storeonchangepropname-listener)
* [`store.get(propName)`](https://stenciljs.com/docs/v4.34/stencil-store#storegetpropname)
* [`store.set(propName, value)`](https://stenciljs.com/docs/v4.34/stencil-store#storesetpropname-value)
* [`store.reset()`](https://stenciljs.com/docs/v4.34/stencil-store#storereset)
* [`store.use(...subscriptions)`](https://stenciljs.com/docs/v4.34/stencil-store#storeusesubscriptions)
* [Testing](https://stenciljs.com/docs/v4.34/stencil-store#testing)
* * *
[Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.34/guides/store.md)
---
# Stencil Style Guide | Stencil
[Skip to main content](https://stenciljs.com/docs/v4.34/style-guide#__docusaurus_skipToContent_fallback)
[An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none)
This is documentation for Stencil **v4.34**, which is no longer actively maintained.
For up-to-date documentation, see the **[latest version](https://stenciljs.com/docs/style-guide)
** (v4.35).
Version: v4.34
On this page
This is a component style guide created and enforced internally by the core team of Stencil, for the purpose of standardizing Stencil components. This should only be used as a reference for other teams in creating their own style guides. Feel free to modify to your team's own preference.
note
In order to enforce this (or your team's) style guide, we recommend leveraging a static analysis tool like [ESLint](https://eslint.org/)
. [@stencil-community/eslint-plugin](https://www.npmjs.com/package/@stencil-community/eslint-plugin)
provides rules specifically for writing Stencil components.
note
This guide once recommended TSLint as a static analysis tool. TSLint has been deprecated by its maintaining organization in favor of ESLint and is no longer recommended by the Stencil team.
File structure[](https://stenciljs.com/docs/v4.34/style-guide#file-structure "Direct link to File structure")
---------------------------------------------------------------------------------------------------------------
* One component per file.
* One component per directory. Though it may make sense to group similar components into the same directory, we've found it's easier to document components when each one has its own directory.
* Implementation (.tsx) and styles of a component should live in the same directory.
Example from ionic-core:
├── my-card│ ├── my-card.ios.css│ ├── my-card.md.css│ ├── my-card.css│ ├── my-card.tsx│ └── test│ └── basic│ ├── e2e.js│ └── index.html├── my-card-content│ ├── my-card-content.ios.css│ ├── my-card-content.md.css│ ├── my-card-content.css│ └── my-card-content.tsx├── my-card-title│ ├── my-card-title.ios.css│ ├── my-card-title.md.css│ ├── my-card-title.css
Naming[](https://stenciljs.com/docs/v4.34/style-guide#naming "Direct link to Naming")
---------------------------------------------------------------------------------------
### HTML tag[](https://stenciljs.com/docs/v4.34/style-guide#html-tag "Direct link to HTML tag")
#### Prefix[](https://stenciljs.com/docs/v4.34/style-guide#prefix "Direct link to Prefix")
The prefix has a major role when you are creating a collection of components intended to be used across different projects, like [@ionic/core](https://www.npmjs.com/package/@ionic/core)
. Web Components are not scoped because they are globally declared within the webpage, which means a "unique" prefix is needed to prevent collisions. The prefix also helps to quickly identify the collection a component is part of. Additionally, web components are required to contain a "-" dash within the tag name, so using the first section to namespace your components is a natural fit.
We do not recommend using "stencil" as prefix, since Stencil DOES NOT emit stencil components, but rather the output is standards compliant web components.
DO NOT do this:
Instead, use your own naming or brand. For example, [Ionic](https://ionicframework.com/)
components are all prefixed with `ion-`.
#### Name[](https://stenciljs.com/docs/v4.34/style-guide#name "Direct link to Name")
Components are not actions, they are conceptually "things". It is better to use nouns instead of verbs, such as "animation" instead of "animating". "input", "tab", "nav", "menu" are some examples.
#### Modifiers[](https://stenciljs.com/docs/v4.34/style-guide#modifiers "Direct link to Modifiers")
When several components are related and/or coupled, it is a good idea to share the name, and then add different modifiers, for example:
### Component (TS class)[](https://stenciljs.com/docs/v4.34/style-guide#component-ts-class "Direct link to Component (TS class)")
The name of the ES6 class of the component SHOULD NOT have a prefix since classes are scoped. There is no risk of collision.
@Component({ tag: 'ion-button'})export class Button { ... }@Component({ tag: 'ion-menu'})export class Menu { ... }
TypeScript[](https://stenciljs.com/docs/v4.34/style-guide#typescript "Direct link to TypeScript")
---------------------------------------------------------------------------------------------------
1. **Use private variables and methods as much possible:** They are useful to detect dead code and enforce encapsulation. Note that this is a feature which TypeScript provides to help harden your code, but using `private`, `public` or `protected` does not make a difference in the actual JavaScript output.
2. **Code with Method/Prop/Event/Component decorators should have JSDocs:** This allows for documentation generation and for better user experience in an editor that has TypeScript intellisense
Code organization[](https://stenciljs.com/docs/v4.34/style-guide#code-organization "Direct link to Code organization")
------------------------------------------------------------------------------------------------------------------------
**Newspaper Metaphor from The Robert C. Martin's _Clean Code_**
note
The source file should be organized like a newspaper article, with the highest level summary at the top, and more and more details further down. Functions called from the top function come directly below it, and so on down to the lowest level and most detailed functions at the bottom. This is a good way to organize the source code, even though IDEs make the location of functions less important, since it is so easy to navigate in and out of them.
### High level example (commented)[](https://stenciljs.com/docs/v4.34/style-guide#high-level-example-commented "Direct link to High level example (commented)")
@Component({ tag: 'ion-something', styleUrls: { ios: 'something.ios.css', md: 'something.md.css', wp: 'something.wp.css' }})export class Something { /** * 1. Own Properties * Always set the type if a default value has not * been set. If a default value is being set, then type * is already inferred. List the own properties in * alphabetical order. Note that because these properties * do not have the @Prop() decorator, they will not be exposed * publicly on the host element, but only used internally. */ num: number; someText = 'default'; /** * 2. Reference to host HTML element. * Inlined decorator */ @Element() el: HTMLElement; /** * 3. State() variables * Inlined decorator, alphabetical order. */ @State() isValidated: boolean; @State() status = 0; /** * 4. Public Property API * Inlined decorator, alphabetical order. These are * different than "own properties" in that public props * are exposed as properties and attributes on the host element. * Requires JSDocs for public API documentation. */ @Prop() content: string; @Prop() enabled: boolean; @Prop() menuId: string; @Prop() type = 'overlay'; /** * Prop lifecycle events SHOULD go just behind the Prop they listen to. * This makes sense since both statements are strongly connected. * - If renaming the instance variable name you must also update the name in @Watch() * - Code is easier to follow and maintain. */ @Prop() swipeEnabled = true; @Watch('swipeEnabled') swipeEnabledChanged(newSwipeEnabled: boolean, oldSwipeEnabled: boolean) { this.updateState(); } /** * 5. Events section * Inlined decorator, alphabetical order. * Requires JSDocs for public API documentation. */ @Event() ionClose: EventEmitter; @Event() ionDrag: EventEmitter; @Event() ionOpen: EventEmitter; /** * 6. Component lifecycle events * Ordered by their natural call order, for example * WillLoad should go before DidLoad. */ connectedCallback() {} disconnectedCallback() {} componentWillLoad() {} componentDidLoad() {} componentShouldUpdate(newVal: any, oldVal: any, propName: string) {} componentWillUpdate() {} componentDidUpdate() {} componentWillRender() {} componentDidRender() {} /** * 7. Listeners * It is ok to place them in a different location * if makes more sense in the context. Recommend * starting a listener method with "on". * Always use two lines. */ @Listen('click', { enabled: false }) onClick(ev: UIEvent) { console.log('hi!') } /** * 8. Public methods API * These methods are exposed on the host element. * Always use two lines. * Public Methods must be async. * Requires JSDocs for public API documentation. */ @Method() async open(): Promise { // ... return true; } @Method() async close(): Promise { // ... } /** * 9. Local methods * Internal business logic. These methods cannot be * called from the host element. */ prepareAnimation(): Promise { // ... } updateState() { // ... } /** * 10. render() function * Always the last public method in the class. * If private methods present, they are below public methods. */ render() { return ( ); }}
Contents
--------
* [File structure](https://stenciljs.com/docs/v4.34/style-guide#file-structure)
* [Naming](https://stenciljs.com/docs/v4.34/style-guide#naming)
* [HTML tag](https://stenciljs.com/docs/v4.34/style-guide#html-tag)
* [Component (TS class)](https://stenciljs.com/docs/v4.34/style-guide#component-ts-class)
* [TypeScript](https://stenciljs.com/docs/v4.34/style-guide#typescript)
* [Code organization](https://stenciljs.com/docs/v4.34/style-guide#code-organization)
* [High level example (commented)](https://stenciljs.com/docs/v4.34/style-guide#high-level-example-commented)
* * *
[Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.34/guides/style-guide.md)
---
# Web Workers | Stencil
[Skip to main content](https://stenciljs.com/docs/v4.34/web-workers#__docusaurus_skipToContent_fallback)
[An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none)
This is documentation for Stencil **v4.34**, which is no longer actively maintained.
For up-to-date documentation, see the **[latest version](https://stenciljs.com/docs/web-workers)
** (v4.35).
Version: v4.34
On this page
[Web Workers](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers)
are a widely supported technology (Chrome, Firefox, Safari and Edge) that allows JavaScript to execute in a different thread, maximizing the usage of multiple CPUs; but most importantly not blocking the **main thread**.
The **main thread** is where JavaScript runs by default and has access to the `document`, `window` and other DOM APIs. The problem is that long-running JS prevents the browser from running smooth animations (CSS animations, transitions, canvas, svg...), making your site look frozen. That's why if your application needs to run CPU-intensive tasks, Web Workers are a great help.
When to use Web Workers?[](https://stenciljs.com/docs/v4.34/web-workers#when-to-use-web-workers "Direct link to When to use Web Workers?")
--------------------------------------------------------------------------------------------------------------------------------------------
The first thing to understand is when to use a Web Workers, and when _not_ to use them since they come with a set of costs and limitations:
* There is no access to the [DOM](https://developer.mozilla.org/en-US/docs/Web/API/Document_Object_Model/Introduction)
. This means you cannot interact with `document`, `window` or any elements in the page.
* There is no access to any of the `@stencil/core` APIs. For example, you cannot declare and use a component in a Web Worker, for the same reasons there is **no access to the DOM**.
* A Web Worker has its own **isolated state** since each worker has their own memory space. For example, a variable declared on the main thread cannot be directly referenced from a worker.
* There is an overhead when passing data between workers and the main thread. As a general rule, it's best to minimize the amount of data sent to and from the worker and be mindful if the work to send your data takes more time than doing it on the main thread.
* Communication is always **asynchronous**. Luckily Promises and async/await makes this relatively easy, but it's important to understand that communication between threads is always asynchronous.
* You can **only** pass [primitives](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Primitive_values)
and objects that implement the [structured clone algorithm](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm)
. Best way to think of it is any data that can be serialized to JSON is safe to use.
In short, it's generally a good idea to use workers to move logic that is thread-blocking -- or UI-blocking, preventing users from interacting with the page -- into a Web Worker, such as real-time code syntax highlighting.
Best Practices when using Web Workers[](https://stenciljs.com/docs/v4.34/web-workers#best-practices-when-using-web-workers "Direct link to Best Practices when using Web Workers")
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
* Use pure and functional algorithms in workers. `(input1, input2) => output`.
* The worker logic itself can be as complex as it has to be, however, the input and output data should stay fairly simple.
* Look for ways to reduce passing data between the main thread and worker thread.
* Class instances cannot be passed as data. Instead, only work with data can be JSON serializable.
* Minimize state within the worker, or better yet, completely avoid maintaining any state (e.g., don't put redux inside a worker).
* The cost of a worker should be easily amortized because it would be doing some CPU-intensive jobs.
How vanilla Web Workers "work"?[](https://stenciljs.com/docs/v4.34/web-workers#how-vanilla-web-workers-work "Direct link to How vanilla Web Workers "work"?")
---------------------------------------------------------------------------------------------------------------------------------------------------------------
The browser comes with a `Worker` API, that works the following way:
const worker = new Worker('/my-worker.js');worker.postMessage(['send message to worker']);worker.onmessage = (ev) => { console.log('data from worker', ev.data);};
This API, while powerful, is very low level and makes it tedious to write complex apps, since the event-driven paradigm leads easily to [spaghetti-code](https://en.wikipedia.org/wiki/Spaghetti_code)
, and quickly misses out on strongly-typed functions and data.
For further information, check out [this fantastic tutorial](https://www.html5rocks.com/en/tutorials/workers/basics/)
by our friends at HTML5Rocks.
A Web Worker also requires the generation of a separate JavaScript bundle, such as the `my-worker.js` file in the example above. This means you usually need extra build scripts and tooling that transpiles and bundles the worker entry point into another `.js` file. Additionally, the main bundle must be able to reference the worker bundle's file location, which is oftentimes a challenge after transpiling, bundling, minifying, filename hashing and deploying to production servers.
Fortunately, Stencil can help you solve these two problems:
* Tooling: Transpiling, bundling, hashing, worker url path referencing
* Communication: Converting event-based communication to Promises, while still maintaining types.
Web Workers with Stencil[](https://stenciljs.com/docs/v4.34/web-workers#web-workers-with-stencil "Direct link to Web Workers with Stencil")
---------------------------------------------------------------------------------------------------------------------------------------------
As we already mention, Stencil's compiler can help you to use workers in production seamlessly. Any TypeScript file within the `src` directory that ends with `.worker.ts` will automatically use a worker. For example:
**src/stuff.worker.ts:**
export const sum = async (a: number, b: number) => { return a + b;}export const expensiveTask = async (buffer: ArrayBuffer) => { for (let i = 0; i < buffer.length; i++) { // do a lot of processing } return buffer;};
**src/my-app/my-app.tsx:**
import { Component } from '@stencil/core';// Import the worker directly.// Stencil will automatically create// a proxy and run the module in a worker.// IDEs and TypeScript will treat this import// no differently than any other ESM import.import { sum, expensiveTask } from '../../stuff.worker';@Component({ tag: 'my-cmp'}export class MyApp { async componentWillLoad() { // sum() will run inside a worker! and the result is a Promise const result = await sum(1, 2); console.log(result); // 3 // expensiveTask() will not block the main thread, // because it runs in parallel inside the worker. // Note that the functions must be async. const newBuffer = await expensiveTask(buffer); console.log(newBuffer); }}
Under the hood, Stencil compiles a worker file and uses the standard `new Worker()` API to instantiate the worker. Then it creates proxies for each of the exported functions, so developers can interact with it using [structured programming constructs](https://en.wikipedia.org/wiki/Structured_programming)
instead of event-based ones.
note
Workers are already placed in a different chunk, and dynamically loaded using `new Worker()`. You should avoid using a dynamic `import()` to load them, as this will cause two network requests. Instead, use ES module imports as it's only importing the proxies for communicating with the worker.
### Imports within a worker[](https://stenciljs.com/docs/v4.34/web-workers#imports-within-a-worker "Direct link to Imports within a worker")
Normal `ESM` imports are possible when building workers in Stencil. Under the hood, the compiler bundles all the dependencies of a worker into a single file that becomes the worker's entry-point, a dependency-free file that can run without problems.
**src/loader.worker.ts:**
import upngjs from 'upng-js';import { Images } from './materials';export const loadTexture = async (imagesSrcs: Images) => { const images = await Promise.all( imagesSrcs.map(loadOriginalImage) ); return images;}async function loadOriginalImage(src: string) { const res = await fetch(src); const png = upngjs.decode(await res.arrayBuffer()); return png;}
In this example, we are building a worker called `loader.worker.ts` that imports an NPM dependency (`upngjs`, used to parse png files), and a local module (`./materials`). Stencil will use [Rollup](https://rollupjs.org/guide/en/)
to bundle all dependencies and remove all imports at runtime. Be aware that code will be duplicated if imported inside and outside a worker.
#### Dynamic imports[](https://stenciljs.com/docs/v4.34/web-workers#dynamic-imports "Direct link to Dynamic imports")
In order to load scripts dynamically inside of a worker, Web Workers come with a handy API, [`importScript()`](https://developer.mozilla.org/en-US/docs/Web/API/WorkerGlobalScope/importScripts)
.
Here's an example of how to use `typescript` directly from a CDN with `importScript()`.
importScripts("https://cdn.jsdelivr.net/npm/typescript@latest/lib/typescript.js");
note
Do not use `importScript()` to import NPM dependencies you have installed using `npm` or `yarn`. Use normal ES module imports as usual, so the bundler can understand it.
### Worker Callbacks[](https://stenciljs.com/docs/v4.34/web-workers#worker-callbacks "Direct link to Worker Callbacks")
In most cases, waiting for a Promise to resolve with the output data is all we'll need. However, a limitation with native Promises is that it provides only one returned value. Where a traditional callback still shines is that it can be called numerous times with different data.
Let's say that we have a long running process that may take a few seconds to complete. With a Promise, we're unable to periodically receive the progress of the task, since all we can do is wait for Promise to resolve.
A feature with Stencil's worker is the ability to pass a callback to the method, and within the worker, execute the callback as much as it's needed before the task resolves.
In the example below, the task is given a number that it counts down from the number provided, and the task completes when it gets to `0`. During the count down, however, the main thread will still receive an update every second. This example will console log from `5` to `0`
**src/countdown.worker.ts:**
export const countDown = (num: number, progress: (p: number) => void) => { return new Promise(resolve => { const tmr = setInterval(() => { num--; if (num > 0) { progress(num); } else { clearInterval(tmr); resolve(num); } }, 1000); });};
**src/my-app/my-app.tsx:**
import { Component } from '@stencil/core';import { countDown } from '../countdown.worker';@Component({ tag: 'my-cmp'}export class MyApp { componentWillLoad() { const startNum = 5; console.log('start', startNum); countDown(startNum, (p) => { console.log('progress', p); }).then(result => { console.log('finish', result); }); }}
When executed, the result would take 5 seconds and would log:
start 5progress 4progress 3progress 2progress 1finish 0
Advanced cases[](https://stenciljs.com/docs/v4.34/web-workers#advanced-cases "Direct link to Advanced cases")
---------------------------------------------------------------------------------------------------------------
Sometimes it might be necessary to access the actual [`Worker`](https://developer.mozilla.org/en-US/docs/Web/API/Worker)
instance, because manual usage of the [`postMessage()`](https://developer.mozilla.org/en-US/docs/Web/API/Worker/postMessage)
and [`onmessage`](https://developer.mozilla.org/en-US/docs/Web/API/DedicatedWorkerGlobalScope/onmessage)
is desired. However, there's still a tooling challenge in having to bundle the worker, and have the main bundle correctly reference the worker bundle url path. In that case, Stencil also has an API that exposes the worker directly so it can be used instead of the proxies mentioned early.
For a direct worker reference, add `?worker` at the end of an ESM import. This virtual ES module will export:
* `worker`: The actual Worker instance.
* `workerPath`: The path to the worker's entry-point (usually a path to a `.js` file).
* `workerName`: The name of the worker, useful for debugging purposes.
**src/my-app/my-app.tsx:**
import { Component } from '@stencil/core';import { sum } from '../../stuff.worker';// Using the ?worker query, allows to access the worker instance directly.import { worker } from '../../stuff.worker.ts?worker';@Component({ tag: 'my-cmp'}export class MyApp { componentWillLoad() { // Use worker api directly worker.postMessage(['send data manually']); // Use the proxy const result = await sum(1, 2); console.log(result); // 3 }}
You can even use this feature you create multiple Worker manually:
import { workerPath } from '../../stuff.worker.ts?worker';const workerPool = [ new Worker(workerPath), new Worker(workerPath), new Worker(workerPath), new Worker(workerPath),];
In this example, we exclusively take advantage of the bundling performed by the compiler to obtain the `workerPath` to the worker's entry point, then manually create a pool of workers.
note
Stencil will not instantiate a worker if it's unused, it takes advantage of tree-shaking to do this.
#### Worker Termination[](https://stenciljs.com/docs/v4.34/web-workers#worker-termination "Direct link to Worker Termination")
Any Web Workers can be terminated using the [`Worker.terminate()`](https://developer.mozilla.org/en-US/docs/Web/API/Worker/terminate)
API, but since Stencil creates one worker shared across all the proxied methods, it's not recommended to terminate it manually. If you have a use-case for using `terminate` and rebuilding workers, then we recommend using the `workerPath` and creating a new Worker directly:
import { workerPath } from '../../stuff.worker.ts?worker';const worker = new Worker(workerPath);// ...worker.terminate()
Contents
--------
* [When to use Web Workers?](https://stenciljs.com/docs/v4.34/web-workers#when-to-use-web-workers)
* [Best Practices when using Web Workers](https://stenciljs.com/docs/v4.34/web-workers#best-practices-when-using-web-workers)
* [How vanilla Web Workers "work"?](https://stenciljs.com/docs/v4.34/web-workers#how-vanilla-web-workers-work)
* [Web Workers with Stencil](https://stenciljs.com/docs/v4.34/web-workers#web-workers-with-stencil)
* [Imports within a worker](https://stenciljs.com/docs/v4.34/web-workers#imports-within-a-worker)
* [Worker Callbacks](https://stenciljs.com/docs/v4.34/web-workers#worker-callbacks)
* [Advanced cases](https://stenciljs.com/docs/v4.34/web-workers#advanced-cases)
* * *
[Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.34/guides/workers.md)
---
# Build Conditionals | Stencil
[Skip to main content](https://stenciljs.com/docs/v4.34/guides/build-conditionals#__docusaurus_skipToContent_fallback)
[An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none)
This is documentation for Stencil **v4.34**, which is no longer actively maintained.
For up-to-date documentation, see the **[latest version](https://stenciljs.com/docs/guides/build-conditionals)
** (v4.35).
Version: v4.34
On this page
Build Conditionals in Stencil allow you to run specific code only when Stencil is running in development mode. This code is stripped from your bundles when doing a production build, therefore keeping your bundles as small as possible.
### Using Build Conditionals[](https://stenciljs.com/docs/v4.34/guides/build-conditionals#using-build-conditionals "Direct link to Using Build Conditionals")
Lets dive in and look at an example of how to use our build conditional:
import { Component, Build } from '@stencil/core';@Component({ tag: 'stencil-app', styleUrl: 'stencil-app.css'})export class StencilApp { componentDidLoad() { if (Build.isDev) { console.log('im in dev mode'); } else { console.log('im running in production'); } }}
As you can see from this example, we just need to import `Build` from `@stencil/core` and then we can use the `isDev` constant to detect when we are running in dev mode or production mode.
### Use Cases[](https://stenciljs.com/docs/v4.34/guides/build-conditionals#use-cases "Direct link to Use Cases")
Some use cases we have come up with are:
* Diagnostics code that runs in dev to make sure logic is working like you would expect
* `console.log()`'s that may be useful for debugging in dev mode but that you don't want to ship
* Disabling auth checks when in dev mode
Contents
--------
* [Using Build Conditionals](https://stenciljs.com/docs/v4.34/guides/build-conditionals#using-build-conditionals)
* [Use Cases](https://stenciljs.com/docs/v4.34/guides/build-conditionals#use-cases)
* * *
[Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.34/guides/build-conditionals.md)
---
# Design Systems | Stencil
[Skip to main content](https://stenciljs.com/docs/v4.34/design-systems#__docusaurus_skipToContent_fallback)
[An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none)
This is documentation for Stencil **v4.34**, which is no longer actively maintained.
For up-to-date documentation, see the **[latest version](https://stenciljs.com/docs/design-systems)
** (v4.35).
Version: v4.34
On this page
What is a Design System?[](https://stenciljs.com/docs/v4.34/design-systems#what-is-a-design-system "Direct link to What is a Design System?")
-----------------------------------------------------------------------------------------------------------------------------------------------
A Design System consists of UI components and a clearly defined visual style, released as both code implementations and design artifacts. When adopted by all product teams, a more cohesive customer experience emerges.
There are several aspects that Design Systems consist of:
### Components[](https://stenciljs.com/docs/v4.34/design-systems#components "Direct link to Components")
A component is a standalone UI element designed to be reusable across many projects. Its goal is to do one thing well, while remaining abstract enough to allow for a variety of use cases. Developers can use them as building blocks to build new user experiences. One of the key benefits of reusable components is that developers don't have to worry about the core design and functionality of each component every time they use them. Examples include buttons, links, forms, input fields, and modals.
### Patterns[](https://stenciljs.com/docs/v4.34/design-systems#patterns "Direct link to Patterns")
A pattern is an opinionated use of components. Often, multiple components are combined in order to create a standardized user experience (UX). As a result, they improve both the user and developer experience. After implementing patterns, users will understand the application better and accomplish their tasks faster. When the development team understands the proper way to use components together, software applications become easier to use. Examples include saving data to the system, capturing data from forms, and filtering and analyzing data.
### Visual Language[](https://stenciljs.com/docs/v4.34/design-systems#visual-language "Direct link to Visual Language")
A cohesive company brand strengthens its value in the minds of the customer. In the context of design systems, this means defining various aspects of the visual style, including colors, typography, and icons. Defining primary, secondary, and tertiary colors helps an application stand out and is more user-friendly. The right typography ensures users are not distracted while using an app. Finally, icons increase engagement in a product and make it “pop” visually.
### Design Artifacts and Code Implementations[](https://stenciljs.com/docs/v4.34/design-systems#design-artifacts-and-code-implementations "Direct link to Design Artifacts and Code Implementations")
By leveraging the components, patterns, and visual language of the design system, designers can create design artifacts representing UI workflows. Developers refer to the artifacts as guidance for implementing the design with code.
The Value of Design Systems[](https://stenciljs.com/docs/v4.34/design-systems#the-value-of-design-systems "Direct link to The Value of Design Systems")
---------------------------------------------------------------------------------------------------------------------------------------------------------
With a design system in place, its true value is revealed. The entire product development team is freed up to focus on what matters most: solving customer problems and delivering value. Additionally, the avoidance of having teams working in parallel, recreating the same UI elements over and over, has a real-world project impact in terms of reduced time to market and increased cost savings.
Design systems allow project teams to work better together. Designers define a centralized “source of truth” for software application best practices which can be referenced by anyone in a product organization. Developers no longer need to spend time rethinking how to build common app scenarios, such as application search or data table grids. When the business inevitably makes changes to the design system, they can easily be applied to all projects. The end result is a better product for your users.
Using Stencil to Build a Design System[](https://stenciljs.com/docs/v4.34/design-systems#using-stencil-to-build-a-design-system "Direct link to Using Stencil to Build a Design System")
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
There’s a lot that goes into creating amazing UI components. Performance, accessibility, cross-platform capabilities, and user experience (not only of the UI component itself but how it fits into the entire design system) all must be considered.
These aspects take real effort to do well.
Enter Stencil, a robust and highly extensible tool for building components and patterns, the building blocks of a design system. With its intentionally minimalistic tooling and API footprint, it’s simple to incorporate into your existing development workflows. It brings substantial performance out of the box by leveraging a tiny runtime. Most importantly, all UI components built with Stencil are based 100% on open web standards.
### The Importance of Open Web Standards[](https://stenciljs.com/docs/v4.34/design-systems#the-importance-of-open-web-standards "Direct link to The Importance of Open Web Standards")
By using the web components standard, supported in all modern browsers, Stencil-built UI components offer many distinct advantages for use in a design system, namely:
* They work on any platform or device
* They work with any front-end framework, so they can easily be used across teams and projects using different tech stacks
* They facilitate the creation of one company-wide code implementation instead of one per framework or platform
Learn more about why web components are ideal for design systems in [this blog post](https://blog.ionicframework.com/5-reasons-web-components-are-perfect-for-design-systems/)
.
### How to Get Started[](https://stenciljs.com/docs/v4.34/design-systems#how-to-get-started "Direct link to How to Get Started")
Stencil’s out-the-box features will help you build your own library of universal UI components that will work across platforms, devices, and front-end frameworks. Review the documentation on this site to get started.
Contents
--------
* [What is a Design System?](https://stenciljs.com/docs/v4.34/design-systems#what-is-a-design-system)
* [Components](https://stenciljs.com/docs/v4.34/design-systems#components)
* [Patterns](https://stenciljs.com/docs/v4.34/design-systems#patterns)
* [Visual Language](https://stenciljs.com/docs/v4.34/design-systems#visual-language)
* [Design Artifacts and Code Implementations](https://stenciljs.com/docs/v4.34/design-systems#design-artifacts-and-code-implementations)
* [The Value of Design Systems](https://stenciljs.com/docs/v4.34/design-systems#the-value-of-design-systems)
* [Using Stencil to Build a Design System](https://stenciljs.com/docs/v4.34/design-systems#using-stencil-to-build-a-design-system)
* [The Importance of Open Web Standards](https://stenciljs.com/docs/v4.34/design-systems#the-importance-of-open-web-standards)
* [How to Get Started](https://stenciljs.com/docs/v4.34/design-systems#how-to-get-started)
* * *
[Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.34/guides/design-systems.md)
---
# Web Workers | Stencil
[Skip to main content](https://stenciljs.com/docs/v4.33/web-workers#__docusaurus_skipToContent_fallback)
[An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none)
This is documentation for Stencil **v4.33**, which is no longer actively maintained.
For up-to-date documentation, see the **[latest version](https://stenciljs.com/docs/web-workers)
** (v4.35).
Version: v4.33
On this page
[Web Workers](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers)
are a widely supported technology (Chrome, Firefox, Safari and Edge) that allows JavaScript to execute in a different thread, maximizing the usage of multiple CPUs; but most importantly not blocking the **main thread**.
The **main thread** is where JavaScript runs by default and has access to the `document`, `window` and other DOM APIs. The problem is that long-running JS prevents the browser from running smooth animations (CSS animations, transitions, canvas, svg...), making your site look frozen. That's why if your application needs to run CPU-intensive tasks, Web Workers are a great help.
When to use Web Workers?[](https://stenciljs.com/docs/v4.33/web-workers#when-to-use-web-workers "Direct link to When to use Web Workers?")
--------------------------------------------------------------------------------------------------------------------------------------------
The first thing to understand is when to use a Web Workers, and when _not_ to use them since they come with a set of costs and limitations:
* There is no access to the [DOM](https://developer.mozilla.org/en-US/docs/Web/API/Document_Object_Model/Introduction)
. This means you cannot interact with `document`, `window` or any elements in the page.
* There is no access to any of the `@stencil/core` APIs. For example, you cannot declare and use a component in a Web Worker, for the same reasons there is **no access to the DOM**.
* A Web Worker has its own **isolated state** since each worker has their own memory space. For example, a variable declared on the main thread cannot be directly referenced from a worker.
* There is an overhead when passing data between workers and the main thread. As a general rule, it's best to minimize the amount of data sent to and from the worker and be mindful if the work to send your data takes more time than doing it on the main thread.
* Communication is always **asynchronous**. Luckily Promises and async/await makes this relatively easy, but it's important to understand that communication between threads is always asynchronous.
* You can **only** pass [primitives](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Primitive_values)
and objects that implement the [structured clone algorithm](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm)
. Best way to think of it is any data that can be serialized to JSON is safe to use.
In short, it's generally a good idea to use workers to move logic that is thread-blocking -- or UI-blocking, preventing users from interacting with the page -- into a Web Worker, such as real-time code syntax highlighting.
Best Practices when using Web Workers[](https://stenciljs.com/docs/v4.33/web-workers#best-practices-when-using-web-workers "Direct link to Best Practices when using Web Workers")
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
* Use pure and functional algorithms in workers. `(input1, input2) => output`.
* The worker logic itself can be as complex as it has to be, however, the input and output data should stay fairly simple.
* Look for ways to reduce passing data between the main thread and worker thread.
* Class instances cannot be passed as data. Instead, only work with data can be JSON serializable.
* Minimize state within the worker, or better yet, completely avoid maintaining any state (e.g., don't put redux inside a worker).
* The cost of a worker should be easily amortized because it would be doing some CPU-intensive jobs.
How vanilla Web Workers "work"?[](https://stenciljs.com/docs/v4.33/web-workers#how-vanilla-web-workers-work "Direct link to How vanilla Web Workers "work"?")
---------------------------------------------------------------------------------------------------------------------------------------------------------------
The browser comes with a `Worker` API, that works the following way:
const worker = new Worker('/my-worker.js');worker.postMessage(['send message to worker']);worker.onmessage = (ev) => { console.log('data from worker', ev.data);};
This API, while powerful, is very low level and makes it tedious to write complex apps, since the event-driven paradigm leads easily to [spaghetti-code](https://en.wikipedia.org/wiki/Spaghetti_code)
, and quickly misses out on strongly-typed functions and data.
For further information, check out [this fantastic tutorial](https://www.html5rocks.com/en/tutorials/workers/basics/)
by our friends at HTML5Rocks.
A Web Worker also requires the generation of a separate JavaScript bundle, such as the `my-worker.js` file in the example above. This means you usually need extra build scripts and tooling that transpiles and bundles the worker entry point into another `.js` file. Additionally, the main bundle must be able to reference the worker bundle's file location, which is oftentimes a challenge after transpiling, bundling, minifying, filename hashing and deploying to production servers.
Fortunately, Stencil can help you solve these two problems:
* Tooling: Transpiling, bundling, hashing, worker url path referencing
* Communication: Converting event-based communication to Promises, while still maintaining types.
Web Workers with Stencil[](https://stenciljs.com/docs/v4.33/web-workers#web-workers-with-stencil "Direct link to Web Workers with Stencil")
---------------------------------------------------------------------------------------------------------------------------------------------
As we already mention, Stencil's compiler can help you to use workers in production seamlessly. Any TypeScript file within the `src` directory that ends with `.worker.ts` will automatically use a worker. For example:
**src/stuff.worker.ts:**
export const sum = async (a: number, b: number) => { return a + b;}export const expensiveTask = async (buffer: ArrayBuffer) => { for (let i = 0; i < buffer.length; i++) { // do a lot of processing } return buffer;};
**src/my-app/my-app.tsx:**
import { Component } from '@stencil/core';// Import the worker directly.// Stencil will automatically create// a proxy and run the module in a worker.// IDEs and TypeScript will treat this import// no differently than any other ESM import.import { sum, expensiveTask } from '../../stuff.worker';@Component({ tag: 'my-cmp'}export class MyApp { async componentWillLoad() { // sum() will run inside a worker! and the result is a Promise const result = await sum(1, 2); console.log(result); // 3 // expensiveTask() will not block the main thread, // because it runs in parallel inside the worker. // Note that the functions must be async. const newBuffer = await expensiveTask(buffer); console.log(newBuffer); }}
Under the hood, Stencil compiles a worker file and uses the standard `new Worker()` API to instantiate the worker. Then it creates proxies for each of the exported functions, so developers can interact with it using [structured programming constructs](https://en.wikipedia.org/wiki/Structured_programming)
instead of event-based ones.
note
Workers are already placed in a different chunk, and dynamically loaded using `new Worker()`. You should avoid using a dynamic `import()` to load them, as this will cause two network requests. Instead, use ES module imports as it's only importing the proxies for communicating with the worker.
### Imports within a worker[](https://stenciljs.com/docs/v4.33/web-workers#imports-within-a-worker "Direct link to Imports within a worker")
Normal `ESM` imports are possible when building workers in Stencil. Under the hood, the compiler bundles all the dependencies of a worker into a single file that becomes the worker's entry-point, a dependency-free file that can run without problems.
**src/loader.worker.ts:**
import upngjs from 'upng-js';import { Images } from './materials';export const loadTexture = async (imagesSrcs: Images) => { const images = await Promise.all( imagesSrcs.map(loadOriginalImage) ); return images;}async function loadOriginalImage(src: string) { const res = await fetch(src); const png = upngjs.decode(await res.arrayBuffer()); return png;}
In this example, we are building a worker called `loader.worker.ts` that imports an NPM dependency (`upngjs`, used to parse png files), and a local module (`./materials`). Stencil will use [Rollup](https://rollupjs.org/guide/en/)
to bundle all dependencies and remove all imports at runtime. Be aware that code will be duplicated if imported inside and outside a worker.
#### Dynamic imports[](https://stenciljs.com/docs/v4.33/web-workers#dynamic-imports "Direct link to Dynamic imports")
In order to load scripts dynamically inside of a worker, Web Workers come with a handy API, [`importScript()`](https://developer.mozilla.org/en-US/docs/Web/API/WorkerGlobalScope/importScripts)
.
Here's an example of how to use `typescript` directly from a CDN with `importScript()`.
importScripts("https://cdn.jsdelivr.net/npm/typescript@latest/lib/typescript.js");
note
Do not use `importScript()` to import NPM dependencies you have installed using `npm` or `yarn`. Use normal ES module imports as usual, so the bundler can understand it.
### Worker Callbacks[](https://stenciljs.com/docs/v4.33/web-workers#worker-callbacks "Direct link to Worker Callbacks")
In most cases, waiting for a Promise to resolve with the output data is all we'll need. However, a limitation with native Promises is that it provides only one returned value. Where a traditional callback still shines is that it can be called numerous times with different data.
Let's say that we have a long running process that may take a few seconds to complete. With a Promise, we're unable to periodically receive the progress of the task, since all we can do is wait for Promise to resolve.
A feature with Stencil's worker is the ability to pass a callback to the method, and within the worker, execute the callback as much as it's needed before the task resolves.
In the example below, the task is given a number that it counts down from the number provided, and the task completes when it gets to `0`. During the count down, however, the main thread will still receive an update every second. This example will console log from `5` to `0`
**src/countdown.worker.ts:**
export const countDown = (num: number, progress: (p: number) => void) => { return new Promise(resolve => { const tmr = setInterval(() => { num--; if (num > 0) { progress(num); } else { clearInterval(tmr); resolve(num); } }, 1000); });};
**src/my-app/my-app.tsx:**
import { Component } from '@stencil/core';import { countDown } from '../countdown.worker';@Component({ tag: 'my-cmp'}export class MyApp { componentWillLoad() { const startNum = 5; console.log('start', startNum); countDown(startNum, (p) => { console.log('progress', p); }).then(result => { console.log('finish', result); }); }}
When executed, the result would take 5 seconds and would log:
start 5progress 4progress 3progress 2progress 1finish 0
Advanced cases[](https://stenciljs.com/docs/v4.33/web-workers#advanced-cases "Direct link to Advanced cases")
---------------------------------------------------------------------------------------------------------------
Sometimes it might be necessary to access the actual [`Worker`](https://developer.mozilla.org/en-US/docs/Web/API/Worker)
instance, because manual usage of the [`postMessage()`](https://developer.mozilla.org/en-US/docs/Web/API/Worker/postMessage)
and [`onmessage`](https://developer.mozilla.org/en-US/docs/Web/API/DedicatedWorkerGlobalScope/onmessage)
is desired. However, there's still a tooling challenge in having to bundle the worker, and have the main bundle correctly reference the worker bundle url path. In that case, Stencil also has an API that exposes the worker directly so it can be used instead of the proxies mentioned early.
For a direct worker reference, add `?worker` at the end of an ESM import. This virtual ES module will export:
* `worker`: The actual Worker instance.
* `workerPath`: The path to the worker's entry-point (usually a path to a `.js` file).
* `workerName`: The name of the worker, useful for debugging purposes.
**src/my-app/my-app.tsx:**
import { Component } from '@stencil/core';import { sum } from '../../stuff.worker';// Using the ?worker query, allows to access the worker instance directly.import { worker } from '../../stuff.worker.ts?worker';@Component({ tag: 'my-cmp'}export class MyApp { componentWillLoad() { // Use worker api directly worker.postMessage(['send data manually']); // Use the proxy const result = await sum(1, 2); console.log(result); // 3 }}
You can even use this feature you create multiple Worker manually:
import { workerPath } from '../../stuff.worker.ts?worker';const workerPool = [ new Worker(workerPath), new Worker(workerPath), new Worker(workerPath), new Worker(workerPath),];
In this example, we exclusively take advantage of the bundling performed by the compiler to obtain the `workerPath` to the worker's entry point, then manually create a pool of workers.
note
Stencil will not instantiate a worker if it's unused, it takes advantage of tree-shaking to do this.
#### Worker Termination[](https://stenciljs.com/docs/v4.33/web-workers#worker-termination "Direct link to Worker Termination")
Any Web Workers can be terminated using the [`Worker.terminate()`](https://developer.mozilla.org/en-US/docs/Web/API/Worker/terminate)
API, but since Stencil creates one worker shared across all the proxied methods, it's not recommended to terminate it manually. If you have a use-case for using `terminate` and rebuilding workers, then we recommend using the `workerPath` and creating a new Worker directly:
import { workerPath } from '../../stuff.worker.ts?worker';const worker = new Worker(workerPath);// ...worker.terminate()
Contents
--------
* [When to use Web Workers?](https://stenciljs.com/docs/v4.33/web-workers#when-to-use-web-workers)
* [Best Practices when using Web Workers](https://stenciljs.com/docs/v4.33/web-workers#best-practices-when-using-web-workers)
* [How vanilla Web Workers "work"?](https://stenciljs.com/docs/v4.33/web-workers#how-vanilla-web-workers-work)
* [Web Workers with Stencil](https://stenciljs.com/docs/v4.33/web-workers#web-workers-with-stencil)
* [Imports within a worker](https://stenciljs.com/docs/v4.33/web-workers#imports-within-a-worker)
* [Worker Callbacks](https://stenciljs.com/docs/v4.33/web-workers#worker-callbacks)
* [Advanced cases](https://stenciljs.com/docs/v4.33/web-workers#advanced-cases)
* * *
[Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.33/guides/workers.md)
---
# Build Conditionals | Stencil
[Skip to main content](https://stenciljs.com/docs/v4.33/guides/build-conditionals#__docusaurus_skipToContent_fallback)
[An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none)
This is documentation for Stencil **v4.33**, which is no longer actively maintained.
For up-to-date documentation, see the **[latest version](https://stenciljs.com/docs/guides/build-conditionals)
** (v4.35).
Version: v4.33
On this page
Build Conditionals in Stencil allow you to run specific code only when Stencil is running in development mode. This code is stripped from your bundles when doing a production build, therefore keeping your bundles as small as possible.
### Using Build Conditionals[](https://stenciljs.com/docs/v4.33/guides/build-conditionals#using-build-conditionals "Direct link to Using Build Conditionals")
Lets dive in and look at an example of how to use our build conditional:
import { Component, Build } from '@stencil/core';@Component({ tag: 'stencil-app', styleUrl: 'stencil-app.css'})export class StencilApp { componentDidLoad() { if (Build.isDev) { console.log('im in dev mode'); } else { console.log('im running in production'); } }}
As you can see from this example, we just need to import `Build` from `@stencil/core` and then we can use the `isDev` constant to detect when we are running in dev mode or production mode.
### Use Cases[](https://stenciljs.com/docs/v4.33/guides/build-conditionals#use-cases "Direct link to Use Cases")
Some use cases we have come up with are:
* Diagnostics code that runs in dev to make sure logic is working like you would expect
* `console.log()`'s that may be useful for debugging in dev mode but that you don't want to ship
* Disabling auth checks when in dev mode
Contents
--------
* [Using Build Conditionals](https://stenciljs.com/docs/v4.33/guides/build-conditionals#using-build-conditionals)
* [Use Cases](https://stenciljs.com/docs/v4.33/guides/build-conditionals#use-cases)
* * *
[Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.33/guides/build-conditionals.md)
---
# Working with host elements | Stencil
[Skip to main content](https://stenciljs.com/docs/v4.33/host-element#__docusaurus_skipToContent_fallback)
[An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none)
This is documentation for Stencil **v4.33**, which is no longer actively maintained.
For up-to-date documentation, see the **[latest version](https://stenciljs.com/docs/host-element)
** (v4.35).
Version: v4.33
On this page
Stencil components render their children declaratively in their `render` method [using JSX](https://stenciljs.com/docs/v4.33/templating-jsx)
. Most of the time, the `render()` function describes the children elements that are about to be rendered, but it can also be used to render attributes of the host element itself.
``[](https://stenciljs.com/docs/v4.33/host-element#host "Direct link to host")
--------------------------------------------------------------------------------------
The `Host` functional component can be used at the root of the render function to set attributes and event listeners to the host element itself. This works just like any other JSX:
// Host is imported from '@stencil/core'import { Component, Host, h } from '@stencil/core';@Component({tag: 'todo-list'})export class TodoList { @Prop() open = false; render() { return ( ` is a virtual component, a virtual API exposed by stencil to declaratively set the attributes of the host element, it will never be rendered in the DOM, i.e. you will never see `` in Chrome Dev Tools for instance.
### `` can work as a ``[](https://stenciljs.com/docs/v4.33/host-element#host-can-work-as-a-fragment "Direct link to host-can-work-as-a-fragment")
`` can also be used when more than one component needs to be rendered at the root level for example:
It could be achieved by a `render()` method like this:
@Component({tag: 'my-cmp'})export class MyCmp { render() { return ( ); }}
This JSX would render the following HTML:
Even if we don't use `` to render any attribute in the host element, it's a useful API to render many elements at the root level.
Element Decorator[](https://stenciljs.com/docs/v4.33/host-element#element-decorator "Direct link to Element Decorator")
-------------------------------------------------------------------------------------------------------------------------
The `@Element()` decorator is how to get access to the host element within the class instance. This returns an instance of an `HTMLElement`, so standard DOM methods/events can be used here.
import { Element } from '@stencil/core';...export class TodoList { @Element() el: HTMLElement; getListHeight(): number { return this.el.getBoundingClientRect().height; }}
In order to reference the host element when initializing a class member you'll need to use TypeScript's definite assignment assertion modifier to avoid a type error:
import { Element } from '@stencil/core';...export class TodoList { @Element() el!: HTMLElement; private listHeight = this.el.getBoundingClientRect().height;}
If you need to update the host element in response to prop or state changes, you should do so in the `render()` method using the `` element.
Styling[](https://stenciljs.com/docs/v4.33/host-element#styling "Direct link to Styling")
-------------------------------------------------------------------------------------------
See full information about styling on the [Styling page](https://stenciljs.com/docs/v4.33/styling#shadow-dom-in-stencil)
.
CSS can be applied to the `` element by using its component tag defined in the `@Component` decorator.
@Component({ tag: 'my-cmp', styleUrl: 'my-cmp.css'})...
my-cmp.css:
my-cmp { width: 100px;}
### Shadow DOM[](https://stenciljs.com/docs/v4.33/host-element#shadow-dom "Direct link to Shadow DOM")
Something to beware of is that Styling the `` element when using shadow DOM does not work quite the same. Instead of using the `my-cmp` element selector you must use `:host`.
@Component({ tag: 'my-cmp', styleUrl: 'my-cmp.css', shadow: true})...
my-cmp.css:
:host { width: 100px;}
Contents
--------
* [``](https://stenciljs.com/docs/v4.33/host-element#host)
* [`` can work as a ``](https://stenciljs.com/docs/v4.33/host-element#host-can-work-as-a-fragment)
* [Element Decorator](https://stenciljs.com/docs/v4.33/host-element#element-decorator)
* [Styling](https://stenciljs.com/docs/v4.33/host-element#styling)
* [Shadow DOM](https://stenciljs.com/docs/v4.33/host-element#shadow-dom)
* * *
[Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.33/components/host-element.md)
---
# Styling Components | Stencil
[Skip to main content](https://stenciljs.com/docs/v4.34/styling#__docusaurus_skipToContent_fallback)
[An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none)
This is documentation for Stencil **v4.34**, which is no longer actively maintained.
For up-to-date documentation, see the **[latest version](https://stenciljs.com/docs/styling)
** (v4.35).
Version: v4.34
On this page
Shadow DOM[](https://stenciljs.com/docs/v4.34/styling#shadow-dom "Direct link to Shadow DOM")
-----------------------------------------------------------------------------------------------
### What is the Shadow DOM?[](https://stenciljs.com/docs/v4.34/styling#what-is-the-shadow-dom "Direct link to What is the Shadow DOM?")
The [shadow DOM](https://developers.google.com/web/fundamentals/web-components/shadowdom)
is an API built into the browser that allows for DOM encapsulation and style encapsulation. It is a core aspect of the Web Component standards. The shadow DOM shields a component's styles, markup, and behavior from its surrounding environment. This means that we do not need to be concerned about scoping our CSS to our component, nor worry about a component's internal DOM being interfered with by anything outside the component.
When talking about the shadow DOM, we use the term "light DOM" to refer to the "regular" DOM. The light DOM encompasses any part of the DOM that does not use the shadow DOM.
### Shadow DOM in Stencil[](https://stenciljs.com/docs/v4.34/styling#shadow-dom-in-stencil "Direct link to Shadow DOM in Stencil")
The shadow DOM hides and separates the DOM of a component in order to prevent clashing styles or unwanted side effects. We can use the shadow DOM in our Stencil components to ensure our components won't be affected by the applications in which they are used.
To use the Shadow DOM in a Stencil component, you can set the `shadow` option to `true` in the component decorator.
@Component({ tag: 'shadow-component', styleUrl: 'shadow-component.css', shadow: true,})export class ShadowComponent {}
If you'd like to learn more about enabling and configuring the shadow DOM, see the [shadow field of the component api](https://stenciljs.com/docs/v4.34/component#component-options)
.
By default, components created with the [`stencil generate` command](https://stenciljs.com/docs/v4.34/cli#stencil-generate)
use the shadow DOM.
### Styling with the Shadow DOM[](https://stenciljs.com/docs/v4.34/styling#styling-with-the-shadow-dom "Direct link to Styling with the Shadow DOM")
With the shadow DOM enabled, elements within the shadow root are scoped, and styles outside of the component do not apply. As a result, CSS selectors inside the component can be simplified, as they will only apply to elements within the component. We do not have to include any specific selectors to scope styles to the component.
:host { color: black;}div { background: blue;}
note
The `:host` pseudo-class selector is used to select the [`Host` element](https://stenciljs.com/docs/v4.34/host-element)
of the component
With the shadow DOM enabled, only these styles will be applied to the component. Even if a style in the light DOM uses a selector that matches an element in the component, those styles will not be applied.
### Shadow DOM QuerySelector[](https://stenciljs.com/docs/v4.34/styling#shadow-dom-queryselector "Direct link to Shadow DOM QuerySelector")
When using Shadow DOM and you want to query an element inside your web component, you must first use the [`@Element` decorator](https://stenciljs.com/docs/v4.34/host-element#element-decorator)
to gain access to the host element, and then you can use the `shadowRoot` property to perform the query. This is because all of your DOM inside your web component is in a shadowRoot that Shadow DOM creates. For example:
import { Component, Element } from '@stencil/core';@Component({ tag: 'shadow-component', styleUrl: 'shadow-component.css', shadow: true})export class ShadowComponent { @Element() el: HTMLElement; componentDidLoad() { const elementInShadowDom = this.el.shadowRoot.querySelector('.a-class-selector'); ... }}
### Shadow DOM Browser Support[](https://stenciljs.com/docs/v4.34/styling#shadow-dom-browser-support "Direct link to Shadow DOM Browser Support")
The shadow DOM is currently natively supported in the following browsers:
* Chrome
* Firefox
* Safari
* Edge (v79+)
* Opera
In browsers which do not support the shadow DOM we fall back to scoped CSS. This gives you the style encapsulation that comes along with the shadow DOM but without loading in a huge shadow DOM polyfill.
### Scoped CSS[](https://stenciljs.com/docs/v4.34/styling#scoped-css "Direct link to Scoped CSS")
An alternative to using the shadow DOM is using scoped components. You can use scoped components by setting the `scoped` option to `true` in the component decorator.
@Component({ tag: 'scoped-component', styleUrl: 'scoped-component.css', scoped: true,})export class ScopedComponent {}
Scoped CSS is a proxy for style encapsulation. It works by appending a data attribute to your styles to make them unique and thereby scope them to your component. It does not, however, prevent styles from the light DOM from seeping into your component.
CSS Custom Properties[](https://stenciljs.com/docs/v4.34/styling#css-custom-properties "Direct link to CSS Custom Properties")
--------------------------------------------------------------------------------------------------------------------------------
CSS custom properties, also often referred to as CSS variables, are used to contain values that can then be used in multiple CSS declarations. For example, we can create a custom property called `--color-primary` and assign it a value of `blue`.
:host { --color-primary: blue;}
And then we can use that custom property to style different parts of our component
h1 { color: var(--color-primary);}
### Customizing Components with Custom Properties[](https://stenciljs.com/docs/v4.34/styling#customizing-components-with-custom-properties "Direct link to Customizing Components with Custom Properties")
CSS custom properties can allow the consumers of a component to customize a component's styles from the light DOM. Consider a `shadow-card` component that uses a custom property for the color of the card heading.
:host { --heading-color: black;}.heading { color: var(--heading-color);}
note
CSS custom properties must be declared on the `Host` element (`:host`) in order for them to be exposed to the consuming application.
The `shadow-card` heading will have a default color of `black`, but this can now be changed in the light DOM by selecting the `shadow-card` and changing the value of the `--heading-color` custom property.
shadow-card { --heading-color: blue;}
CSS Parts[](https://stenciljs.com/docs/v4.34/styling#css-parts "Direct link to CSS Parts")
--------------------------------------------------------------------------------------------
CSS custom properties can be helpful for customizing components from the light DOM, but they are still a little limiting as they only allow a user to modify specific properties. For situations where users require a higher degree of flexibility, we recommend using the [CSS `::part()` pseudo-element](https://developer.mozilla.org/en-US/docs/Web/CSS/::part)
. You can define parts on elements of your component with the "part" attribute.
@Component({ tag: 'shadow-card', styleUrl: 'shadow-card.css', shadow: true,})export class ShadowCard { @Prop() heading: string; render() { return ( ); }}
Then you can use the `::part()` pseudo-class on the host element to give any styles you want to the element with the corresponding part.
shadow-card::part(heading) { text-transform: uppercase;}
This allows for greater flexibility in styling as any styles can now be added to this element.
### Exportparts[](https://stenciljs.com/docs/v4.34/styling#exportparts "Direct link to Exportparts")
If you have a Stencil component nested within another component, any `part` specified on elements of the child component will not be exposed through the parent component. In order to expose the `part`s of the child component, you need to use the `exportparts` attribute. Consider this `OuterComponent` which contains the `InnerComponent`.
@Component({ tag: 'outer-component', styleUrl: 'outer-component.css', shadow: true,})export class OuterComponent { render() { return ( ); }}@Component({ tag: 'inner-component', styleUrl: 'inner-component.css', shadow: true,})export class InnerComponent { render() { return ( ); }}
By specifying "inner-text" as the value of the `exportparts` attribute, elements of the `InnerComponent` with a `part` of "inner-text" can now be styled in the light DOM. Even though the `InnerComponent` is not used directly, we can style its parts through the `OuterComponent`.
`, is a functional component that can be used at the root of the render function to set attributes and event listeners to the host element itself. Refer to the [Host Element](https://stenciljs.com/docs/v4.34/host-element)
page for usage info.
* **Fragment**: ``, often used via `<>...` syntax, lets you group elements without a wrapper node.
To use this feature, ensure that the following TypeScript compiler options are set:
* [`jsxFragmentFactory` is set](https://www.typescriptlang.org/tsconfig#jsxFragmentFactory)
to "Fragment"
* [`jsxFactory` is set](https://www.typescriptlang.org/tsconfig#jsxFactory)
to "h"
**Type:** `FunctionalComponent`
**Example:**
import { Component, Fragment, h } from '@stencil/core'@Component({ tag: 'cmp-fragment',})export class CmpFragment { render() { return ( <> ); }}
* **setAssetPath()**: Sets the path for Stencil to resolve local assets. Refer to the [Assets](https://stenciljs.com/docs/v4.34/assets#setassetpath)
page for usage info.
**Type:** `(path: string) => string`
**Example:**
import { setAssetPath } from '@stencil/core';setAssetPath(`{window.location.origin}/`);
* **setMode()**: Sets the style mode of a component. Refer to the [Styling](https://stenciljs.com/docs/v4.34/styling#style-modes)
page for usage info.
**Type:** `((elm: HTMLElement) => string | undefined | null) => void`
**Example:**
import { setMode } from '@stencil/core'// set mode based on a propertysetMode((el) => el.getAttribute('mode'));
* **getMode()**: Get the current style mode of your application. Refer to the [Styling](https://stenciljs.com/docs/v4.34/styling#style-modes)
page for usage info.
**Type:** `(ref: any) => string | undefined`
**Example:**
import { getMode } from '@stencil/core'getMode(this);
* **getElement()**: Retrieve a Stencil element for a given reference.
**Type:** `(ref: any) => HTMLStencilElement`
**Example:**
import { getElement } from '@stencil/core'const stencilComponent = getElement(document.querySelector('my-cmp'))if (stencilComponent) { stencilComponent.componentOnReady().then(() => { ... })}
Contents
--------
* [Decorators](https://stenciljs.com/docs/v4.34/api#decorators)
* [Lifecycle hooks](https://stenciljs.com/docs/v4.34/api#lifecycle-hooks)
* [componentOnReady()](https://stenciljs.com/docs/v4.34/api#componentonready)
* [The `appload` event](https://stenciljs.com/docs/v4.34/api#the-appload-event)
* [Other](https://stenciljs.com/docs/v4.34/api#other)
* * *
[Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.34/components/api.md)
---
# Reactive Data, Handling arrays and objects | Stencil
[Skip to main content](https://stenciljs.com/docs/v4.33/reactive-data#__docusaurus_skipToContent_fallback)
[An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none)
This is documentation for Stencil **v4.33**, which is no longer actively maintained.
For up-to-date documentation, see the **[latest version](https://stenciljs.com/docs/reactive-data)
** (v4.35).
Version: v4.33
On this page
Stencil components update when props or state on a component change.
Rendering methods[](https://stenciljs.com/docs/v4.33/reactive-data#rendering-methods "Direct link to Rendering methods")
--------------------------------------------------------------------------------------------------------------------------
When props or state change on a component, the [`render()` method](https://stenciljs.com/docs/v4.33/templating-jsx)
is scheduled to run.
The Watch Decorator (`@Watch()`)[](https://stenciljs.com/docs/v4.33/reactive-data#the-watch-decorator-watch "Direct link to the-watch-decorator-watch")
---------------------------------------------------------------------------------------------------------------------------------------------------------
`@Watch()` is a decorator that is applied to a method of a Stencil component. The decorator accepts a single argument, the name of a class member that is decorated with `@Prop()` or `@State()`, or a host attribute. A method decorated with `@Watch()` will automatically run when its associated class member or attribute changes.
// We import Prop & State to show how `@Watch()` can be used on// class members decorated with either `@Prop()` or `@State()`import { Component, Prop, State, Watch } from '@stencil/core';@Component({ tag: 'loading-indicator' })export class LoadingIndicator { // We decorate a class member with @Prop() so that we // can apply @Watch() @Prop() activated: boolean; // We decorate a class member with @State() so that we // can apply @Watch() @State() busy: boolean; // Apply @Watch() for the component's `activated` member. // Whenever `activated` changes, this method will fire. @Watch('activated') watchPropHandler(newValue: boolean, oldValue: boolean) { console.log('The old value of activated is: ', oldValue); console.log('The new value of activated is: ', newValue); } // Apply @Watch() for the component's `busy` member. // Whenever `busy` changes, this method will fire. @Watch('busy') watchStateHandler(newValue: boolean, oldValue: boolean) { console.log('The old value of busy is: ', oldValue); console.log('The new value of busy is: ', newValue); } @Watch('activated') @Watch('busy') watchMultiple(newValue: boolean, oldValue: boolean, propName:string) { console.log(`The new value of ${propName} is: `, newValue); }}
In the example above, there are two `@Watch()` decorators. One decorates `watchPropHandler`, which will fire when the class member `activated` changes. The other decorates `watchStateHandler`, which will fire when the class member `busy` changes.
When fired, the decorated method will receive the old and new values of the prop/state. This is useful for validation or the handling of side effects.
info
The `@Watch()` decorator does not fire when a component initially loads.
### Watching Native HTML Attributes[](https://stenciljs.com/docs/v4.33/reactive-data#watching-native-html-attributes "Direct link to Watching Native HTML Attributes")
Stencil's `@Watch()` decorator also allows you to watch native HTML attributes on the constructed host element. Simply include the attribute name as the argument to the decorator (this is case-sensitive):
@Watch('aria-label')onAriaLabelChange(newVal: string, oldVal: string) { console.log('Label changed:', newVal, oldVal);}
note
Since native attributes are not `@Prop()` or `State()` members of the Stencil component, they will not automatically trigger a re-render when changed. If you wish to re-render a component in this instance, you can leverage the `forceUpdate()` method:
import { Component, forceUpdate, h } from '@stencil/core';@Watch('aria-label')onAriaLabelChange() { forceUpdate(this); // Forces a re-render}
Handling Arrays and Objects[](https://stenciljs.com/docs/v4.33/reactive-data#handling-arrays-and-objects "Direct link to Handling Arrays and Objects")
--------------------------------------------------------------------------------------------------------------------------------------------------------
When Stencil checks if a class member decorated with `@Prop()` or `@State()` has changed, it checks if the reference to the class member has changed. When a class member is an object or array, and is marked with `@Prop()` or `@State`, in-place mutation of an existing entity will _not_ cause `@Watch()` to fire, as it does not change the _reference_ to the class member.
### Updating Arrays[](https://stenciljs.com/docs/v4.33/reactive-data#updating-arrays "Direct link to Updating Arrays")
For arrays, the standard mutable array operations such as `push()` and `unshift()` won't trigger a component update. These functions will change the content of the array, but won't change the reference to the array itself.
In order to make changes to an array, non-mutable array operators should be used. Non-mutable array operators return a copy of a new array that can be detected in a performant manner. These include `map()` and `filter()`, and the [spread operator syntax](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Spread_operator)
. The value returned by `map()`, `filter()`, etc., should be assigned to the `@Prop()` or `@State()` class member being watched.
For example, to push a new item to an array, create a new array with the existing values and the new value at the end:
import { Component, State, Watch, h } from '@stencil/core';@Component({ tag: 'rand-numbers'})export class RandomNumbers { // We decorate a class member with @State() so that we // can apply @Watch(). This will hold a list of randomly // generated numbers @State() randNumbers: number[] = []; private timer: NodeJS.Timer; // Apply @Watch() for the component's `randNumbers` member. // Whenever `randNumbers` changes, this method will fire. @Watch('randNumbers') watchStateHandler(newValue: number[], oldValue: number[]) { console.log('The old value of randNumbers is: ', oldValue); console.log('The new value of randNumbers is: ', newValue); } connectedCallback() { this.timer = setInterval(() => { // generate a random whole number const newVal = Math.ceil(Math.random() * 100); /** * This does not create a new array. When stencil * attempts to see if any Watched members have changed, * it sees the reference to its `randNumbers` State is * the same, and will not trigger `@Watch` or a re-render */ // this.randNumbers.push(newVal) /** * Using the spread operator, on the other hand, does * create a new array. `randNumbers` is reassigned * using the value returned by the spread operator. * The reference to `randNumbers` has changed, which * will trigger `@Watch` and a re-render */ this.randNumbers = [...this.randNumbers, newVal] }, 1000) } disconnectedCallback() { if (this.timer) { clearInterval(this.timer) } } render() { return(
Instead, use your own naming or brand. For example, [Ionic](https://ionicframework.com/)
components are all prefixed with `ion-`.
#### Name[](https://stenciljs.com/docs/style-guide#name "Direct link to Name")
Components are not actions, they are conceptually "things". It is better to use nouns instead of verbs, such as "animation" instead of "animating". "input", "tab", "nav", "menu" are some examples.
#### Modifiers[](https://stenciljs.com/docs/style-guide#modifiers "Direct link to Modifiers")
When several components are related and/or coupled, it is a good idea to share the name, and then add different modifiers, for example:
### Component (TS class)[](https://stenciljs.com/docs/style-guide#component-ts-class "Direct link to Component (TS class)")
The name of the ES6 class of the component SHOULD NOT have a prefix since classes are scoped. There is no risk of collision.
@Component({ tag: 'ion-button'})export class Button { ... }@Component({ tag: 'ion-menu'})export class Menu { ... }
TypeScript[](https://stenciljs.com/docs/style-guide#typescript "Direct link to TypeScript")
---------------------------------------------------------------------------------------------
1. **Use private variables and methods as much possible:** They are useful to detect dead code and enforce encapsulation. Note that this is a feature which TypeScript provides to help harden your code, but using `private`, `public` or `protected` does not make a difference in the actual JavaScript output.
2. **Code with Method/Prop/Event/Component decorators should have JSDocs:** This allows for documentation generation and for better user experience in an editor that has TypeScript intellisense
Code organization[](https://stenciljs.com/docs/style-guide#code-organization "Direct link to Code organization")
------------------------------------------------------------------------------------------------------------------
**Newspaper Metaphor from The Robert C. Martin's _Clean Code_**
note
The source file should be organized like a newspaper article, with the highest level summary at the top, and more and more details further down. Functions called from the top function come directly below it, and so on down to the lowest level and most detailed functions at the bottom. This is a good way to organize the source code, even though IDEs make the location of functions less important, since it is so easy to navigate in and out of them.
### High level example (commented)[](https://stenciljs.com/docs/style-guide#high-level-example-commented "Direct link to High level example (commented)")
@Component({ tag: 'ion-something', styleUrls: { ios: 'something.ios.css', md: 'something.md.css', wp: 'something.wp.css' }})export class Something { /** * 1. Own Properties * Always set the type if a default value has not * been set. If a default value is being set, then type * is already inferred. List the own properties in * alphabetical order. Note that because these properties * do not have the @Prop() decorator, they will not be exposed * publicly on the host element, but only used internally. */ num: number; someText = 'default'; /** * 2. Reference to host HTML element. * Inlined decorator */ @Element() el: HTMLElement; /** * 3. State() variables * Inlined decorator, alphabetical order. */ @State() isValidated: boolean; @State() status = 0; /** * 4. Public Property API * Inlined decorator, alphabetical order. These are * different than "own properties" in that public props * are exposed as properties and attributes on the host element. * Requires JSDocs for public API documentation. */ @Prop() content: string; @Prop() enabled: boolean; @Prop() menuId: string; @Prop() type = 'overlay'; /** * Prop lifecycle events SHOULD go just behind the Prop they listen to. * This makes sense since both statements are strongly connected. * - If renaming the instance variable name you must also update the name in @Watch() * - Code is easier to follow and maintain. */ @Prop() swipeEnabled = true; @Watch('swipeEnabled') swipeEnabledChanged(newSwipeEnabled: boolean, oldSwipeEnabled: boolean) { this.updateState(); } /** * 5. Events section * Inlined decorator, alphabetical order. * Requires JSDocs for public API documentation. */ @Event() ionClose: EventEmitter; @Event() ionDrag: EventEmitter; @Event() ionOpen: EventEmitter; /** * 6. Component lifecycle events * Ordered by their natural call order, for example * WillLoad should go before DidLoad. */ connectedCallback() {} disconnectedCallback() {} componentWillLoad() {} componentDidLoad() {} componentShouldUpdate(newVal: any, oldVal: any, propName: string) {} componentWillUpdate() {} componentDidUpdate() {} componentWillRender() {} componentDidRender() {} /** * 7. Listeners * It is ok to place them in a different location * if makes more sense in the context. Recommend * starting a listener method with "on". * Always use two lines. */ @Listen('click', { enabled: false }) onClick(ev: UIEvent) { console.log('hi!') } /** * 8. Public methods API * These methods are exposed on the host element. * Always use two lines. * Public Methods must be async. * Requires JSDocs for public API documentation. */ @Method() async open(): Promise { // ... return true; } @Method() async close(): Promise { // ... } /** * 9. Local methods * Internal business logic. These methods cannot be * called from the host element. */ prepareAnimation(): Promise { // ... } updateState() { // ... } /** * 10. render() function * Always the last public method in the class. * If private methods present, they are below public methods. */ render() { return ( ); }}
Contents
--------
* [File structure](https://stenciljs.com/docs/style-guide#file-structure)
* [Naming](https://stenciljs.com/docs/style-guide#naming)
* [HTML tag](https://stenciljs.com/docs/style-guide#html-tag)
* [Component (TS class)](https://stenciljs.com/docs/style-guide#component-ts-class)
* [TypeScript](https://stenciljs.com/docs/style-guide#typescript)
* [Code organization](https://stenciljs.com/docs/style-guide#code-organization)
* [High level example (commented)](https://stenciljs.com/docs/style-guide#high-level-example-commented)
* * *
[Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.35/guides/style-guide.md)
---
# Module Bundling | Stencil
[Skip to main content](https://stenciljs.com/docs/v4.33/module-bundling#__docusaurus_skipToContent_fallback)
[An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none)
This is documentation for Stencil **v4.33**, which is no longer actively maintained.
For up-to-date documentation, see the **[latest version](https://stenciljs.com/docs/module-bundling)
** (v4.35).
Version: v4.33
On this page
Stencil uses [Rollup](https://rollupjs.org/guide/en/)
under the hood to bundle your components. This guide will explain and recommend certain workarounds for some of the most common bundling issues you might encounter.
One Component Per Module[](https://stenciljs.com/docs/v4.33/module-bundling#one-component-per-module "Direct link to One Component Per Module")
-------------------------------------------------------------------------------------------------------------------------------------------------
For Stencil to bundle your components most efficiently, you must declare a single component (class decorated with `@Component`) per _TypeScript_ file, and the component itself **must** have a unique `export`. By doing so, Stencil is able to easily analyze the entire component graph within the app, and best understand how components should be bundled together. Under-the-hood it uses the Rollup bundler to efficiently bundled shared code together. Additionally, lazy-loading is a default feature of Stencil, so code-splitting is already happening automatically, and only dynamically importing components which are being used on the page.
Modules that contain a component are entry-points, which means that no other module should import anything from them.
The following example is **NOT** valid:
src/components/my-cmp.tsx
// This module has a component, you cannot export anything elseexport function someUtilFunction() { console.log('do stuff');}@Component({ tag: 'my-cmp'})export class MyCmp {}
In this case, the compiler will emit an error that looks like this:
[ ERROR ] src/components/my-cmp.tsx:4:1 To allow efficient bundling, modules using @Component() can only have a single export which is the component class itself. Any other exports should be moved to a separate file. For further information check out: https://stenciljs.com/docs/module-bundling L4: export function someUtilFunction() { L5: console.log('do stuff');
The solution is to move any shared functions or classes to a different `.ts` file, like this:
src/utils.ts
export function someUtilFunction() { console.log('do stuff');}
src/components/my-cmp.tsx
import { someUtilFunction } from '../utils.ts';@Component({ tag: 'my-cmp'})export class MyCmp {}
src/components/my-cmp-two.tsx
import { someUtilFunction } from '../utils.ts';@Component({ tag: 'my-cmp-two'})export class MyCmpTwo {}
CommonJS Dependencies[](https://stenciljs.com/docs/v4.33/module-bundling#commonjs-dependencies "Direct link to CommonJS Dependencies")
----------------------------------------------------------------------------------------------------------------------------------------
Rollup depends on [ES modules (ESM)](https://hacks.mozilla.org/2018/03/es-modules-a-cartoon-deep-dive/)
to properly tree-shake the module graph, unfortunately, some third-party libraries ship their code using the [CommonJS](https://requirejs.org/docs/commonjs.html)
module system, which is not ideal.
Since CommonJS libraries are still common today, Stencil comes with [`rollup-plugin-commonjs`](https://github.com/rollup/rollup-plugin-commonjs)
already installed and configured.
At compiler-time, the `rollup-plugin-commonjs` plugin does a best-effort to **transform CommonJS into ESM**, but this is not always an easy task. CommonJS is dynamic by nature, while ESM is static by design.
For further information, check out the [rollup-plugin-commonjs docs](https://github.com/rollup/plugins/tree/master/packages/commonjs)
.
Custom Rollup plugins[](https://stenciljs.com/docs/v4.33/module-bundling#custom-rollup-plugins "Direct link to Custom Rollup plugins")
----------------------------------------------------------------------------------------------------------------------------------------
Stencil provides an API to pass custom rollup plugins to the bundling process in `stencil.config.ts`. Under the hood, stencil ships with some built-in plugins including `node-resolve` and `commonjs`, since the execution order of some rollup plugins is important, stencil provides an API to inject custom plugin **before node-resolve** and after **commonjs transform**:
export const config = { rollupPlugins: { before: [ // Plugins injected before rollupNodeResolve() resolvePlugin() ], after: [ // Plugins injected after commonjs() nodePolyfills() ] }}
As a rule of thumb, plugins that need to resolve modules, should be place in `before`, while code transform plugins like: `node-polyfills`, `replace`... should be placed in `after`. Follow the plugin's documentation to make sure it's executed in the right order.
Node Polyfills[](https://stenciljs.com/docs/v4.33/module-bundling#node-polyfills "Direct link to Node Polyfills")
-------------------------------------------------------------------------------------------------------------------
Depending on which libraries a project is dependent on, the [rollup-plugin-node-polyfills](https://www.npmjs.com/package/rollup-plugin-node-polyfills)
plugin may be required. In such cases, an error message similar to the following will be displayed at build time.
[ ERROR ] Bundling Node Builtin For the import "crypto" to be bundled from 'problematic-dep', ensure the "rollup-plugin-node-polyfills" plugin is installed and added to the stencil config plugins.
This is caused by some third-party dependencies that use [Node APIs](https://nodejs.org/dist/latest-v10.x/docs/api/)
that are not available in the browser, the `rollup-plugin-node-polyfills` plugin works by transparently polyfilling this missing APIs in the browser.
### 1\. Install `rollup-plugin-node-polyfills`:[](https://stenciljs.com/docs/v4.33/module-bundling#1-install-rollup-plugin-node-polyfills "Direct link to 1-install-rollup-plugin-node-polyfills")
* npm
* Yarn
* pnpm
npm install rollup-plugin-node-polyfills --save-dev
yarn add rollup-plugin-node-polyfills --dev
pnpm add rollup-plugin-node-polyfills --save-dev
### 2\. Update the `stencil.config.ts` file including the plugin:[](https://stenciljs.com/docs/v4.33/module-bundling#2-update-the-stencilconfigts-file-including-the-plugin "Direct link to 2-update-the-stencilconfigts-file-including-the-plugin")
import { Config } from '@stencil/core';import nodePolyfills from 'rollup-plugin-node-polyfills';export const config: Config = { namespace: 'mycomponents', rollupPlugins: { after: [ nodePolyfills(), ] }};
note
`rollup-plugin-node-polyfills` is a code-transform plugin, so it needs to run AFTER the commonjs transform plugin, that's the reason it's placed in the "after" array of plugins.
Strict Mode[](https://stenciljs.com/docs/v4.33/module-bundling#strict-mode "Direct link to Strict Mode")
----------------------------------------------------------------------------------------------------------
ES modules are always parsed in strict mode. That means that certain non-strict constructs (like octal literals) will be treated as syntax errors when Rollup parses modules that use them. Some older CommonJS modules depend on those constructs, and if you depend on them your bundle will blow up. There's nothing we can do about that.
Luckily, there is absolutely no good reason not to use strict mode for everything — so the solution to this problem is to lobby the authors of those modules to update them.
_Source: [https://github.com/rollup/rollup-plugin-commonjs#strict-mode](https://github.com/rollup/rollup-plugin-commonjs#strict-mode)
_
Contents
--------
* [One Component Per Module](https://stenciljs.com/docs/v4.33/module-bundling#one-component-per-module)
* [CommonJS Dependencies](https://stenciljs.com/docs/v4.33/module-bundling#commonjs-dependencies)
* [Custom Rollup plugins](https://stenciljs.com/docs/v4.33/module-bundling#custom-rollup-plugins)
* [Node Polyfills](https://stenciljs.com/docs/v4.33/module-bundling#node-polyfills)
* [1\. Install `rollup-plugin-node-polyfills`:](https://stenciljs.com/docs/v4.33/module-bundling#1-install-rollup-plugin-node-polyfills)
* [2\. Update the `stencil.config.ts` file including the plugin:](https://stenciljs.com/docs/v4.33/module-bundling#2-update-the-stencilconfigts-file-including-the-plugin)
* [Strict Mode](https://stenciljs.com/docs/v4.33/module-bundling#strict-mode)
* * *
[Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.33/guides/module-bundling.md)
---
# Content Security Policy Nonces | Stencil
[Skip to main content](https://stenciljs.com/docs/v4.34/csp-nonce#__docusaurus_skipToContent_fallback)
[An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none)
This is documentation for Stencil **v4.34**, which is no longer actively maintained.
For up-to-date documentation, see the **[latest version](https://stenciljs.com/docs/csp-nonce)
** (v4.35).
Version: v4.34
On this page
[Content Security Policies (CSPs)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP)
can help protect an application from Cross-Site Scripting (XSS) attacks by adding a security layer to help prevent unauthorized code from running in the browser.
An application that is served with a CSP other than 'unsafe-inline' and contains web components without a Shadow DOM will likely run into errors on load. This is often first detected in the browser's console, which reports an error stating that certain styles or scripts violate the effective CSP.
To resolve this issue, Stencil supports using [CSP nonces](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/nonce)
in many of the output targets.
caution
NOTE: CSPs and some CSP strategies are not supported by certain browsers. For a more detailed list, please see the [CSP browser compatibility table](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP#browser_compatibility)
.
How to Use a Nonce[](https://stenciljs.com/docs/v4.34/csp-nonce#how-to-use-a-nonce "Direct link to How to Use a Nonce")
-------------------------------------------------------------------------------------------------------------------------
The actual generation of the nonce value and enforcement of the correct CSP are not the responsibility of Stencil. Instead, the server of the application will need to generate the nonce value for each page view, construct the CSP, and then correctly handle passing the generated nonce to Stencil based on which output target is being consumed.
There are many resources available that walk through setting up a CSP and using the nonce behavior. [This](https://towardsdatascience.com/content-security-policy-how-to-create-an-iron-clad-nonce-based-csp3-policy-with-webpack-and-nginx-ce5a4605db90)
article walks through the process using Nginx and Webpack. Obviously, these resources don't account for the Stencil specifics, but any specifics will be called out in this guide.
Per the [MDN Guide on nonces](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/nonce#generating_values)
, a nonce should be "a random base64-encoded string of at least 128 bits of data from a cryptographically secure random number generator".
### Output Targets[](https://stenciljs.com/docs/v4.34/csp-nonce#output-targets "Direct link to Output Targets")
Using nonces may differ slightly between output targets, so please be sure to use the correct pattern based on the context in which your Stencil components are consumed.
#### Dist[](https://stenciljs.com/docs/v4.34/csp-nonce#dist "Direct link to Dist")
Consuming a `nonce` in the `dist` output target is easy using the provided `setNonce` helper function. This function is exported from the index file of the output target's designated output directory.
This function simply accepts the `nonce` string value that you want set for every `style` and `script` tag.
This is an example of consuming the `dist` output in an Angular app's entrypoint:
// main.tsimport { defineCustomElements, setNonce } from 'my-lib/loader';// Will set the `nonce` attribute for all scripts/style tags// i.e. will run styleTag.setAttribute('nonce', 'r4nd0m')// Obviously, you should use the nonce generated by your serversetNonce('r4nd0m');// Generic Angular bootstrappingplatformBrowserDynamic() .bootstrapModule(AppModule) .catch(err => console.log(err));defineCustomElements();
#### Custom Elements[](https://stenciljs.com/docs/v4.34/csp-nonce#custom-elements "Direct link to Custom Elements")
Consuming a `nonce` in the `dist-custom-elements` output target is easy using the provided `setNonce` helper function. This function is exported from the index file of the output target's designated output directory.
This function simply accepts the `nonce` string value that you want set for every `style` and `script` tag.
This is an example of consuming the `dist-custom-elements` output in an Angular app's entrypoint:
// main.tsimport { defineCustomElements, setNonce } from 'my-lib/dist/components';// Assume `customElementsExportBehavior: 'auto-define-custom-elements'` is setimport 'my-lib/dist/components/my-component';// Will set the `nonce` attribute for all scripts/style tags// i.e. will run styleTag.setAttribute('nonce', 'r4nd0m')// Obviously, you should use the nonce generated by your serversetNonce('r4nd0m');// Generic Angular bootstrappingplatformBrowserDynamic() .bootstrapModule(AppModule) .catch(err => console.log(err));
#### WWW[](https://stenciljs.com/docs/v4.34/csp-nonce#www "Direct link to WWW")
Unfortunately, setting `nonce` attributes gets a bit trickier when it comes to [SSR and SSG](https://stenciljs.com/docs/v4.34/static-site-generation)
. As a `nonce` needs to be unique per page view, it cannot be defined/set at build time. So, this responsibility now falls on the [hydrate app](https://stenciljs.com/docs/v4.34/hydrate-app)
's execution of runtime code.
**SSR**
Since there is not an easy way (or any way) of exposing and executing helper functions to manipulate the outcome of the runtime code, Stencil has fallback behavior for pulling the `nonce` off of a `meta` tag in the DOM head.
So, for SSR, your app can simply inject a `meta` element into the header _on each page request_. Yes, this does involve some manual configuration for the code served by your server. To work correctly, the created tag must be generated as follows:
This isn't a security risk because, for an attacker to execute a script to pull the nonce from the meta tag, they would have needed to know the nonce _ahead_ of the script's execution.
**SSG**
Stencil cannot support CSP nonces with SSG. Because all of the code is generated during [pre-rendering](https://stenciljs.com/docs/v4.34/static-site-generation#how-static-site-generation-and-prerendering-works)
, Stencil doesn't generate the `style` or `script` tags at runtime. If an application wants to leverage nonces in SSG, they can build a mechanism to scrape the pre-rendered code and apply the attribute server-side before it is served to the client.
Contents
--------
* [How to Use a Nonce](https://stenciljs.com/docs/v4.34/csp-nonce#how-to-use-a-nonce)
* [Output Targets](https://stenciljs.com/docs/v4.34/csp-nonce#output-targets)
* * *
[Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.34/guides/csp-nonce.md)
---
# Stencil Frequently Asked Questions | Stencil
[Skip to main content](https://stenciljs.com/docs/v4.33/faq#__docusaurus_skipToContent_fallback)
[An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none)
This is documentation for Stencil **v4.33**, which is no longer actively maintained.
For up-to-date documentation, see the **[latest version](https://stenciljs.com/docs/faq)
** (v4.35).
Version: v4.33
On this page
Introduction[](https://stenciljs.com/docs/v4.33/faq#introduction "Direct link to Introduction")
-------------------------------------------------------------------------------------------------
### What is Stencil?[](https://stenciljs.com/docs/v4.33/faq#what-is-stencil "Direct link to What is Stencil?")
Stencil is a developer-focused toolchain for building reusable, scalable component libraries. It provides a compiler that generates highly optimized Web Components, and combines the best concepts of the most popular frameworks into a simple build-time tool.
Stencil focuses on building components with web standards. It’s used by developers and organizations around the world, and is [100% free and MIT open source](https://github.com/ionic-team/stencil/blob/main/LICENSE.md)
.
### What does Stencil do?[](https://stenciljs.com/docs/v4.33/faq#what-does-stencil-do "Direct link to What does Stencil do?")
Stencil helps developers and teams build and share custom components. Since Stencil generates standards-compliant Web Components, the components you build with Stencil will work with many popular frameworks right out of the box, and can even be used without a framework because they are just Web Components. Stencil also enables a number of key capabilities on top of Web Components, in particular, prerendering, and objects-as-properties (instead of just strings).
### Who is Stencil for?[](https://stenciljs.com/docs/v4.33/faq#who-is-stencil-for "Direct link to Who is Stencil for?")
Stencil is for developers and teams that want to build custom component libraries that can be shared across teams, frameworks and large organizations.
Stencil can also be used by designers who want their original design visions delivered consistently, with high fidelity, to all users.
### Who makes Stencil?[](https://stenciljs.com/docs/v4.33/faq#who-makes-stencil "Direct link to Who makes Stencil?")
Stencil is an open source project started by the [Ionic core team](https://ionicframework.com/)
, with contributions also coming from the community.
### Why was Stencil created?[](https://stenciljs.com/docs/v4.33/faq#why-was-stencil-created "Direct link to Why was Stencil created?")
Stencil was created by the Ionic Framework team to make our own component library faster, smaller, and compatible with all major frameworks. Web Components offered a solution by pushing more work to the browser for better performance, and targeting a standards-based component model that all frameworks could use.
### Who uses Stencil?[](https://stenciljs.com/docs/v4.33/faq#who-uses-stencil "Direct link to Who uses Stencil?")
Stencil was initially developed for Ionic Framework which is a very successful Web Component-based library & UI framework. Web Components are now in thousands of app store apps, and nearly 4 million new Ionic Framework projects are being created every year.
### How does Stencil compare to traditional frameworks?[](https://stenciljs.com/docs/v4.33/faq#how-does-stencil-compare-to-traditional-frameworks "Direct link to How does Stencil compare to traditional frameworks?")
The Web Component ecosystem has a diverse set of players, each with a different long-term vision for what Web Components can and should do.
Some think Web Components should replace third-party app frameworks, while others think that Web Components are more suited for leaf/style/design nodes and shouldn’t get in the business of your app’s component system. There are also many framework developers that don’t see the point of Web Components, or consider them to be an affront to front-end innovation.
With Stencil, our vision is somewhere in the middle. In the long term, we see app development teams continuing to use their framework of choice. We envision these frameworks continuing to get better, smaller, and more efficient, with increasingly good support for targeting and consuming Web Components -- and big teams will be consuming an increasing amount of Web Components as companies continue to embrace them for shared component libraries.
At the same time, we believe an indispensable feature for Web Components is solving those component distribution and design system problems. We also believe, however, that 90% of the market doesn’t have those problems to begin with, so the current debate about the merits of Web Components is somewhat unproductive.
### Why is Stencil considered framework-agnostic?[](https://stenciljs.com/docs/v4.33/faq#why-is-stencil-considered-framework-agnostic "Direct link to Why is Stencil considered framework-agnostic?")
Perhaps the most appealing benefit of Web Components is that they give your development teams the flexibility to choose the underlying tools and frameworks - and versions of those frameworks - and tools that they prefer. As pointed out earlier, one of the great challenges of implementing a universal set of components is getting all of your development teams to standardize on just one set of technologies. With Web Components, each team can use what works best for them, giving them complete freedom to use the tools they love—today and tomorrow.
What does Stencil provide?[](https://stenciljs.com/docs/v4.33/faq#what-does-stencil-provide "Direct link to What does Stencil provide?")
------------------------------------------------------------------------------------------------------------------------------------------
### Does Stencil have a component library?[](https://stenciljs.com/docs/v4.33/faq#does-stencil-have-a-component-library "Direct link to Does Stencil have a component library?")
The most widely used Stencil component library is the Ionic Framework, however, Stencil itself is only a toolchain and does not provide its own component library. We encourage you to first review Ionic components if you are building an application.
### Is Stencil a framework?[](https://stenciljs.com/docs/v4.33/faq#is-stencil-a-framework "Direct link to Is Stencil a framework?")
Stencil purposely does not strive to act as a stand-alone framework, but rather a tool which allows developers to scale framework-agnostic components across many projects, teams and large organizations. One of Stencil’s superpowers is its flexibility: its components could be used stand-alone, or within traditional frameworks.
### Does Stencil come with a testing framework?[](https://stenciljs.com/docs/v4.33/faq#does-stencil-come-with-a-testing-framework "Direct link to Does Stencil come with a testing framework?")
Yes, Stencil provides a rich set of APIs for unit and End-to-end tests. [Learn more about testing with Stencil](https://stenciljs.com/docs/v4.33/testing-overview)
.
Technology[](https://stenciljs.com/docs/v4.33/faq#technology "Direct link to Technology")
-------------------------------------------------------------------------------------------
### Why does Stencil use web components?[](https://stenciljs.com/docs/v4.33/faq#why-does-stencil-use-web-components "Direct link to Why does Stencil use web components?")
By using a consistent set of web standards, Web Components do not depend on a specific framework runtime to execute. As frameworks change their APIs, Web Components do not, allowing for the original source to continue to work natively in a browser.
### How is Stencil able to optimize component file size and startup?[](https://stenciljs.com/docs/v4.33/faq#how-is-stencil-able-to-optimize-component-file-size-and-startup "Direct link to How is Stencil able to optimize component file size and startup?")
Traditional frameworks provide a runtime API, and developers can pick and choose which APIs to use per component. However, this means every feature needs to be available to every component, just in case the component may or may not use the API.
With Stencil, the compiler is able to perform static analysis on each component in order to understand which APIs are and are not being used. By doing so, Stencil is able to customize each build to use exactly what each component needs, making for a highly optimized runtime with minimal size.
Since Stencil uses a compiler, it is able to adjust code as new improvements and features become available. Source code can continue to be written using the same public API and syntax, while the compiler can adjust the code to further take advantage of modern features, without requiring re-writes.
### What template syntax does Stencil use?[](https://stenciljs.com/docs/v4.33/faq#what-template-syntax-does-stencil-use "Direct link to What template syntax does Stencil use?")
Stencil uses [JSX](https://react.dev/learn/writing-markup-with-jsx)
, a markup language popularized by the React library.
### Can Stencil components be lazy loaded?[](https://stenciljs.com/docs/v4.33/faq#can-stencil-components-be-lazy-loaded "Direct link to Can Stencil components be lazy loaded?")
Yes! Lazy loading components helps to reduce application startup times, decrease bundle sizes, and improve distribution.
Because users are able to dynamically load only what is used, startup times are drastically reduced and users only load exactly what their application’s first paint requires.
At the same time, components built with Stencil can still be imported and consumed by traditional bundlers.
### Why are Stencil components written with TypeScript?[](https://stenciljs.com/docs/v4.33/faq#why-are-stencil-components-written-with-typescript "Direct link to Why are Stencil components written with TypeScript?")
Stencil was originally built for Ionic, and in our experience we’ve found TypeScript to be a valuable tool for maintaining a large codebase across multiple teams.
### What dependencies does the Stencil runtime have?[](https://stenciljs.com/docs/v4.33/faq#what-dependencies-does-the-stencil-runtime-have "Direct link to What dependencies does the Stencil runtime have?")
None. The code generated by Stencil does not rely on Stencil, but rather it generates highly-optimized, framework-free, stand-alone code which runs natively in the browser.
### Can data be passed to Web Components?[](https://stenciljs.com/docs/v4.33/faq#can-data-be-passed-to-web-components "Direct link to Can data be passed to Web Components?")
Just like any other DOM element in a webpage, any data in the form of arrays, objects, strings and numbers can be passed to element properties. Stencil is designed from the ground up to ensure this capability stays unlocked for application developers.
### What technology is Stencil built with?[](https://stenciljs.com/docs/v4.33/faq#what-technology-is-stencil-built-with "Direct link to What technology is Stencil built with?")
The Stencil compiler is built with TypeScript and is [distributed on npm](https://www.npmjs.com/package/@stencil/core)
. Its distribution includes types, making it easier for developers to use Stencil APIs.
Capabilities[](https://stenciljs.com/docs/v4.33/faq#capabilities "Direct link to Capabilities")
-------------------------------------------------------------------------------------------------
### Where can Stencil components be used?[](https://stenciljs.com/docs/v4.33/faq#where-can-stencil-components-be-used "Direct link to Where can Stencil components be used?")
One great advantage of using Web Components is that your component library will work across all projects, not just desktop web apps.
For example, using a hybrid mobile framework like Ionic, you can deploy Web Components across just about any platform or device, from native iOS and Android apps, to Electron and desktop web apps, and even Progressive Web Apps.
### What are the limitations of Web Components?[](https://stenciljs.com/docs/v4.33/faq#what-are-the-limitations-of-web-components "Direct link to What are the limitations of Web Components?")
The [Web Component](https://developer.mozilla.org/en-US/docs/Web/Web_Components)
specs are purposely low-level, and on their own, they do not provide a framework quality developer experience. Web Components run on a fairly primitive set of standards, so you will need a little help to get them to meet your objectives.
Some limitations include:
When you try to use pure vanilla Web Components in an application, functionality like server-side rendering and progressive enhancement is not supported by default, and some out-of-date clients don’t support the Web Components standard.
In addition, while Web Components technically work with any framework, there are some limitations like lack of type support and input bindings, and challenges passing properties to components, as noted above.
The good news is that, with help from open source tools like Stencil, you can overcome all of these challenges. Stencil includes framework bindings for Angular, React, and Vue, so you can easily import Web Component libraries into any framework, and interact with them just like they were native to that framework, with all the functionality you’re used to.
### What are framework bindings?[](https://stenciljs.com/docs/v4.33/faq#what-are-framework-bindings "Direct link to What are framework bindings?")
While Web Components can be paired with any JavaScript framework, Stencil has built-in special-purpose bindings to deliver the more advanced features enterprise teams expect when building applications in Angular, React, and Vue.
### What features does Stencil add to Web Components?[](https://stenciljs.com/docs/v4.33/faq#what-features-does-stencil-add-to-web-components "Direct link to What features does Stencil add to Web Components?")
Web Components by themselves weren't enough to provide a quality development experience. Building fast web apps required innovations that were previously locked up inside traditional web frameworks. Stencil was built to pull these features out of traditional frameworks and bring them to the fast emerging Web Component standard.
Compared to using Web Components directly, Stencil provides extra APIs that make writing fast components simpler. APIs like Virtual DOM, JSX, and async rendering make fast, powerful components easy to create, while still maintaining 100% compatibility with Web Components.
### What browsers can support Stencil components?[](https://stenciljs.com/docs/v4.33/faq#what-browsers-can-support-stencil-components "Direct link to What browsers can support Stencil components?")
Stencil works on modern browsers.
[Learn more about browser support](https://stenciljs.com/docs/v4.33/support-policy#browser-support)
.
Stencil Project[](https://stenciljs.com/docs/v4.33/faq#stencil-project "Direct link to Stencil Project")
----------------------------------------------------------------------------------------------------------
### How do I get involved?[](https://stenciljs.com/docs/v4.33/faq#how-do-i-get-involved "Direct link to How do I get involved?")
Stencil is an open source project, and we encourage you to contribute. You can start by creating issues on GitHub, submitting feature requests, and helping to replicate bugs. If you’re interested in contributing, please see our [Contributor Guide](https://github.com/ionic-team/stencil/blob/main/.github/CONTRIBUTING.md)
and check out our [issue tracker](https://github.com/ionic-team/stencil/issues)
.
### Is Stencil open source?[](https://stenciljs.com/docs/v4.33/faq#is-stencil-open-source "Direct link to Is Stencil open source?")
Yes, Stencil is open source and its source code can be [found on GitHub](https://github.com/ionic-team/stencil)
. Contributions are welcomed from the community.
### Which software license does Stencil use?[](https://stenciljs.com/docs/v4.33/faq#which-software-license-does-stencil-use "Direct link to Which software license does Stencil use?")
Stencil’s software [license is MIT](https://github.com/ionic-team/stencil/blob/main/LICENSE.md)
.
### Who works on Stencil?[](https://stenciljs.com/docs/v4.33/faq#who-works-on-stencil "Direct link to Who works on Stencil?")
The majority of the development is done by engineers at [Ionic](https://github.com/ionic-team/ionic)
. If you’re excited about Stencil, we encourage you to join the community and contribute! Best place to start is on the [discord channel](https://chat.stenciljs.com/)
.
Contents
--------
* [Introduction](https://stenciljs.com/docs/v4.33/faq#introduction)
* [What is Stencil?](https://stenciljs.com/docs/v4.33/faq#what-is-stencil)
* [What does Stencil do?](https://stenciljs.com/docs/v4.33/faq#what-does-stencil-do)
* [Who is Stencil for?](https://stenciljs.com/docs/v4.33/faq#who-is-stencil-for)
* [Who makes Stencil?](https://stenciljs.com/docs/v4.33/faq#who-makes-stencil)
* [Why was Stencil created?](https://stenciljs.com/docs/v4.33/faq#why-was-stencil-created)
* [Who uses Stencil?](https://stenciljs.com/docs/v4.33/faq#who-uses-stencil)
* [How does Stencil compare to traditional frameworks?](https://stenciljs.com/docs/v4.33/faq#how-does-stencil-compare-to-traditional-frameworks)
* [Why is Stencil considered framework-agnostic?](https://stenciljs.com/docs/v4.33/faq#why-is-stencil-considered-framework-agnostic)
* [What does Stencil provide?](https://stenciljs.com/docs/v4.33/faq#what-does-stencil-provide)
* [Does Stencil have a component library?](https://stenciljs.com/docs/v4.33/faq#does-stencil-have-a-component-library)
* [Is Stencil a framework?](https://stenciljs.com/docs/v4.33/faq#is-stencil-a-framework)
* [Does Stencil come with a testing framework?](https://stenciljs.com/docs/v4.33/faq#does-stencil-come-with-a-testing-framework)
* [Technology](https://stenciljs.com/docs/v4.33/faq#technology)
* [Why does Stencil use web components?](https://stenciljs.com/docs/v4.33/faq#why-does-stencil-use-web-components)
* [How is Stencil able to optimize component file size and startup?](https://stenciljs.com/docs/v4.33/faq#how-is-stencil-able-to-optimize-component-file-size-and-startup)
* [What template syntax does Stencil use?](https://stenciljs.com/docs/v4.33/faq#what-template-syntax-does-stencil-use)
* [Can Stencil components be lazy loaded?](https://stenciljs.com/docs/v4.33/faq#can-stencil-components-be-lazy-loaded)
* [Why are Stencil components written with TypeScript?](https://stenciljs.com/docs/v4.33/faq#why-are-stencil-components-written-with-typescript)
* [What dependencies does the Stencil runtime have?](https://stenciljs.com/docs/v4.33/faq#what-dependencies-does-the-stencil-runtime-have)
* [Can data be passed to Web Components?](https://stenciljs.com/docs/v4.33/faq#can-data-be-passed-to-web-components)
* [What technology is Stencil built with?](https://stenciljs.com/docs/v4.33/faq#what-technology-is-stencil-built-with)
* [Capabilities](https://stenciljs.com/docs/v4.33/faq#capabilities)
* [Where can Stencil components be used?](https://stenciljs.com/docs/v4.33/faq#where-can-stencil-components-be-used)
* [What are the limitations of Web Components?](https://stenciljs.com/docs/v4.33/faq#what-are-the-limitations-of-web-components)
* [What are framework bindings?](https://stenciljs.com/docs/v4.33/faq#what-are-framework-bindings)
* [What features does Stencil add to Web Components?](https://stenciljs.com/docs/v4.33/faq#what-features-does-stencil-add-to-web-components)
* [What browsers can support Stencil components?](https://stenciljs.com/docs/v4.33/faq#what-browsers-can-support-stencil-components)
* [Stencil Project](https://stenciljs.com/docs/v4.33/faq#stencil-project)
* [How do I get involved?](https://stenciljs.com/docs/v4.33/faq#how-do-i-get-involved)
* [Is Stencil open source?](https://stenciljs.com/docs/v4.33/faq#is-stencil-open-source)
* [Which software license does Stencil use?](https://stenciljs.com/docs/v4.33/faq#which-software-license-does-stencil-use)
* [Who works on Stencil?](https://stenciljs.com/docs/v4.33/faq#who-works-on-stencil)
* * *
[Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.33/reference/faq.md)
---
# Publishing A Component Library | Stencil
[Skip to main content](https://stenciljs.com/docs/v4.33/publishing#__docusaurus_skipToContent_fallback)
[An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none)
This is documentation for Stencil **v4.33**, which is no longer actively maintained.
For up-to-date documentation, see the **[latest version](https://stenciljs.com/docs/publishing)
** (v4.35).
Version: v4.33
On this page
There are numerous strategies to publish and distribute your component library to be consumed by external projects. One of the benefits of Stencil is that is makes it easy to generate the various [output targets](https://stenciljs.com/docs/v4.33/output-targets)
that are right for your use-case.
Use Cases[](https://stenciljs.com/docs/v4.33/publishing#use-cases "Direct link to Use Cases")
-----------------------------------------------------------------------------------------------
To use your Stencil components in other projects, there are two different output targets to consider: [`dist`](https://stenciljs.com/docs/v4.33/distribution)
and [`dist-custom-elements`](https://stenciljs.com/docs/v4.33/custom-elements)
. Both export your components for different use cases. Luckily, both can be generated at the same time, using the same source code, and shipped in the same distribution. It would be up to the consumer of your component library to decide which build to use.
### Lazy Loading[](https://stenciljs.com/docs/v4.33/publishing#lazy-loading "Direct link to Lazy Loading")
If you prefer to have your components automatically loaded when used in your application, we recommend enabling the [`dist`](https://stenciljs.com/docs/v4.33/distribution)
output target. The bundle gives you a small entry file that registers all your components and defers loading the full component logic until it is rendered in your application. It doesn't matter if the actual application is written in HTML or created with vanilla JavaScript, jQuery, React, etc.
Your users can import your component library, e.g. called `my-design-system`, either via a `script` tag:
or by importing it in the bootstrap script of your application:
import 'my-design-system';
To ensure that the right entry file is loaded when importing the project, define the following fields in your `package.json`:
{ "exports": "./dist/esm/my-design-system.js", "main": "./dist/cjs/my-design-system.js", "unpkg": "dist/my-design-system/my-design-system.esm.js",}
Read more about various options when it comes to configuring your project's components for lazy loading in the [`dist`](https://stenciljs.com/docs/v4.33/distribution)
output target section.
#### Considerations[](https://stenciljs.com/docs/v4.33/publishing#considerations "Direct link to Considerations")
To start, Stencil was designed to lazy-load itself only when the component was actually used on a page. There are many benefits to this approach, such as simply adding a script tag to any page and the entire library is available for use, yet only the components actually used are downloaded. For example, [`@ionic/core`](https://www.npmjs.com/package/@ionic/core)
comes with over 100 components, but a webpage may only need `ion-toggle`. Instead of requesting the entire component library, or generating a custom bundle for just `ion-toggle`, the `dist` output target is able to generate a tiny entry build ready to load any of its components on-demand.
However be aware that this approach is not ideal in all cases. It requires your application to ship the bundled components as static assets in order for them to load properly. Furthermore, having many nested component dependencies can have an impact on the performance of your application. For example, given you have a component `CmpA` which uses a Stencil component `CmpB` which itself uses another Stencil component `CmpC`. In order to fully render `CmpA` the browser has to load 3 scripts sequentially which can result in undesired rendering delays.
### Standalone[](https://stenciljs.com/docs/v4.33/publishing#standalone "Direct link to Standalone")
The [`dist-custom-elements`](https://stenciljs.com/docs/v4.33/custom-elements)
output target builds each component as a stand-alone class that extends `HTMLElement`. The output is a standardized custom element with the styles already attached and without any of Stencil's lazy-loading. This may be preferred for projects that are already handling bundling, lazy-loading and defining the custom elements themselves.
The generated files will each export a component class and will already have the styles bundled. However, this build does not define the custom elements or apply any polyfills. Static assets referenced within components will need to be set using `setAssetPath` (see [Making Assets Available](https://stenciljs.com/docs/v4.33/custom-elements#making-assets-available)
).
You can use these standalone components by importing them via:
import { MyComponent, defineCustomElementMyComponent } from 'my-design-system'// register to CustomElementRegistrydefineCustomElementMyComponent()// or extend custom element viaclass MyCustomComponent extends MyComponent { // ...}define('my-custom-component', MyCustomComponent)
To ensure that the right entry file is loaded when importing the project, define different [exports fields](https://nodejs.org/api/packages.html#exports)
in your `package.json`:
{ "exports": { ".": { "import": "./dist/components/index.js", "types": "./dist/components/index.d.ts" }, "./my-component": { "import": "./dist/components/my-component.js", "types": "./dist/components/my-component.d.ts" } }, "types": "dist/components/index.d.ts",}
This allows us to map certain import paths to specific components within our project and allows users to only import the component code they are interested in and reduce the amount of code that needs to downloaded by the browser, e.g.:
// this import loads all compiled componentsimport { MyComponent } from 'my-design-system'// only import compiled code for MyComponentimport { MyComponent } from 'my-design-system/my-component'
If you define exports targets for all your components as shown above and by using [`customElementsExportBehavior: 'auto-define-custom-elements'`](https://stenciljs.com/docs/v4.33/custom-elements#customelementsexportbehavior)
as output target option, you can skip the `defineCustomElement` call and directly import the component where you need it:
import 'my-design-system/my-component'
note
If you are distributing both the `dist` and `dist-custom-elements`, then it's best to pick one of them as the main entry depending on which use case is more prominent.
Read more about various options when it comes to distributing your components as standalone components in the [`dist-custom-elements`](https://stenciljs.com/docs/v4.33/custom-elements)
output target section.
The output directory will also contain an `index.js` file which exports some helper methods by default. The contents of the file will look something like:
export { setAssetPath, setPlatformOptions } from '@stencil/core/internal/client';
note
The contents may look different if [`customElementsExportBehavior`](https://stenciljs.com/docs/v4.33/custom-elements#customelementsexportbehavior)
is specified!
#### Considerations[](https://stenciljs.com/docs/v4.33/publishing#considerations-1 "Direct link to Considerations")
The `dist-custom-elements` is a direct build of the custom element that extends `HTMLElement`, without any lazy-loading. This distribution strategy may be preferred for projects that use an external bundler such as [Vite](https://vitejs.dev/)
, [WebPack](https://webpack.js.org/)
or [Rollup](https://rollupjs.org/)
to compile the application. They ensure that only the components used within your application are bundled into compilation.
#### Usage in TypeScript[](https://stenciljs.com/docs/v4.33/publishing#usage-in-typescript "Direct link to Usage in TypeScript")
If you plan to support consuming your component library in TypeScript you'll need to set `generateTypeDeclarations: true` on the output target in your `stencil.config.ts`, like so:
stencil.config.ts
import { Config } from '@stencil/core';export const config: Config = { outputTargets: [ { type: 'dist-custom-elements', generateTypeDeclarations: true, }, // ... ], // ...};
Then you can set the `types` property in `package.json` so that consumers of your package can find the type definitions, like so:
package.json
{ "types": "dist/components/index.d.ts", "dependencies": { "@stencil/core": "latest" }, ...}
note
If you set the `dir` property on the output target config, replace `dist/components` in the above snippet with the path set in the config.
Publishing to NPM[](https://stenciljs.com/docs/v4.33/publishing#publishing-to-npm "Direct link to Publishing to NPM")
-----------------------------------------------------------------------------------------------------------------------
[NPM](https://www.npmjs.com/)
is an online software registry for sharing libraries, tools, utilities, packages, etc. To make your Stencil project widely available to be consumed, it's recommended to [publish the component library to NPM](https://docs.npmjs.com/getting-started/publishing-npm-packages)
. Once the library is published to NPM, other projects are able to add your component library as a dependency and use the components within their own projects.
Contents
--------
* [Use Cases](https://stenciljs.com/docs/v4.33/publishing#use-cases)
* [Lazy Loading](https://stenciljs.com/docs/v4.33/publishing#lazy-loading)
* [Standalone](https://stenciljs.com/docs/v4.33/publishing#standalone)
* [Publishing to NPM](https://stenciljs.com/docs/v4.33/publishing#publishing-to-npm)
* * *
[Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.33/guides/publishing.md)
---
# Debugging With VS Code | Stencil
[Skip to main content](https://stenciljs.com/docs/v4.33/vs-code-debugging#__docusaurus_skipToContent_fallback)
[An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none)
This is documentation for Stencil **v4.33**, which is no longer actively maintained.
For up-to-date documentation, see the **[latest version](https://stenciljs.com/docs/vs-code-debugging)
** (v4.35).
Version: v4.33
On this page
VS Code offers a streamlined debugging experience that can be started with a single click when using [launch configurations](https://code.visualstudio.com/docs/editor/debugging#_launch-configurations)
.
If you're unfamiliar with using the VS Code debugger in general, please visit the [VS Code debugger documentation](https://code.visualstudio.com/docs/editor/debugging)
for a primer.
Requirements for Debugging[](https://stenciljs.com/docs/v4.33/vs-code-debugging#requirements-for-debugging "Direct link to Requirements for Debugging")
---------------------------------------------------------------------------------------------------------------------------------------------------------
In order for a debugger to function, the Stencil project must be configured to generate source maps for the compiled web components back to the source code. As of Stencil v3, source maps are generated by default, but be sure to double-check the project's Stencil config does not disable this behavior. More information regarding source maps in Stencil can be found in the [project configuration documentation](https://stenciljs.com/docs/v4.33/config#sourcemap)
.
Debugging Stencil Components In a Web App[](https://stenciljs.com/docs/v4.33/vs-code-debugging#debugging-stencil-components-in-a-web-app "Direct link to Debugging Stencil Components In a Web App")
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
It's a common use case to want to step through a web component's code as it executes in the browser and VS Code makes that process simple. Combining the debugger with Stencil's dev server in watch mode will allow you to debug changes as they're made.
### Configuring the VS Code Debugger[](https://stenciljs.com/docs/v4.33/vs-code-debugging#configuring-the-vs-code-debugger "Direct link to Configuring the VS Code Debugger")
To debug Stencil components as they run in a browser (web app), create (or edit) the `.vscode/launch.json` file with the following configuration:
.vscode/launch.json
{ ..., "configurations": [ ..., { "type": "chrome", "request": "launch", "name": "Launch Chrome against localhost", "url": "http://localhost:3333", "sourceMaps": true, "sourceMapPathOverrides": { "*": "${webRoot}/*" } } ]}
note
If your Stencil project is within a monorepo structure, you may want (or need) to add the `webRoot` option to the above config to point to the Stencil project's directory. For instance, if you have your Stencil project at `/packages/stencil-library`, you would add the following to the config:
{ ..., "webRoot": "${workspaceFolder}/packages/stencil-library",}
This will create a configuration to open a Chrome debugger instance on port 3333 (the default port used by the Stencil dev server). To use this configuration, start a Stencil dev server (running `npm start` in a [Stencil component starter project](https://stenciljs.com/docs/getting-started)
) and then run the configuration from the VS Code debugger tab. At this point, any breakpoints set in the component source code will pause browser execution when hit.
note
If your Stencil project is [configured to use a different port](https://stenciljs.com/docs/dev-server#dev-server-config)
for the dev server, you will need to update the `url` property in the debugger configuration with the correct port.
Debugging Static Site Generation (SSG)[](https://stenciljs.com/docs/v4.33/vs-code-debugging#debugging-static-site-generation-ssg "Direct link to Debugging Static Site Generation (SSG)")
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Static Site Generation, also known as prerendering, executes your components at build time to generate a snapshot of the rendered styles and markup to be efficiently served to search engines and users on first request.
Since this step runs in a Node.js process instead of a browser, debugging can't be done directly in the browser. However, debugging is straightforward using existing Node.js debugging techniques.
### Overview[](https://stenciljs.com/docs/v4.33/vs-code-debugging#overview "Direct link to Overview")
The `stencil build --prerender` command will first build the hydrate script for a NodeJS environment, then prerender the site using the build. For a production build this is probably ideal.
However, while debugging you may not need to keep rebuilding the hydrate script, but you only need to debug through the prerendering process. Stencil creates a file in `dist/hydrate` that is used to actually execute your components.
To only prerender (and avoid rebuilding), you can use the `stencil prerender dist/hydrate/index.js` command, with the path to the script as a flag.
### Tips for Debugging Prerendering[](https://stenciljs.com/docs/v4.33/vs-code-debugging#tips-for-debugging-prerendering "Direct link to Tips for Debugging Prerendering")
By default, prerendering will start by rendering the homepage, find links within the homepage, and continue to crawl the entire site as it finds more links. While debugging, it might be easier to _not_ crawl every URL in the site, but rather have it only prerender one page. To disable crawling, set the prerender config `crawlUrls: false`.
Next, you can use the `entryUrls` config to provide an array of paths to prerender, rather than starting at the homepage.
Additionally, console logs that are printed within the runtime are suppressed while prerendering (otherwise the terminal would be overloaded with logs). By setting `runtimeLogging: true`, the runtime console logs will be printed in the terminal. Below is an example setup for prerender debugging:
prerender.config.ts
import { PrerenderConfig } from '@stencil/core';export const config: PrerenderConfig = { crawlUrls: false, entryUrls: ['/example'], hydrateOptions: (_url) => { return { runtimeLogging: true, }; },};
### Configuring the VS Code Debugger[](https://stenciljs.com/docs/v4.33/vs-code-debugging#configuring-the-vs-code-debugger-1 "Direct link to Configuring the VS Code Debugger")
To debug the Stencil prerender process, create (or edit) the `launch.json` file with the following configuration:
launch.json
{ ..., "configurations": [ ..., { "type": "node", "request": "launch", "name": "Prerender", "args": [ "${workspaceFolder}/node_modules/@stencil/core/bin/stencil", "prerender", "${workspaceFolder}/dist/hydrate/index.js", "--max-workers=0", "--config=${workspaceFolder}/stencil.config.ts" ], "protocol": "inspector" } ]}
This creates a new debugging configuration using the script that hydrates the app. We're starting up the `stencil prerender` command, and providing it a path to where the hydrate script can be found. Next we're using `--max-workers=0` so we do not fork numerous processes to each of your CPUs which will make it difficult to debug.
Contents
--------
* [Requirements for Debugging](https://stenciljs.com/docs/v4.33/vs-code-debugging#requirements-for-debugging)
* [Debugging Stencil Components In a Web App](https://stenciljs.com/docs/v4.33/vs-code-debugging#debugging-stencil-components-in-a-web-app)
* [Configuring the VS Code Debugger](https://stenciljs.com/docs/v4.33/vs-code-debugging#configuring-the-vs-code-debugger)
* [Debugging Static Site Generation (SSG)](https://stenciljs.com/docs/v4.33/vs-code-debugging#debugging-static-site-generation-ssg)
* [Overview](https://stenciljs.com/docs/v4.33/vs-code-debugging#overview)
* [Tips for Debugging Prerendering](https://stenciljs.com/docs/v4.33/vs-code-debugging#tips-for-debugging-prerendering)
* [Configuring the VS Code Debugger](https://stenciljs.com/docs/v4.33/vs-code-debugging#configuring-the-vs-code-debugger-1)
* * *
[Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.33/guides/vs-code-debugging.md)
---
# Service Workers | Stencil
[Skip to main content](https://stenciljs.com/docs/v4.33/service-workers#__docusaurus_skipToContent_fallback)
[An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none)
This is documentation for Stencil **v4.33**, which is no longer actively maintained.
For up-to-date documentation, see the **[latest version](https://stenciljs.com/docs/service-workers)
** (v4.35).
Version: v4.33
On this page
[Service workers](https://developers.google.com/web/fundamentals/getting-started/primers/service-workers)
are a very powerful api that is essential for [PWAs](https://blog.ionic.io/what-is-a-progressive-web-app/)
, but can be hard to use. To help with this, we decided to build support for Service Workers into Stencil itself using [Workbox](https://workboxjs.org/)
.
What is Workbox?[](https://stenciljs.com/docs/v4.33/service-workers#what-is-workbox "Direct link to What is Workbox?")
------------------------------------------------------------------------------------------------------------------------
Workbox is a library that greatly simplifies the Service Worker API. It allows you to quickly generate a service worker that can handle caching static assets, cache remote assets using routes (similar to Express) or even do offline Google Analytics. Because we are built on top of Workbox, you can easily use any of the functionality they offer. For more info on Workbox, [check out their docs](https://developers.google.com/web/tools/workbox/)
Usage[](https://stenciljs.com/docs/v4.33/service-workers#usage "Direct link to Usage")
----------------------------------------------------------------------------------------
When doing a production build of an app built using Stencil, the Stencil compiler will automatically generate a service worker for you and inject the necessary code to register the service worker in your index.html. Also, because the files Stencil generates are hashed, every time you do a production build and push an update to your app, the service worker will know to update, therefore ensuring your users are never stuck on a stale version of your site.
Lets run through the steps needed to enable service workers for your project:
* `cd` into your project
* Run `npm run build`
And that's it! You should now have an `sw.js` file in your `www` folder and the code to register the service worker in your `www/index.html` file.
note
The component starter by default does not have service workers enabled as a service worker is not needed for component collections
Config[](https://stenciljs.com/docs/v4.33/service-workers#config "Direct link to Config")
-------------------------------------------------------------------------------------------
Stencil uses Workbox underneath, and by default generates a service worker from a config object using the `generateSW` mode. Therefore it supports all of the [Workbox generateSW config options](https://developers.google.com/web/tools/workbox/modules/workbox-build#full_generatesw_config)
. Here is the default config Stencil uses:
{ globPatterns: [ '**/*.{js,css,json,html}' ]};
This configuration does pre-caching of all of your app's assets.
To modify this config you can use the `serviceWorker` param of your Stencil config. Here is an example:
import { Config } from '@stencil/core';export const config: Config = { outputTargets: [ { type: 'www', serviceWorker: { globPatterns: [ '**/*.{js,css,json,html,ico,png}' ] } } ]};
### Disabling the service worker[](https://stenciljs.com/docs/v4.33/service-workers#disabling-the-service-worker "Direct link to Disabling the service worker")
If you do not want a service worker to be generated during the build, this can be turned off. To disable this feature, set the `serviceWorker` property to `null` in the `www` output target.
import { Config } from '@stencil/core';export const config: Config = { outputTargets: [ { type: 'www', serviceWorker: null } ]};
Using a custom service worker[](https://stenciljs.com/docs/v4.33/service-workers#using-a-custom-service-worker "Direct link to Using a custom service worker")
----------------------------------------------------------------------------------------------------------------------------------------------------------------
Already have a service worker or want to include some custom code? We support that, too. By specifying a source file for your service worker, Stencil switches to the `injectManifest` mode of Workbox. That gives you full control over your service worker, while still allowing you to automatically inject a precache manifest.
Let's go through the steps needed for this functionality:
* First we need to pass the path to our custom service worker to the `swSrc` command in the `serviceWorker` config. Here is an example:
import { Config } from '@stencil/core';export const config: Config = { outputTargets: [ { type: 'www', serviceWorker: { swSrc: 'src/sw.js' } } ]};
* Now we need to include some boilerplate code in our custom service worker:
// change to the version you get from `npm ls workbox-build`importScripts('workbox-v4.3.1/workbox-sw.js');// your custom service worker code// the precache manifest will be injected into the following lineself.workbox.precaching.precacheAndRoute([]);
This code imports the Workbox library, creates a new instance of the service worker and tells Workbox where to insert the pre-cache array.
### Showing a reload toast when an update is available[](https://stenciljs.com/docs/v4.33/service-workers#showing-a-reload-toast-when-an-update-is-available "Direct link to Showing a reload toast when an update is available")
When a new service worker is available, by default, it will be downloaded and then go into a state of waiting to be activated. The new service worker won't take over until all tabs of the site are closed and the site is visited again. This is to avoid unexpected behavior from conflicts with files being served from cache, and works well in many cases.
If you want to give your users the option to immediately access the new update, a common way is to show them a toast that lets them know about the update and offers a "reload" button. The reload let's the new service worker take over, serving the fresh content, and triggers a page reload, to avoid cache issues.
The following example showcases this in combination with the Ionic framework, but the toast-related code should be easily adaptable to any UI. Add the following to your root component (commonly `app-root.tsx`).
@Listen("swUpdate", { target: 'window' })async onServiceWorkerUpdate() { const registration = await navigator.serviceWorker.getRegistration(); if (!registration?.waiting) { // If there is no waiting registration, this is the first service // worker being installed. return; } const toast = await toastController.create({ message: "New version available.", buttons: [{ text: 'Reload', role: 'reload' }], duration: 0 }); await toast.present(); const { role } = await toast.onWillDismiss(); if (role === 'reload') { registration.waiting.postMessage("skipWaiting"); }}
The `swUpdate` event is emitted by Stencil every time a new service worker is installed. When a service worker is waiting for registration, the toast is shown. After clicking the reload button, a message is posted to the waiting service worker, letting it know to take over. This message needs to be handled by the service worker; therefore we need to create a custom one (e. g. `src/sw.js`) and add a listener to call `skipWaiting()`.
importScripts("workbox-v4.3.1/workbox-sw.js");self.addEventListener("message", ({ data }) => { if (data === "skipWaiting") { self.skipWaiting(); }});self.workbox.precaching.precacheAndRoute([]);
note
Don't forget to set `swSrc` in your Stencil config.
Finally, we want our app to reload when the new service worker has taken over, so that no outdated code is served from the cache anymore. We can use the service worker's `controllerchange` event for that, by attaching an event listener in our root component's `componentWillLoad` lifecycle hook.
componentWillLoad() { if ('serviceWorker' in navigator) { navigator.serviceWorker .getRegistration() .then(registration => { if (registration?.active) { navigator.serviceWorker.addEventListener( 'controllerchange', () => window.location.reload() ); } }) }}
### Handle push events[](https://stenciljs.com/docs/v4.33/service-workers#handle-push-events "Direct link to Handle push events")
A common use case for custom service workers is to handle browser push notifications. But before we will be able show push notifications, we first need to use the Notifications API to request permissions from the user to do so.
if ('Notification' in window && 'serviceWorker' in navigator) { Notification.requestPermission(status => { // status will either be 'default', 'granted' or 'denied' console.log(`Notification permissions have been ${status}`); });}
The current permission status can always be checked using `Notification.permission`.
To show a notification to the user after being granted permission, we can use the `showNotification` method of our service worker's registration (within our custom service worker).
self.registration.showNotification('Hakuna matata.');
Usually we will have a backend that will send out push notifications to clients, and we want our service worker to handle them. To do that, we can register an event listener in our worker for the `push` event. The event will be of type [`PushEvent`](https://developer.mozilla.org/en-US/docs/Web/API/PushEvent)
and have a `data` field of type [`PushMessageData`](https://developer.mozilla.org/en-US/docs/Web/API/PushMessageData)
.
self.addEventListener('push', event => { console.log(`Push received with data "${event.data.text()}"`); const title = 'Push Notification'; const options = { body: `${event.data.text()}`, data: { href: '/users/donald' }, actions: [ { action: 'details', title: 'Details' }, { action: 'dismiss', title: 'Dismiss' }, ], }; event.waitUntil(self.registration.showNotification(title, options));});
If the data is a JSON string, then `data.json()` can be used to immediately get the parsed data. The `event.waitUntil` method is used to ensure that the service worker doesn't terminate before the asynchronous `showNotification` operation has completed.
Furthermore, we will likely want to handle notification clicks. The API provides the events `notificationclick` and `notificationclose` for that.
self.addEventListener('notificationclick', event => { const notification = event.notification; const action = event.action; if (action === 'dismiss') { notification.close(); } else { // This handles both notification click and 'details' action, // because some platforms might not support actions. clients.openWindow(notification.data.href); notification.close(); }});
Now our service worker is able to receive and process push notifications, however we still need to register the client with our backend. Browsers provide a push service for that reason, which your app can subscribe to. The subscription object contains an endpoint URL with a unique identifier for each client. You can send your notifications to that URL, encrypted with a public key which is also provided by the subscription object.
In order to implement this, we first need to get each client to subscribe to the browser's push service, and then send the subscription object to our backend. Then our backend can generate the push notifications, encrypt them with the public key, and send them to the subscription endpoint URL.
First we will implement a function to subscribe the user to the push service, which as a best practice should be triggered from a user action signalling that they would like to receive push notifications. Assuming that notification permissions have already been granted, the following function can be used for that.
async function subscribeUser() { if ('serviceWorker' in navigator) { const registration = await navigator.serviceWorker.ready; const subscription = await registration.pushManager .subscribe({ userVisibleOnly: true }) .catch(console.error); if (!subscription) { return; } // the subscription object is what we want to send to our backend console.log(subscription.endpoint); }}
We should also check our subscription every time our app is accessed, because the subscription object can change.
self.registration.pushManager.getSubscription().then(subscription => { if (!subscription) { // ask the user to register for push return; } // update the database console.log(subscription);});
### Further Reading[](https://stenciljs.com/docs/v4.33/service-workers#further-reading "Direct link to Further Reading")
* For more information on push notifications and the related APIs please refer to the [Web Fundamentals Introduction to Push Notifications](https://developers.google.com/web/ilt/pwa/introduction-to-push-notifications)
and the [MDN Push API docs](https://developer.mozilla.org/en-US/docs/Web/API/Push_API)
.
* [This Twitter thread by David Brunelle](https://twitter.com/davidbrunelle/status/1073394572980453376)
explains how to implement versioning in your PWA in order to handle breaking API changes. The problem here is that your service worker enabled app will continue to serve an outdated (cached) app against your updated API. In order to solve this a version check can be implemented.
Contents
--------
* [What is Workbox?](https://stenciljs.com/docs/v4.33/service-workers#what-is-workbox)
* [Usage](https://stenciljs.com/docs/v4.33/service-workers#usage)
* [Config](https://stenciljs.com/docs/v4.33/service-workers#config)
* [Disabling the service worker](https://stenciljs.com/docs/v4.33/service-workers#disabling-the-service-worker)
* [Using a custom service worker](https://stenciljs.com/docs/v4.33/service-workers#using-a-custom-service-worker)
* [Showing a reload toast when an update is available](https://stenciljs.com/docs/v4.33/service-workers#showing-a-reload-toast-when-an-update-is-available)
* [Handle push events](https://stenciljs.com/docs/v4.33/service-workers#handle-push-events)
* [Further Reading](https://stenciljs.com/docs/v4.33/service-workers#further-reading)
* * *
[Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.33/guides/service-workers.md)
---
# Getting Started | Stencil
[Skip to main content](https://stenciljs.com/docs/getting-started#__docusaurus_skipToContent_fallback)
[An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none)
Version: v4.35
On this page
Starting a New Project[](https://stenciljs.com/docs/getting-started#starting-a-new-project "Direct link to Starting a New Project")
-------------------------------------------------------------------------------------------------------------------------------------
### Prerequisites[](https://stenciljs.com/docs/getting-started#prerequisites "Direct link to Prerequisites")
Stencil requires a recent LTS version of [NodeJS](https://nodejs.org/)
and npm/yarn. Make sure you've installed and/or updated Node before continuing.
### Running the `create-stencil` CLI[](https://stenciljs.com/docs/getting-started#running-the-create-stencil-cli "Direct link to running-the-create-stencil-cli")
The `create-stencil` CLI can be used to scaffold a new Stencil project, and can be run using the following command:
* npm
* Yarn
* pnpm
npm init stencil
yarn create stencil
pnpm create stencil
Stencil can be used to create standalone components, or entire apps. `create-stencil`, will provide a prompt so that you can choose the type of project to start:
? Select a starter project.Starters marked as [community] are developed by the StencilCommunity, rather than Ionic. For more information on the Stencil Community, please see github.com/stencil-community❯ component Collection of web components that can be used anywhere app [community] Minimal starter for building a Stencil app or website ionic-pwa [community] Ionic PWA starter with tabs layout and routes
Selecting the 'component' option will prompt you for the name of your project. Here, we'll name our project 'my-first-stencil-project':
✔ Pick a starter › component? Project name › my-first-stencil-project
After hitting `ENTER` to confirm your choices, the CLI will scaffold a Stencil project for us in a directory that matches the provided project name. Upon successfully creating our project, the CLI will print something similar to the following to the console:
✔ Project name › my-first-stencil-project✔ A new git repo was initialized✔ All setup in 26 ms We suggest that you begin by typing: $ cd my-first-stencil-project $ npm install $ npm start $ npm start Starts the development server. $ npm run build Builds your project in production mode. $ npm test Starts the test runner. Further reading: - https://github.com/ionic-team/stencil-component-starter Happy coding! 🎈
The first section describes a few commands required to finish getting your project bootstrapped.
* npm
* Yarn
* pnpm
cd my-first-stencil-projectnpm installnpm start
cd my-first-stencil-projectyarn installyarn start
cd my-first-stencil-projectpnpm installpnpm start
This will change your current directory to `my-first-stencil-project`, install your dependencies for you, and start the development server.
### Useful Initial Commands[](https://stenciljs.com/docs/getting-started#useful-initial-commands "Direct link to Useful Initial Commands")
The second section of the `create-stencil` output describes a few useful commands available during the development process:
* `npm start` starts a local development server. The development server will open a new browser tab containing your project's components. The dev-server uses hot-module reloading to update your components in the browser as you modify them for a rapid feedback cycle.
* `npm run build` creates a production-ready version of your components. The components generated in this step are not meant to be used in the local development server, but rather within a project that consumes your components.
* `npm test` runs your project's tests. The `create-stencil` CLI has created both end-to-end and unit tests when scaffolding your project.
### Source Control[](https://stenciljs.com/docs/getting-started#source-control "Direct link to Source Control")
As of create-stencil v3.3.0, a new git repository will be automatically created for you when you initialize a project if:
1. git is installed
2. Your project is not created under another git work tree (e.g. if you create a new project in a monorepo, a new git repo will not be created)
Versions of create-stencil prior to v3.3.0 do not interact with any version control systems (VCS). If you wish to place your project under version control, we recommend initializing your VCS now. If you wish to use git, run the following after changing your current directory to the root of your Stencil project:
$ git init$ git add -A$ git commit -m "initialize project using stencil cli"
My First Component[](https://stenciljs.com/docs/getting-started#my-first-component "Direct link to My First Component")
-------------------------------------------------------------------------------------------------------------------------
Stencil components are created by adding a new file with a `.tsx` extension, such as `my-component.tsx`. The `.tsx` extension is required since Stencil components are built using [JSX](https://stenciljs.com/docs/templating-jsx)
and TypeScript.
When we ran `create-stencil` above, it generated a component, `my-component.tsx`, that can be found in the `src/components/my-component` directory:
my-component.tsx
import { Component, Prop, h } from '@stencil/core';import { format } from '../../utils/utils';@Component({ tag: 'my-component', styleUrl: 'my-component.css', shadow: true,})export class MyComponent { @Prop() first: string; @Prop() middle: string; @Prop() last: string; private getText(): string { return format(this.first, this.middle, this.last); } render() { return
| `string` | `undefined` | The properties section will be placed after the [usage examples section](https://stenciljs.com/docs/docs-readme#usage-examples) of the README. If a component does not use the `@Prop()` decorator, this section will be omitted from the generated README. ### @Event() Details[](https://stenciljs.com/docs/docs-readme#event-details "Direct link to @Event() Details") Usages of Stencil's [`@Event()` decorator](https://stenciljs.com/docs/events) are described in a table containing the following information for each usage of `@Event()`: * **Event**: The name of the property on the TypeScript class decorated with `@Event()`. * **Description**: A description of the property, if one was given in a JSDoc comment for the property. * **Type**: The TypeScript type of the property. For the following usages of `@Event()` in a component: export class MyComponent { /** * Emitted when an event is completed */ @Event() todoCompleted: EventEmitter
| `CustomEvent
Mock Date Picker, mode: {this.view} this.onInputChange(e)}>
}}
Note that the `formStateRestoreCallback` also receives a second argument, `mode`, which can be either `"restore"` or `"autocomplete"`, indicating the reason for the form restoration.
For more on form restoration, including a complete example, check out [this great blog post on the subject](https://web.dev/articles/more-capable-form-controls#restoring-form-state)
.
Resources[](https://stenciljs.com/docs/v4.33/form-associated#resources "Direct link to Resources")
----------------------------------------------------------------------------------------------------
* [WHATWG specification for form-associated custom elements](https://html.spec.whatwg.org/dev/custom-elements.html#form-associated-custom-elements)
* [ElementInternals and Form-Associated Custom Elements](https://webkit.org/blog/13711/elementinternals-and-form-associated-custom-elements/)
from the WebKit blog
* [Web.dev post detailing how form-associated lifecycle callbacks work](https://web.dev/articles/more-capable-form-controls#lifecycle_callbacks)
Footnotes[](https://stenciljs.com/docs/v4.33/form-associated#footnote-label "Direct link to Footnotes")
---------------------------------------------------------------------------------------------------------
1. See [https://caniuse.com/?search=attachInternals](https://caniuse.com/?search=attachInternals)
for up-to-date adoption estimates. [↩](https://stenciljs.com/docs/v4.33/form-associated#user-content-fnref-1)
Contents
--------
* [Creating a Form-Associated Component](https://stenciljs.com/docs/v4.33/form-associated#creating-a-form-associated-component)
* [Lifecycle Callbacks](https://stenciljs.com/docs/v4.33/form-associated#lifecycle-callbacks)
* [`formAssociatedCallback`](https://stenciljs.com/docs/v4.33/form-associated#formassociatedcallback)
* [`formDisabledCallback`](https://stenciljs.com/docs/v4.33/form-associated#formdisabledcallback)
* [`formResetCallback`](https://stenciljs.com/docs/v4.33/form-associated#formresetcallback)
* [`formStateRestoreCallback`](https://stenciljs.com/docs/v4.33/form-associated#formstaterestorecallback)
* [Resources](https://stenciljs.com/docs/v4.33/form-associated#resources)
* * *
[Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.33/components/form-associated.md)
---
# Extras Config | Stencil
[Skip to main content](https://stenciljs.com/docs/v4.34/config-extras#__docusaurus_skipToContent_fallback)
[An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none)
This is documentation for Stencil **v4.34**, which is no longer actively maintained.
For up-to-date documentation, see the **[latest version](https://stenciljs.com/docs/config-extras)
** (v4.35).
Version: v4.34
On this page
The `extras` config contains options to enable new/experimental features in Stencil, add & remove runtime for DOM features that require manipulations to polyfills, etc. For example, not all DOM APIs are fully polyfilled when using the Slot polyfill. Most of these are opt-in, since not all users require the additional runtime.
### appendChildSlotFix[](https://stenciljs.com/docs/v4.34/config-extras#appendchildslotfix "Direct link to appendChildSlotFix")
By default, the slot polyfill does not update `appendChild()` so that it appends new child nodes into the correct child slot like how shadow dom works. This is an opt-in polyfill for those who need it.
### cloneNodeFix[](https://stenciljs.com/docs/v4.34/config-extras#clonenodefix "Direct link to cloneNodeFix")
By default, the runtime does not polyfill `cloneNode()` when cloning a component that uses the slot polyfill. This is an opt-in polyfill for those who need it.
### enableImportInjection[](https://stenciljs.com/docs/v4.34/config-extras#enableimportinjection "Direct link to enableImportInjection")
In some cases, it can be difficult to lazily load Stencil components in a separate project that uses a bundler such as [Vite](https://vitejs.dev/)
.
Enabling this flag will allow downstream projects that consume a Stencil library and use a bundler such as Vite to lazily load the Stencil library's components.
In order for this flag to work:
1. The Stencil library must expose lazy loadable components, such as those created with the [`dist` output target](https://stenciljs.com/docs/v4.34/distribution)
2. The Stencil library must be recompiled with this flag set to `true`
This flag works by creating dynamic import statements for every lazily loadable component in a Stencil project. Users of this flag should note that they may see an increase in their bundle size.
Defaults to `false`.
### experimentalImportInjection[](https://stenciljs.com/docs/v4.34/config-extras#experimentalimportinjection "Direct link to experimentalImportInjection")
caution
This flag has been deprecated in favor of [`enableImportInjection`](https://stenciljs.com/docs/v4.34/config-extras#enableimportinjection)
, which provides the same functionality. `experimentalImportInjection` will be removed in a future major version of Stencil.
In some cases, it can be difficult to lazily load Stencil components in a separate project that uses a bundler such as [Vite](https://vitejs.dev/)
.
This is an experimental flag that, when set to `true`, will allow downstream projects that consume a Stencil library and use a bundler such as Vite to lazily load the Stencil library's components.
In order for this flag to work:
1. The Stencil library must expose lazy loadable components, such as those created with the [`dist` output target](https://stenciljs.com/docs/v4.34/distribution)
2. The Stencil library must be recompiled with this flag set to `true`
This flag works by creating dynamic import statements for every lazily loadable component in a Stencil project. Users of this flag should note that they may see an increase in their bundle size.
Defaults to `false`.
### experimentalScopedSlotChanges[](https://stenciljs.com/docs/v4.34/config-extras#experimentalscopedslotchanges "Direct link to experimentalScopedSlotChanges")
This option updates runtime behavior for Stencil's support of slots in **scoped** components to match more closely with the native Shadow DOM behaviors.
When set to `true`, the following behaviors will be applied:
* Stencil will hide projected nodes that do not have a destination `slot` ([#2778](https://github.com/ionic-team/stencil/issues/2877)
) (since v4.10.0)
* The `textContent` getter will return the text content of all nodes located in a slot (since v4.10.0)
* The `textContent` setter will overwrite all nodes located in a slot (since v4.10.0)
Defaults to `false`.
note
These behaviors only apply to components using scoped encapsulation!
### experimentalSlotFixes[](https://stenciljs.com/docs/v4.34/config-extras#experimentalslotfixes "Direct link to experimentalSlotFixes")
This option enables all current and future slot-related fixes. When enabled it will enable the following options, overriding their values if they are specified separately:
* [`slotChildNodesFix`](https://stenciljs.com/docs/v4.34/config-extras#slotchildnodesfix)
* [`scopedSlotTextContentFix`](https://stenciljs.com/docs/v4.34/config-extras#scopedslottextcontentfix)
.
* [`appendChildSlotFix`](https://stenciljs.com/docs/v4.34/config-extras#appendchildslotfix)
* [`cloneNodeFix`](https://stenciljs.com/docs/v4.34/config-extras#clonenodefix)
Slot-related fixes to the runtime will be added over the course of Stencil v4, with the intent of making these the default behavior in Stencil v5. When set to `true` fixes for the following issues will be applied:
* Elements rendered outside of slot when shadow not enabled [(#2641)](https://github.com/ionic-team/stencil/issues/2641)
(since v4.2.0)
* A slot gets the attribute hidden when it shouldn't [(#4523)](https://github.com/ionic-team/stencil/issues/4523)
(since v4.7.0)
* Nested slots mis-ordered when not using Shadow DOM [(#2997)](https://github.com/ionic-team/stencil/issues/2997)
(since v4.7.0)
* Inconsistent behavior: slot-fb breaks styling of default slot content in component with 'shadow: false' [(#2937)](https://github.com/ionic-team/stencil/issues/2937)
(since v4.7.2)
* Slot content went missing within dynamic component [(#4284)](https://github.com/ionic-team/stencil/issues/4284)
(since v4.8.2)
* Slot element loses its parent reference and disappears when its parent is rendered conditionally [(#3913)](https://github.com/ionic-team/stencil/issues/3913)
(since v4.8.2)
* Failed to execute 'removeChild' on 'Node' [(#3278)](https://github.com/ionic-team/stencil/issues/3278)
(since v4.9.0)
* React fails to manage children in Stencil slot [(#2259)](https://github.com/ionic-team/stencil/issues/2259)
(since v4.9.0)
* Slot name is not updated when it is bind to a prop [(#2982)](https://github.com/ionic-team/stencil/issues/2982)
(since 4.12.1)
* Conditionally rendered slots not working [(#5335)](https://github.com/ionic-team/stencil/issues/5335)
(since 4.13.0)
note
New fixes enabled by this experimental flag are not subject to Stencil's [semantic versioning policy](https://stenciljs.com/docs/v4.34/versioning)
.
### lifecycleDOMEvents[](https://stenciljs.com/docs/v4.34/config-extras#lifecycledomevents "Direct link to lifecycleDOMEvents")
Dispatches component lifecycle events. By default these events are not dispatched, but by enabling this to `true` these events can be listened for on `window`. Mainly used for testing.
| Event Name | Description |
| --- | --- |
| `stencil_componentWillLoad` | Dispatched for each component's `componentWillLoad`. |
| `stencil_componentWillUpdate` | Dispatched for each component's `componentWillUpdate`. |
| `stencil_componentWillRender` | Dispatched for each component's `componentWillRender`. |
| `stencil_componentDidLoad` | Dispatched for each component's `componentDidLoad`. |
| `stencil_componentDidUpdate` | Dispatched for each component's `componentDidUpdate`. |
| `stencil_componentDidRender` | Dispatched for each component's `componentDidRender`. |
### scopedSlotTextContentFix[](https://stenciljs.com/docs/v4.34/config-extras#scopedslottextcontentfix "Direct link to scopedSlotTextContentFix")
An experimental flag that when set to `true`, aligns the behavior of invoking the `textContent` getter/setter on a scoped component to act more like a component that uses the shadow DOM. Specifically, invoking `textContent` on a component will adhere to the return values described in [MDN's article on textContent](https://developer.mozilla.org/en-US/docs/Web/API/Node/textContent#description)
. Defaults to `false`.
### scriptDataOpts[](https://stenciljs.com/docs/v4.34/config-extras#scriptdataopts "Direct link to scriptDataOpts")
caution
This option has been deprecated and will be removed in the next major Stencil release.
It is possible to assign data to the actual `
Seconds: {state.seconds}
Squared Clicks: {state.squaredClicks}
To-Do List
- {this.items.map((todo) =>
- {todo.description} #{todo.id} )}
, written in Markdown files in the `usages/` directory adjacent to the current component. | | `props` | Array of metadata objects for each usage of the [`@Prop` decorator](https://stenciljs.com/docs/v4.33/properties#the-prop-decorator-prop)
on the current component. | | `methods` | Array of metadata objects for each usage of the [`@Method` decorator](https://stenciljs.com/docs/v4.33/methods)
on the current component. | | `events` | Array of metadata objects for each usage of the [`@Event` decorator](https://stenciljs.com/docs/v4.33/events#event-decorator)
on the current component. | | `listeners` | Array of metadata objects for each usage of the [`@Listen` decorator](https://stenciljs.com/docs/v4.33/events#listen-decorator)
on the current component. | | `styles` | Array of objects documenting annotated [CSS variables](https://stenciljs.com/docs/v4.33/docs-json#css-variables)
used in the current component's CSS. | | `slots` | Array of objects documenting [slots](https://stenciljs.com/docs/v4.33/docs-json#slots)
which are tagged with `@slot` in the current component's JSDoc comment. | | `parts` | Array of objects derived from `@part` tags in the current component's JSDoc comment. | | `dependents` | Array of components where current component is used | | `dependencies` | Array of components which is used in current component | | `dependencyGraph` | Describes a tree of components coupling | Contents -------- * [Config](https://stenciljs.com/docs/v4.33/docs-custom#config) * [JsonDocs](https://stenciljs.com/docs/v4.33/docs-custom#jsondocs) * [JsonDocsComponent](https://stenciljs.com/docs/v4.33/docs-custom#jsondocscomponent) * * * [Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.33/documentation-generation/docs-custom.md) --- # Methods | Stencil [Skip to main content](https://stenciljs.com/docs/v4.34/methods#__docusaurus_skipToContent_fallback) [An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none) This is documentation for Stencil **v4.34**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](https://stenciljs.com/docs/methods) ** (v4.35). Version: v4.34 On this page The `@Method()` decorator is used to expose methods on the public API. Functions decorated with the `@Method()` decorator can be called directly from the element, i.e. they are intended to be callable from the outside! note Developers should try to rely on publicly exposed methods as little as possible, and instead default to using properties and events as much as possible. As an app scales, we've found it's easier to manage and pass data through @Prop rather than public methods. import { Method } from '@stencil/core';export class TodoList { @Method() async showPrompt() { // show a prompt }} Call the method like this: note Developers should ensure that the component is defined by using the whenDefined method of the custom element registry before attempting to call public methods. (async () => { await customElements.whenDefined('todo-list'); const todoListElement = document.querySelector('todo-list'); await todoListElement.showPrompt();})(); Public methods must be async[](https://stenciljs.com/docs/v4.34/methods#public-methods-must-be-async "Direct link to Public methods must be async") ----------------------------------------------------------------------------------------------------------------------------------------------------- Stencil's architecture is async at all levels which allows for many performance benefits and ease of use. By ensuring publicly exposed methods using the `@Method` decorator return a promise: * Developers can call methods before the implementation was downloaded without componentOnReady(), which queues the method calls and resolves after the component has finished loading. * Interaction with the component is the same whether it still needs to be lazy-loaded, or is already fully hydrated. * By keeping a component's public API async, apps could move the components transparently to [Web Worker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API) and the API would still be the same. * Returning a promise is only required for publicly exposed methods which have the `@Method` decorator. All other component methods are private to the component and are not required to be async. // VALID: using async@Method()async myMethod() { return 42;}// VALID: using Promise.resolve()@Method()myMethod2() { return Promise.resolve(42);}// VALID: even if it returns nothing, it needs to be async@Method()async myMethod3() { console.log(42);}// INVALID@Method()notOk() { return 42;} Private methods[](https://stenciljs.com/docs/v4.34/methods#private-methods "Direct link to Private methods") -------------------------------------------------------------------------------------------------------------- Non-public methods can still be used to organize the business logic of your component and they do NOT have to return a Promise. class Component { // Since `getData` is not a public method exposed with @Method // it does not need to be async getData() { return this.someData; } render() { return (
{this.getData()}
); }}
Contents
--------
* [Public methods must be async](https://stenciljs.com/docs/v4.34/methods#public-methods-must-be-async)
* [Private methods](https://stenciljs.com/docs/v4.34/methods#private-methods)
* * *
[Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.34/components/methods.md)
---
# Typed Components | Stencil
[Skip to main content](https://stenciljs.com/docs/v4.33/typed-components#__docusaurus_skipToContent_fallback)
[An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none)
This is documentation for Stencil **v4.33**, which is no longer actively maintained.
For up-to-date documentation, see the **[latest version](https://stenciljs.com/docs/typed-components)
** (v4.35).
Version: v4.33
On this page
Web Components generated with Stencil come with type declaration files automatically generated by the Stencil compiler.
In general, TypeScript declarations provide strong guarantees when consuming components:
* Ensuring that proper values are passed down as properties
* Code autocompletion in modern IDEs such as VSCode
* Events' details
* Signature of components' methods
These public types are automatically generated by Stencil in `src/component.d.ts`. This file allows for strong typing in JSX (just like React) and `HTMLElement` interfaces for each component.
tip
It is recommended that this file be checked in with the rest of your code in source control.
Because Web Components generated by Stencil are just vanilla Web Components, they extend the `HTMLElement` interface. For each component a type named `HTML{CamelCaseTag}Element` is registered at the global scope. This means developers DO NOT have to import them explicitly, just like `HTMLElement` or `HTMLScriptElement` are not imported.
* `ion-button` => `HTMLIonButtonElement`
* `ion-menu-controller` => `HTMLIonMenuControllerElement`
const button: HTMLIonButtonElement = document.queryElement('ion-button');button.fill = 'outline';
**IMPORTANT**: always use the `HTML{}Element` interfaces in order to hold references to components.
Properties[](https://stenciljs.com/docs/v4.33/typed-components#properties "Direct link to Properties")
--------------------------------------------------------------------------------------------------------
This section has moved to [Property Types](https://stenciljs.com/docs/v4.33/properties#types)
### Required Properties[](https://stenciljs.com/docs/v4.33/typed-components#required-properties "Direct link to Required Properties")
This section has moved to [Required Properties](https://stenciljs.com/docs/v4.33/properties#required-properties)
Contents
--------
* [Properties](https://stenciljs.com/docs/v4.33/typed-components#properties)
* [Required Properties](https://stenciljs.com/docs/v4.33/typed-components#required-properties)
* * *
[Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.33/guides/typed-components.md)
---
# Framework Integration | Stencil
[Skip to main content](https://stenciljs.com/docs/v4.33/overview#__docusaurus_skipToContent_fallback)
[An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none)
This is documentation for Stencil **v4.33**, which is no longer actively maintained.
For up-to-date documentation, see the **[latest version](https://stenciljs.com/docs/overview)
** (v4.35).
Version: v4.33
Stencil's primary goal is to remove the need for components to be written using a specific framework's API. It accomplishes this by using standardized web platform APIs that work across all modern browsers. Using the low-level component model that is provided by the browser (which all frameworks are built on) allows Stencil components to work inside a framework or without one.
The experience of integrating web components directly into existing applications can be tricky at times, as frameworks have varying support for vanilla web components. In order to accommodate the various issues the Stencil team has created Framework Wrappers to make the process simpler.
The Framework Wrappers are configured like output targets, and emit a native library, just like if your components were originally written using any of these frameworks:
* [Angular](https://stenciljs.com/docs/v4.33/angular)
* [React](https://stenciljs.com/docs/v4.33/react)
* [Vue](https://stenciljs.com/docs/v4.33/vue)
* [Ember (Community)](https://stenciljs.com/docs/v4.33/ember)
By using Stencil bindings, you can build your components once, and have Stencil emit Angular/React/Vue libraries. This way, the consumers of your components can enjoy all the features of their framework of choice.
---
# Store | Stencil
[Skip to main content](https://stenciljs.com/docs/v4.34/stencil-store#__docusaurus_skipToContent_fallback)
[An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none)
This is documentation for Stencil **v4.34**, which is no longer actively maintained.
For up-to-date documentation, see the **[latest version](https://stenciljs.com/docs/stencil-store)
** (v4.35).
Version: v4.34
On this page
[Store](https://github.com/ionic-team/stencil-store)
is a lightweight shared state library by the stencil core team. It implements a simple key/value map that efficiently re-renders components when necessary.
* Lightweight
* Zero dependencies
* Simple API, like a reactive Map
* Best performance
Installation[](https://stenciljs.com/docs/v4.34/stencil-store#installation "Direct link to Installation")
-----------------------------------------------------------------------------------------------------------
* npm
* Yarn
* pnpm
npm install @stencil/store --save-dev
yarn add @stencil/store --dev
pnpm add @stencil/store --save-dev
Example[](https://stenciljs.com/docs/v4.34/stencil-store#example "Direct link to Example")
--------------------------------------------------------------------------------------------
**store.ts:**
import { createStore } from "@stencil/store";const { state, onChange } = createStore({ clicks: 0, seconds: 0, squaredClicks: 0});onChange('clicks', value => { state.squaredClicks = value ** 2;});export default state;
**component.tsx:**
import { Component, h } from '@stencil/core';import state from '../store';@Component({ tag: 'app-profile',})export class AppProfile { componentWillLoad() { setInterval(() => state.seconds++, 1000); } render() { return (
Seconds: {state.seconds}
Squared Clicks: {state.squaredClicks}
Title
Message
Title
Message
{this.heading}
Outer Component
Inner Component
...
...
...
); }}
* [**h()**](https://stenciljs.com/docs/v4.34/templating-jsx)
: It's used within the `render()` to turn the JSX into Virtual DOM elements.
* **render()**: a utility method to render a virtual DOM created by `h()` into a container.
**Type:** `(vnode: VNode, container: Element) => void` **Example:**
import { render } from '@stencil/core'const vdom = ( Hello World!
)render(vdom, document.body)
* [**readTask()**](https://developers.google.com/web/fundamentals/performance/rendering/avoid-large-complex-layouts-and-layout-thrashing)
: Schedules a DOM-read task. The provided callback will be executed in the best moment to perform DOM reads without causing layout thrashing.
**Type:** `(task: Function) => void`
* [**writeTask()**](https://developers.google.com/web/fundamentals/performance/rendering/avoid-large-complex-layouts-and-layout-thrashing)
: Schedules a DOM-write task. The provided callback will be executed in the best moment to perform DOM mutations without causing layout thrashing.
**Type:** `(task: Function) => void`
* **forceUpdate()**: Schedules a new render of the given instance or element even if no state changed. Notice `forceUpdate()` is not synchronous and might perform the DOM render in the next frame.
**Type:** `(ref: any) => void`
**Example:**
import { forceUpdate } from '@stencil/core'// inside a class component functionforceUpdate(this);
* **getAssetPath()**: Gets the path to local assets. Refer to the [Assets](https://stenciljs.com/docs/v4.34/assets#getassetpath)
page for usage info.
**Type:** `(path: string) => string`
**Example:**
import { Component, Prop, getAssetPath, h } from '@stencil/core'@Component({ tag: 'cmp-asset',})export class CmpAsset { @Prop() icon: string; render() { return ( ); }}
* **setAssetPath()**: Sets the path for Stencil to resolve local assets. Refer to the [Assets](https://stenciljs.com/docs/v4.34/assets#setassetpath)
page for usage info.
**Type:** `(path: string) => string`
**Example:**
import { setAssetPath } from '@stencil/core';setAssetPath(`{window.location.origin}/`);
* **setMode()**: Sets the style mode of a component. Refer to the [Styling](https://stenciljs.com/docs/v4.34/styling#style-modes)
page for usage info.
**Type:** `((elm: HTMLElement) => string | undefined | null) => void`
**Example:**
import { setMode } from '@stencil/core'// set mode based on a propertysetMode((el) => el.getAttribute('mode'));
* **getMode()**: Get the current style mode of your application. Refer to the [Styling](https://stenciljs.com/docs/v4.34/styling#style-modes)
page for usage info.
**Type:** `(ref: any) => string | undefined`
**Example:**
import { getMode } from '@stencil/core'getMode(this);
* **getElement()**: Retrieve a Stencil element for a given reference.
**Type:** `(ref: any) => HTMLStencilElement`
**Example:**
import { getElement } from '@stencil/core'const stencilComponent = getElement(document.querySelector('my-cmp'))if (stencilComponent) { stencilComponent.componentOnReady().then(() => { ... })}
Contents
--------
* [Decorators](https://stenciljs.com/docs/v4.34/api#decorators)
* [Lifecycle hooks](https://stenciljs.com/docs/v4.34/api#lifecycle-hooks)
* [componentOnReady()](https://stenciljs.com/docs/v4.34/api#componentonready)
* [The `appload` event](https://stenciljs.com/docs/v4.34/api#the-appload-event)
* [Other](https://stenciljs.com/docs/v4.34/api#other)
* * *
[Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.34/components/api.md)
---
# Reactive Data, Handling arrays and objects | Stencil
[Skip to main content](https://stenciljs.com/docs/v4.33/reactive-data#__docusaurus_skipToContent_fallback)
[An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none)
This is documentation for Stencil **v4.33**, which is no longer actively maintained.
For up-to-date documentation, see the **[latest version](https://stenciljs.com/docs/reactive-data)
** (v4.35).
Version: v4.33
On this page
Stencil components update when props or state on a component change.
Rendering methods[](https://stenciljs.com/docs/v4.33/reactive-data#rendering-methods "Direct link to Rendering methods")
--------------------------------------------------------------------------------------------------------------------------
When props or state change on a component, the [`render()` method](https://stenciljs.com/docs/v4.33/templating-jsx)
is scheduled to run.
The Watch Decorator (`@Watch()`)[](https://stenciljs.com/docs/v4.33/reactive-data#the-watch-decorator-watch "Direct link to the-watch-decorator-watch")
---------------------------------------------------------------------------------------------------------------------------------------------------------
`@Watch()` is a decorator that is applied to a method of a Stencil component. The decorator accepts a single argument, the name of a class member that is decorated with `@Prop()` or `@State()`, or a host attribute. A method decorated with `@Watch()` will automatically run when its associated class member or attribute changes.
// We import Prop & State to show how `@Watch()` can be used on// class members decorated with either `@Prop()` or `@State()`import { Component, Prop, State, Watch } from '@stencil/core';@Component({ tag: 'loading-indicator' })export class LoadingIndicator { // We decorate a class member with @Prop() so that we // can apply @Watch() @Prop() activated: boolean; // We decorate a class member with @State() so that we // can apply @Watch() @State() busy: boolean; // Apply @Watch() for the component's `activated` member. // Whenever `activated` changes, this method will fire. @Watch('activated') watchPropHandler(newValue: boolean, oldValue: boolean) { console.log('The old value of activated is: ', oldValue); console.log('The new value of activated is: ', newValue); } // Apply @Watch() for the component's `busy` member. // Whenever `busy` changes, this method will fire. @Watch('busy') watchStateHandler(newValue: boolean, oldValue: boolean) { console.log('The old value of busy is: ', oldValue); console.log('The new value of busy is: ', newValue); } @Watch('activated') @Watch('busy') watchMultiple(newValue: boolean, oldValue: boolean, propName:string) { console.log(`The new value of ${propName} is: `, newValue); }}
In the example above, there are two `@Watch()` decorators. One decorates `watchPropHandler`, which will fire when the class member `activated` changes. The other decorates `watchStateHandler`, which will fire when the class member `busy` changes.
When fired, the decorated method will receive the old and new values of the prop/state. This is useful for validation or the handling of side effects.
info
The `@Watch()` decorator does not fire when a component initially loads.
### Watching Native HTML Attributes[](https://stenciljs.com/docs/v4.33/reactive-data#watching-native-html-attributes "Direct link to Watching Native HTML Attributes")
Stencil's `@Watch()` decorator also allows you to watch native HTML attributes on the constructed host element. Simply include the attribute name as the argument to the decorator (this is case-sensitive):
@Watch('aria-label')onAriaLabelChange(newVal: string, oldVal: string) { console.log('Label changed:', newVal, oldVal);}
note
Since native attributes are not `@Prop()` or `State()` members of the Stencil component, they will not automatically trigger a re-render when changed. If you wish to re-render a component in this instance, you can leverage the `forceUpdate()` method:
import { Component, forceUpdate, h } from '@stencil/core';@Watch('aria-label')onAriaLabelChange() { forceUpdate(this); // Forces a re-render}
Handling Arrays and Objects[](https://stenciljs.com/docs/v4.33/reactive-data#handling-arrays-and-objects "Direct link to Handling Arrays and Objects")
--------------------------------------------------------------------------------------------------------------------------------------------------------
When Stencil checks if a class member decorated with `@Prop()` or `@State()` has changed, it checks if the reference to the class member has changed. When a class member is an object or array, and is marked with `@Prop()` or `@State`, in-place mutation of an existing entity will _not_ cause `@Watch()` to fire, as it does not change the _reference_ to the class member.
### Updating Arrays[](https://stenciljs.com/docs/v4.33/reactive-data#updating-arrays "Direct link to Updating Arrays")
For arrays, the standard mutable array operations such as `push()` and `unshift()` won't trigger a component update. These functions will change the content of the array, but won't change the reference to the array itself.
In order to make changes to an array, non-mutable array operators should be used. Non-mutable array operators return a copy of a new array that can be detected in a performant manner. These include `map()` and `filter()`, and the [spread operator syntax](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Spread_operator)
. The value returned by `map()`, `filter()`, etc., should be assigned to the `@Prop()` or `@State()` class member being watched.
For example, to push a new item to an array, create a new array with the existing values and the new value at the end:
import { Component, State, Watch, h } from '@stencil/core';@Component({ tag: 'rand-numbers'})export class RandomNumbers { // We decorate a class member with @State() so that we // can apply @Watch(). This will hold a list of randomly // generated numbers @State() randNumbers: number[] = []; private timer: NodeJS.Timer; // Apply @Watch() for the component's `randNumbers` member. // Whenever `randNumbers` changes, this method will fire. @Watch('randNumbers') watchStateHandler(newValue: number[], oldValue: number[]) { console.log('The old value of randNumbers is: ', oldValue); console.log('The new value of randNumbers is: ', newValue); } connectedCallback() { this.timer = setInterval(() => { // generate a random whole number const newVal = Math.ceil(Math.random() * 100); /** * This does not create a new array. When stencil * attempts to see if any Watched members have changed, * it sees the reference to its `randNumbers` State is * the same, and will not trigger `@Watch` or a re-render */ // this.randNumbers.push(newVal) /** * Using the spread operator, on the other hand, does * create a new array. `randNumbers` is reassigned * using the value returned by the spread operator. * The reference to `randNumbers` has changed, which * will trigger `@Watch` and a re-render */ this.randNumbers = [...this.randNumbers, newVal] }, 1000) } disconnectedCallback() { if (this.timer) { clearInterval(this.timer) } } render() { return( randNumbers contains:
) }}
### Updating an object[](https://stenciljs.com/docs/v4.33/reactive-data#updating-an-object "Direct link to Updating an object")
The spread operator should be used to update objects. As with arrays, mutating an object will not trigger a view update in Stencil. However, using the spread operator and assigning its return value to the `@Prop()` or `@State()` class member being watched will. Below is an example:
import { Component, State, Watch, h } from '@stencil/core';export type NumberContainer = { val: number,}@Component({ tag: 'rand-numbers'})export class RandomNumbers { // We decorate a class member with @State() so that we // can apply @Watch(). This will hold a randomly generated // number. @State() numberContainer: NumberContainer = { val: 0 }; private timer: NodeJS.Timer; // Apply @Watch() for the component's `numberContainer` member. // Whenever `numberContainer` changes, this method will fire. @Watch('numberContainer') watchStateHandler(newValue: NumberContainer, oldValue: NumberContainer) { console.log('The old value of numberContainer is: ', oldValue); console.log('The new value of numberContainer is: ', newValue); } connectedCallback() { this.timer = setInterval(() => { // generate a random whole number const newVal = Math.ceil(Math.random() * 100); /** * This does not create a new object. When stencil * attempts to see if any Watched members have changed, * it sees the reference to its `numberContainer` State is * the same, and will not trigger `@Watch` or are-render */ // this.numberContainer.val = newVal; /** * Using the spread operator, on the other hand, does * create a new object. `numberContainer` is reassigned * using the value returned by the spread operator. * The reference to `numberContainer` has changed, which * will trigger `@Watch` and a re-render */ this.numberContainer = {...this.numberContainer, val: newVal}; }, 1000) } disconnectedCallback() { if (this.timer) { clearInterval(this.timer) } } render() { return - {this.randNumbers.map((num) =>
- {num} )}
numberContainer contains: {this.numberContainer.val}
; }}
Contents
--------
* [Rendering methods](https://stenciljs.com/docs/v4.33/reactive-data#rendering-methods)
* [The Watch Decorator (`@Watch()`)](https://stenciljs.com/docs/v4.33/reactive-data#the-watch-decorator-watch)
* [Watching Native HTML Attributes](https://stenciljs.com/docs/v4.33/reactive-data#watching-native-html-attributes)
* [Handling Arrays and Objects](https://stenciljs.com/docs/v4.33/reactive-data#handling-arrays-and-objects)
* [Updating Arrays](https://stenciljs.com/docs/v4.33/reactive-data#updating-arrays)
* [Updating an object](https://stenciljs.com/docs/v4.33/reactive-data#updating-an-object)
* * *
[Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.33/components/reactive-data.md)
---
# Testing | Stencil
[Skip to main content](https://stenciljs.com/docs/v4.33/testing-overview#__docusaurus_skipToContent_fallback)
[An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none)
This is documentation for Stencil **v4.33**, which is no longer actively maintained.
For up-to-date documentation, see the **[latest version](https://stenciljs.com/docs/testing-overview)
** (v4.35).
Version: v4.33
On this page
In order to ensure that your Stencil components work the way you expect, Stencil provides testing support out of the box. Stencil offers both unit testing and end-to-end testing capabilities.
Unit Testing vs. End-to-end Testing[](https://stenciljs.com/docs/v4.33/testing-overview#unit-testing-vs-end-to-end-testing "Direct link to Unit Testing vs. End-to-end Testing")
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Testing within Stencil is broken up into two distinct types: Unit tests and End-to-end (e2e) tests.
There are several philosophies on how testing should be done, and how to differentiate what should be considered a unit test versus an end-to-end test. Stencil takes an opinionated stance so developers have a description of each to better choose when to use each type of testing:
**Unit tests** focus on testing a component's methods in isolation. For example, when a method is given the argument `X`, it should return `Y`.
**End-to-end tests** focus on how the components are rendered in the DOM and how the individual components work together. For example, when `my-component` has the `X` attribute, the child component then renders the text `Y`, and expects to receive the event `Z`.
Library Support[](https://stenciljs.com/docs/v4.33/testing-overview#library-support "Direct link to Library Support")
-----------------------------------------------------------------------------------------------------------------------
Stencil currently supports the following tools for testing components:
* [Stencil Test Runner](https://stenciljs.com/docs/v4.33/testing/stencil-testrunner/overview)
: a built-in test runner based on Jest v27 - v29 for unit and end-to-end testing with Puppeteer to run within an actual browser in order to provide more realistic results.
* [WebdriverIO](https://stenciljs.com/docs/v4.33/testing/webdriverio/overview)
: a browser and mobile automation test framework for Node.js that allows you to run component and end-to-end tests across all browsers.
* [Playwright](https://stenciljs.com/docs/v4.33/testing/playwright/overview)
: an automated end-to-end testing framework that can run across all major browsers
* [Jest v30+](https://stenciljs.com/docs/v4.33/testing/jest)
: successor of the Stencil Test Runner for unit testing support in Jest v30 and up.
info
We are actively working to support a wider range of testing tools, including Playwright. Stay tuned for updates!
Contents
--------
* [Unit Testing vs. End-to-end Testing](https://stenciljs.com/docs/v4.33/testing-overview#unit-testing-vs-end-to-end-testing)
* [Library Support](https://stenciljs.com/docs/v4.33/testing-overview#library-support)
* * *
[Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.33/testing/01-overview.md)
---
# Framework Integration | Stencil
[Skip to main content](https://stenciljs.com/docs/v4.34/overview#__docusaurus_skipToContent_fallback)
[An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none)
This is documentation for Stencil **v4.34**, which is no longer actively maintained.
For up-to-date documentation, see the **[latest version](https://stenciljs.com/docs/overview)
** (v4.35).
Version: v4.34
Stencil's primary goal is to remove the need for components to be written using a specific framework's API. It accomplishes this by using standardized web platform APIs that work across all modern browsers. Using the low-level component model that is provided by the browser (which all frameworks are built on) allows Stencil components to work inside a framework or without one.
The experience of integrating web components directly into existing applications can be tricky at times, as frameworks have varying support for vanilla web components. In order to accommodate the various issues the Stencil team has created Framework Wrappers to make the process simpler.
The Framework Wrappers are configured like output targets, and emit a native library, just like if your components were originally written using any of these frameworks:
* [Angular](https://stenciljs.com/docs/v4.34/angular)
* [React](https://stenciljs.com/docs/v4.34/react)
* [Vue](https://stenciljs.com/docs/v4.34/vue)
* [Ember (Community)](https://stenciljs.com/docs/v4.34/ember)
By using Stencil bindings, you can build your components once, and have Stencil emit Angular/React/Vue libraries. This way, the consumers of your components can enjoy all the features of their framework of choice.
---
# Stencil Style Guide | Stencil
[Skip to main content](https://stenciljs.com/docs/style-guide#__docusaurus_skipToContent_fallback)
[An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none)
Version: v4.35
On this page
This is a component style guide created and enforced internally by the core team of Stencil, for the purpose of standardizing Stencil components. This should only be used as a reference for other teams in creating their own style guides. Feel free to modify to your team's own preference.
note
In order to enforce this (or your team's) style guide, we recommend leveraging a static analysis tool like [ESLint](https://eslint.org/)
. [@stencil-community/eslint-plugin](https://www.npmjs.com/package/@stencil-community/eslint-plugin)
provides rules specifically for writing Stencil components.
note
This guide once recommended TSLint as a static analysis tool. TSLint has been deprecated by its maintaining organization in favor of ESLint and is no longer recommended by the Stencil team.
File structure[](https://stenciljs.com/docs/style-guide#file-structure "Direct link to File structure")
---------------------------------------------------------------------------------------------------------
* One component per file.
* One component per directory. Though it may make sense to group similar components into the same directory, we've found it's easier to document components when each one has its own directory.
* Implementation (.tsx) and styles of a component should live in the same directory.
Example from ionic-core:
├── my-card│ ├── my-card.ios.css│ ├── my-card.md.css│ ├── my-card.css│ ├── my-card.tsx│ └── test│ └── basic│ ├── e2e.js│ └── index.html├── my-card-content│ ├── my-card-content.ios.css│ ├── my-card-content.md.css│ ├── my-card-content.css│ └── my-card-content.tsx├── my-card-title│ ├── my-card-title.ios.css│ ├── my-card-title.md.css│ ├── my-card-title.css
Naming[](https://stenciljs.com/docs/style-guide#naming "Direct link to Naming")
---------------------------------------------------------------------------------
### HTML tag[](https://stenciljs.com/docs/style-guide#html-tag "Direct link to HTML tag")
#### Prefix[](https://stenciljs.com/docs/style-guide#prefix "Direct link to Prefix")
The prefix has a major role when you are creating a collection of components intended to be used across different projects, like [@ionic/core](https://www.npmjs.com/package/@ionic/core)
. Web Components are not scoped because they are globally declared within the webpage, which means a "unique" prefix is needed to prevent collisions. The prefix also helps to quickly identify the collection a component is part of. Additionally, web components are required to contain a "-" dash within the tag name, so using the first section to namespace your components is a natural fit.
We do not recommend using "stencil" as prefix, since Stencil DOES NOT emit stencil components, but rather the output is standards compliant web components.
DO NOT do this:
Hello, World! I'm {this.getText()}
; }}
Once compiled, this component can be used in HTML just like any other tag.
Hello, World! I'm {this.getText()}
; }
This component's `render()` returns a `` element, containing text to render to the screen.
The `render()` function uses all three class members decorated with `@Prop()`, through the `getText` function. Declaring private functions like `getText` helps pull logic out of the `render()` function's JSX.
Any property decorated with `@Prop()` is also automatically watched for changes. If a user of our component were to change the element's `first`, `middle`, or `last` properties, our component would fire its `render()` function again, updating the displayed content.
Local Development[](https://stenciljs.com/docs/getting-started#local-development "Direct link to Local Development")
----------------------------------------------------------------------------------------------------------------------
After creating your Stencil components, you'll likely want to use them in an existing application. There are multiple approaches for local development depending on your project setup.
### Framework Integration[](https://stenciljs.com/docs/getting-started#framework-integration "Direct link to Framework Integration")
If you want to integrate your Stencil components directly into an existing application built with frameworks like React, Angular, or Vue, refer to the [Framework Integrations](https://stenciljs.com/docs/overview)
guide for specific integration instructions.
### Using Component Library in Another Project[](https://stenciljs.com/docs/getting-started#using-component-library-in-another-project "Direct link to Using Component Library in Another Project")
If you're building a standalone component library and want to use it in another project during development, you have two main options:
### Using Script Tags[](https://stenciljs.com/docs/getting-started#using-script-tags "Direct link to Using Script Tags")
For applications that don't use npm or for simple HTML pages, you can include your components directly with a script tag:
# First, build your Stencil projectcd my-first-stencil-projectnpm run build
This creates a `dist` folder containing your compiled components. Copy this folder to your application, then add a script tag that points to the ESM bundle:
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. This file can be used as the root module when distributing your component library, see [Publishing](https://stenciljs.com/docs/publishing)
for more details. | note At this time, components that do not use JSX cannot be automatically defined. This is a known limitation of Stencil that users should be aware of. ### dir[](https://stenciljs.com/docs/v4.34/custom-elements#dir "Direct link to dir") _default: `'dist/components'`_ This config option allows you to change the output directory where the compiled output for this output target will be written. ### empty[](https://stenciljs.com/docs/v4.34/custom-elements#empty "Direct link to empty") _default: `true`_ Setting this flag to `true` will remove the contents of the [output directory](https://stenciljs.com/docs/v4.34/custom-elements#dir) between builds. ### externalRuntime[](https://stenciljs.com/docs/v4.34/custom-elements#externalruntime "Direct link to externalRuntime") _default: `true`_ Setting this flag to `true` results in the following behaviors: 1. Minification will follow what is specified in the [Stencil config](https://stenciljs.com/docs/v4.34/config#minifyjs) . 2. Filenames will not be hashed. 3. All imports from packages under `@stencil/core/*` will be marked as external and therefore not included in the generated Rollup bundle. Ensure that `@stencil/core` is included in your list of dependencies if you set this option to `true`. This is crucial to prevent any runtime errors. ### generateTypeDeclarations[](https://stenciljs.com/docs/v4.34/custom-elements#generatetypedeclarations "Direct link to generateTypeDeclarations") _default: `true`_ By default, Stencil will generate type declaration files (`.d.ts` files) as a part of the `dist-custom-elements` output target through the `generateTypeDeclarations` field on the target options. Type declaration files will be placed in the `dist/types` directory in the root of a Stencil project. At this time, this output destination is not able to be configured. Setting this flag to `false` will not generate type declaration files for the `dist-custom-elements` output target. note When set to generate type declarations, Stencil respects the export behavior selected via `customElementsExportBehavior` and generates type declarations specific to the content of the generated [output directory's](https://stenciljs.com/docs/v4.34/custom-elements#dir) `index.js` file. ### includeGlobalScripts[](https://stenciljs.com/docs/v4.34/custom-elements#includeglobalscripts "Direct link to includeGlobalScripts") _default: `false`_ Setting this flag to `true` will include [global scripts](https://stenciljs.com/docs/v4.34/config#globalscript) in the bundle and execute them once the bundle entry point in loaded. ### isPrimaryPackageOutputTarget[](https://stenciljs.com/docs/v4.34/custom-elements#isprimarypackageoutputtarget "Direct link to isPrimaryPackageOutputTarget") _default: `false`_ If `true`, this output target will be used to validate `package.json` fields for your project's distribution. See the overview of [primary package output target validation](https://stenciljs.com/docs/v4.34/output-targets#primary-package-output-target-validation) for more information. ### minify[](https://stenciljs.com/docs/v4.34/custom-elements#minify "Direct link to minify") _default: `false`_ Setting this flag to `true` will cause file minification to follow what is specified in the [Stencil config](https://stenciljs.com/docs/v4.34/config#minifyjs) . _However_, if [`externalRuntime`](https://stenciljs.com/docs/v4.34/custom-elements#externalruntime) is enabled, it will override this option and always result in minification being disabled. Making Assets Available[](https://stenciljs.com/docs/v4.34/custom-elements#making-assets-available "Direct link to Making Assets Available") ---------------------------------------------------------------------------------------------------------------------------------------------- For performance reasons, the generated bundle does not include [local assets](https://stenciljs.com/docs/v4.34/assets) built within the JavaScript output, but instead it's recommended to keep static assets as external files. By keeping them external this ensures they can be requested on-demand, rather than either welding their content into the JS file, or adding many URLs for the bundler to add to the output. One method to ensure [assets](https://stenciljs.com/docs/v4.34/assets) are available to external builds and http servers is to set the asset path using `setAssetPath()`. The `setAssetPath()` function is used to manually set the base path where static assets can be found. For the lazy-loaded output target the asset path is automatically set and assets copied to the correct build directory. However, for custom elements builds, the `setAssetPath(path)` should be used to customize the asset path depending on where they are found on the http server. If the component's script is a `type="module"`, it's recommended to use `import.meta.url`, such as `setAssetPath(import.meta.url)`. Other options include `setAssetPath(document.currentScript.src)`, or using a bundler's replace plugin to dynamically set the path at build time, such as `setAssetPath(process.env.ASSET_PATH)`. import { setAssetPath } from 'my-library/dist/components';setAssetPath(document.currentScript.src); 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 bundling, and where your assets can be loaded from. How the files are copied to the production build directory depends on the bundler or tooling. The configs below provide examples of how to do this automatically with popular bundlers. Example Bundler Configs[](https://stenciljs.com/docs/v4.34/custom-elements#example-bundler-configs "Direct link to Example Bundler Configs") ---------------------------------------------------------------------------------------------------------------------------------------------- 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. The following examples assume your component library is published to NPM as `my-library`. You should change this to the name you actually publish your library with. Users will need to install your library before importing them. * npm * Yarn * pnpm npm install my-library yarn add my-library pnpm add my-library ### webpack.config.js[](https://stenciljs.com/docs/v4.34/custom-elements#webpackconfigjs "Direct link to webpack.config.js") A webpack config will look something like the one below. Note how assets are copied from the library's `node_module` folder to `dist/assets` via the `CopyPlugin` utility. This is important if your library includes [local assets](https://stenciljs.com/docs/v4.34/assets) . const path = require('path');const CopyPlugin = require('copy-webpack-plugin');module.exports = { entry: './src/index.js', output: { filename: 'main.js', path: path.resolve(__dirname, 'dist'), }, module: { rules: [ { test: /\.css$/i, use: ['style-loader', 'css-loader'], }, ], }, plugins: [ new CopyPlugin({ patterns: [ { from: path.resolve(__dirname, 'node_modules/my-library/dist/my-library/assets'), to: path.resolve(__dirname, 'dist/assets'), }, ], }), ],}; ### rollup.config.js[](https://stenciljs.com/docs/v4.34/custom-elements#rollupconfigjs "Direct link to rollup.config.js") A Rollup config will look something like the one below. Note how assets are copied from the library's `node_module` folder to `dist/assets` via the `rollup-copy-plugin` utility. This is important if your library includes [local assets](https://stenciljs.com/docs/v4.34/assets) . import path from 'path';import commonjs from '@rollup/plugin-commonjs';import copy from 'rollup-plugin-copy';import postcss from 'rollup-plugin-postcss';import resolve from '@rollup/plugin-node-resolve';export default { input: 'src/index.js', output: [{ dir: path.resolve('dist/'), format: 'es' }], plugins: [ resolve(), commonjs(), postcss({ extensions: ['.css'], }), copy({ targets: [ { src: path.resolve(__dirname, 'node_modules/my-library/dist/my-library/assets'), dest: path.resolve(__dirname, 'dist'), }, ], }), ],}; Contents -------- * [Config](https://stenciljs.com/docs/v4.34/custom-elements#config) * [copy](https://stenciljs.com/docs/v4.34/custom-elements#copy) * [customElementsExportBehavior](https://stenciljs.com/docs/v4.34/custom-elements#customelementsexportbehavior) * [dir](https://stenciljs.com/docs/v4.34/custom-elements#dir) * [empty](https://stenciljs.com/docs/v4.34/custom-elements#empty) * [externalRuntime](https://stenciljs.com/docs/v4.34/custom-elements#externalruntime) * [generateTypeDeclarations](https://stenciljs.com/docs/v4.34/custom-elements#generatetypedeclarations) * [includeGlobalScripts](https://stenciljs.com/docs/v4.34/custom-elements#includeglobalscripts) * [isPrimaryPackageOutputTarget](https://stenciljs.com/docs/v4.34/custom-elements#isprimarypackageoutputtarget) * [minify](https://stenciljs.com/docs/v4.34/custom-elements#minify) * [Making Assets Available](https://stenciljs.com/docs/v4.34/custom-elements#making-assets-available) * [Example Bundler Configs](https://stenciljs.com/docs/v4.34/custom-elements#example-bundler-configs) * [webpack.config.js](https://stenciljs.com/docs/v4.34/custom-elements#webpackconfigjs) * [rollup.config.js](https://stenciljs.com/docs/v4.34/custom-elements#rollupconfigjs) * * * [Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.34/output-targets/custom-elements.md) --- # Custom Elements with Stencil | Stencil [Skip to main content](https://stenciljs.com/docs/custom-elements#__docusaurus_skipToContent_fallback) [An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none) Version: v4.35 On this page The `dist-custom-elements` output target creates custom elements that directly extend `HTMLElement` and provides simple utility functions for easily defining these elements on the [Custom Element Registry](https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry) . This output target excels in use in frontend frameworks and projects that will handle bundling, lazy-loading, and custom element registration themselves. 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 [dist output target](https://stenciljs.com/docs/distribution) . To generate components using the `dist-custom-elements` output target, add it to a project's `stencil.config.ts` file like so: stencil.config.ts import { Config } from '@stencil/core';export const config: Config = { // Other top-level config options here outputTargets: [ { type: 'dist-custom-elements', // Output target config options here }, // Other output targets here ],}; Config[](https://stenciljs.com/docs/custom-elements#config "Direct link to Config") ------------------------------------------------------------------------------------- ### copy[](https://stenciljs.com/docs/custom-elements#copy "Direct link to copy") _default: `undefined`_ An array of [copy tasks](https://stenciljs.com/docs/copy-tasks) to be executed during the build process. ### customElementsExportBehavior[](https://stenciljs.com/docs/custom-elements#customelementsexportbehavior "Direct link to customElementsExportBehavior") _default: `'default'`_ By default, the `dist-custom-elements` output target generates a single file per component, and exports each of those files individually. 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. 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.tsimport { 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. This file can be used as the root module when distributing your component library, see [Publishing](https://stenciljs.com/docs/publishing)
for more details. | note At this time, components that do not use JSX cannot be automatically defined. This is a known limitation of Stencil that users should be aware of. ### dir[](https://stenciljs.com/docs/custom-elements#dir "Direct link to dir") _default: `'dist/components'`_ This config option allows you to change the output directory where the compiled output for this output target will be written. ### empty[](https://stenciljs.com/docs/custom-elements#empty "Direct link to empty") _default: `true`_ Setting this flag to `true` will remove the contents of the [output directory](https://stenciljs.com/docs/custom-elements#dir) between builds. ### externalRuntime[](https://stenciljs.com/docs/custom-elements#externalruntime "Direct link to externalRuntime") _default: `true`_ Setting this flag to `true` results in the following behaviors: 1. Minification will follow what is specified in the [Stencil config](https://stenciljs.com/docs/config#minifyjs) . 2. Filenames will not be hashed. 3. All imports from packages under `@stencil/core/*` will be marked as external and therefore not included in the generated Rollup bundle. Ensure that `@stencil/core` is included in your list of dependencies if you set this option to `true`. This is crucial to prevent any runtime errors. ### generateTypeDeclarations[](https://stenciljs.com/docs/custom-elements#generatetypedeclarations "Direct link to generateTypeDeclarations") _default: `true`_ By default, Stencil will generate type declaration files (`.d.ts` files) as a part of the `dist-custom-elements` output target through the `generateTypeDeclarations` field on the target options. Type declaration files will be placed in the `dist/types` directory in the root of a Stencil project. At this time, this output destination is not able to be configured. Setting this flag to `false` will not generate type declaration files for the `dist-custom-elements` output target. note When set to generate type declarations, Stencil respects the export behavior selected via `customElementsExportBehavior` and generates type declarations specific to the content of the generated [output directory's](https://stenciljs.com/docs/custom-elements#dir) `index.js` file. ### includeGlobalScripts[](https://stenciljs.com/docs/custom-elements#includeglobalscripts "Direct link to includeGlobalScripts") _default: `false`_ Setting this flag to `true` will include [global scripts](https://stenciljs.com/docs/config#globalscript) in the bundle and execute them once the bundle entry point in loaded. ### isPrimaryPackageOutputTarget[](https://stenciljs.com/docs/custom-elements#isprimarypackageoutputtarget "Direct link to isPrimaryPackageOutputTarget") _default: `false`_ If `true`, this output target will be used to validate `package.json` fields for your project's distribution. See the overview of [primary package output target validation](https://stenciljs.com/docs/output-targets#primary-package-output-target-validation) for more information. ### minify[](https://stenciljs.com/docs/custom-elements#minify "Direct link to minify") _default: `false`_ Setting this flag to `true` will cause file minification to follow what is specified in the [Stencil config](https://stenciljs.com/docs/config#minifyjs) . _However_, if [`externalRuntime`](https://stenciljs.com/docs/custom-elements#externalruntime) is enabled, it will override this option and always result in minification being disabled. Making Assets Available[](https://stenciljs.com/docs/custom-elements#making-assets-available "Direct link to Making Assets Available") ---------------------------------------------------------------------------------------------------------------------------------------- For performance reasons, the generated bundle does not include [local assets](https://stenciljs.com/docs/assets) built within the JavaScript output, but instead it's recommended to keep static assets as external files. By keeping them external this ensures they can be requested on-demand, rather than either welding their content into the JS file, or adding many URLs for the bundler to add to the output. One method to ensure [assets](https://stenciljs.com/docs/assets) are available to external builds and http servers is to set the asset path using `setAssetPath()`. The `setAssetPath()` function is used to manually set the base path where static assets can be found. For the lazy-loaded output target the asset path is automatically set and assets copied to the correct build directory. However, for custom elements builds, the `setAssetPath(path)` should be used to customize the asset path depending on where they are found on the http server. If the component's script is a `type="module"`, it's recommended to use `import.meta.url`, such as `setAssetPath(import.meta.url)`. Other options include `setAssetPath(document.currentScript.src)`, or using a bundler's replace plugin to dynamically set the path at build time, such as `setAssetPath(process.env.ASSET_PATH)`. import { setAssetPath } from 'my-library/dist/components';setAssetPath(document.currentScript.src); 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 bundling, and where your assets can be loaded from. How the files are copied to the production build directory depends on the bundler or tooling. The configs below provide examples of how to do this automatically with popular bundlers. Example Bundler Configs[](https://stenciljs.com/docs/custom-elements#example-bundler-configs "Direct link to Example Bundler Configs") ---------------------------------------------------------------------------------------------------------------------------------------- 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. The following examples assume your component library is published to NPM as `my-library`. You should change this to the name you actually publish your library with. Users will need to install your library before importing them. * npm * Yarn * pnpm npm install my-library yarn add my-library pnpm add my-library ### webpack.config.js[](https://stenciljs.com/docs/custom-elements#webpackconfigjs "Direct link to webpack.config.js") A webpack config will look something like the one below. Note how assets are copied from the library's `node_module` folder to `dist/assets` via the `CopyPlugin` utility. This is important if your library includes [local assets](https://stenciljs.com/docs/assets) . const path = require('path');const CopyPlugin = require('copy-webpack-plugin');module.exports = { entry: './src/index.js', output: { filename: 'main.js', path: path.resolve(__dirname, 'dist'), }, module: { rules: [ { test: /\.css$/i, use: ['style-loader', 'css-loader'], }, ], }, plugins: [ new CopyPlugin({ patterns: [ { from: path.resolve(__dirname, 'node_modules/my-library/dist/my-library/assets'), to: path.resolve(__dirname, 'dist/assets'), }, ], }), ],}; ### rollup.config.js[](https://stenciljs.com/docs/custom-elements#rollupconfigjs "Direct link to rollup.config.js") A Rollup config will look something like the one below. Note how assets are copied from the library's `node_module` folder to `dist/assets` via the `rollup-copy-plugin` utility. This is important if your library includes [local assets](https://stenciljs.com/docs/assets) . import path from 'path';import commonjs from '@rollup/plugin-commonjs';import copy from 'rollup-plugin-copy';import postcss from 'rollup-plugin-postcss';import resolve from '@rollup/plugin-node-resolve';export default { input: 'src/index.js', output: [{ dir: path.resolve('dist/'), format: 'es' }], plugins: [ resolve(), commonjs(), postcss({ extensions: ['.css'], }), copy({ targets: [ { src: path.resolve(__dirname, 'node_modules/my-library/dist/my-library/assets'), dest: path.resolve(__dirname, 'dist'), }, ], }), ],}; Contents -------- * [Config](https://stenciljs.com/docs/custom-elements#config) * [copy](https://stenciljs.com/docs/custom-elements#copy) * [customElementsExportBehavior](https://stenciljs.com/docs/custom-elements#customelementsexportbehavior) * [dir](https://stenciljs.com/docs/custom-elements#dir) * [empty](https://stenciljs.com/docs/custom-elements#empty) * [externalRuntime](https://stenciljs.com/docs/custom-elements#externalruntime) * [generateTypeDeclarations](https://stenciljs.com/docs/custom-elements#generatetypedeclarations) * [includeGlobalScripts](https://stenciljs.com/docs/custom-elements#includeglobalscripts) * [isPrimaryPackageOutputTarget](https://stenciljs.com/docs/custom-elements#isprimarypackageoutputtarget) * [minify](https://stenciljs.com/docs/custom-elements#minify) * [Making Assets Available](https://stenciljs.com/docs/custom-elements#making-assets-available) * [Example Bundler Configs](https://stenciljs.com/docs/custom-elements#example-bundler-configs) * [webpack.config.js](https://stenciljs.com/docs/custom-elements#webpackconfigjs) * [rollup.config.js](https://stenciljs.com/docs/custom-elements#rollupconfigjs) * * * [Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.35/output-targets/custom-elements.md) --- # Publishing A Component Library | Stencil [Skip to main content](https://stenciljs.com/docs/publishing#__docusaurus_skipToContent_fallback) [An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none) Version: v4.35 On this page There are numerous strategies to publish and distribute your component library to be consumed by external projects. One of the benefits of Stencil is that is makes it easy to generate the various [output targets](https://stenciljs.com/docs/output-targets) that are right for your use-case. Use Cases[](https://stenciljs.com/docs/publishing#use-cases "Direct link to Use Cases") ----------------------------------------------------------------------------------------- To use your Stencil components in other projects, there are two different output targets to consider: [`dist`](https://stenciljs.com/docs/distribution) and [`dist-custom-elements`](https://stenciljs.com/docs/custom-elements) . Both export your components for different use cases. Luckily, both can be generated at the same time, using the same source code, and shipped in the same distribution. It would be up to the consumer of your component library to decide which build to use. ### Lazy Loading[](https://stenciljs.com/docs/publishing#lazy-loading "Direct link to Lazy Loading") If you prefer to have your components automatically loaded when used in your application, we recommend enabling the [`dist`](https://stenciljs.com/docs/distribution) output target. The bundle gives you a small entry file that registers all your components and defers loading the full component logic until it is rendered in your application. It doesn't matter if the actual application is written in HTML or created with vanilla JavaScript, jQuery, React, etc. Your users can import your component library, e.g. called `my-design-system`, either via a `script` tag: or by importing it in the bootstrap script of your application: import 'my-design-system'; To ensure that the right entry file is loaded when importing the project, define the following fields in your `package.json`: { "exports": "./dist/esm/my-design-system.js", "main": "./dist/cjs/my-design-system.js", "unpkg": "dist/my-design-system/my-design-system.esm.js",} Read more about various options when it comes to configuring your project's components for lazy loading in the [`dist`](https://stenciljs.com/docs/distribution) output target section. #### Considerations[](https://stenciljs.com/docs/publishing#considerations "Direct link to Considerations") To start, Stencil was designed to lazy-load itself only when the component was actually used on a page. There are many benefits to this approach, such as simply adding a script tag to any page and the entire library is available for use, yet only the components actually used are downloaded. For example, [`@ionic/core`](https://www.npmjs.com/package/@ionic/core) comes with over 100 components, but a webpage may only need `ion-toggle`. Instead of requesting the entire component library, or generating a custom bundle for just `ion-toggle`, the `dist` output target is able to generate a tiny entry build ready to load any of its components on-demand. However be aware that this approach is not ideal in all cases. It requires your application to ship the bundled components as static assets in order for them to load properly. Furthermore, having many nested component dependencies can have an impact on the performance of your application. For example, given you have a component `CmpA` which uses a Stencil component `CmpB` which itself uses another Stencil component `CmpC`. In order to fully render `CmpA` the browser has to load 3 scripts sequentially which can result in undesired rendering delays. ### Standalone[](https://stenciljs.com/docs/publishing#standalone "Direct link to Standalone") The [`dist-custom-elements`](https://stenciljs.com/docs/custom-elements) output target builds each component as a stand-alone class that extends `HTMLElement`. The output is a standardized custom element with the styles already attached and without any of Stencil's lazy-loading. This may be preferred for projects that are already handling bundling, lazy-loading and defining the custom elements themselves. The generated files will each export a component class and will already have the styles bundled. However, this build does not define the custom elements or apply any polyfills. Static assets referenced within components will need to be set using `setAssetPath` (see [Making Assets Available](https://stenciljs.com/docs/custom-elements#making-assets-available) ). You can use these standalone components by importing them via: import { MyComponent, defineCustomElementMyComponent } from 'my-design-system'// register to CustomElementRegistrydefineCustomElementMyComponent()// or extend custom element viaclass MyCustomComponent extends MyComponent { // ...}define('my-custom-component', MyCustomComponent) To ensure that the right entry file is loaded when importing the project, define different [exports fields](https://nodejs.org/api/packages.html#exports) in your `package.json`: { "exports": { ".": { "import": "./dist/components/index.js", "types": "./dist/components/index.d.ts" }, "./my-component": { "import": "./dist/components/my-component.js", "types": "./dist/components/my-component.d.ts" } }, "types": "dist/components/index.d.ts",} This allows us to map certain import paths to specific components within our project and allows users to only import the component code they are interested in and reduce the amount of code that needs to downloaded by the browser, e.g.: // this import loads all compiled componentsimport { MyComponent } from 'my-design-system'// only import compiled code for MyComponentimport { MyComponent } from 'my-design-system/my-component' If you define exports targets for all your components as shown above and by using [`customElementsExportBehavior: 'auto-define-custom-elements'`](https://stenciljs.com/docs/custom-elements#customelementsexportbehavior) as output target option, you can skip the `defineCustomElement` call and directly import the component where you need it: import 'my-design-system/my-component' note If you are distributing both the `dist` and `dist-custom-elements`, then it's best to pick one of them as the main entry depending on which use case is more prominent. Read more about various options when it comes to distributing your components as standalone components in the [`dist-custom-elements`](https://stenciljs.com/docs/custom-elements) output target section. The output directory will also contain an `index.js` file which exports some helper methods by default. The contents of the file will look something like: export { setAssetPath, setPlatformOptions } from '@stencil/core/internal/client'; note The contents may look different if [`customElementsExportBehavior`](https://stenciljs.com/docs/custom-elements#customelementsexportbehavior) is specified! #### Considerations[](https://stenciljs.com/docs/publishing#considerations-1 "Direct link to Considerations") The `dist-custom-elements` is a direct build of the custom element that extends `HTMLElement`, without any lazy-loading. This distribution strategy may be preferred for projects that use an external bundler such as [Vite](https://vitejs.dev/) , [WebPack](https://webpack.js.org/) or [Rollup](https://rollupjs.org/) to compile the application. They ensure that only the components used within your application are bundled into compilation. #### Usage in TypeScript[](https://stenciljs.com/docs/publishing#usage-in-typescript "Direct link to Usage in TypeScript") If you plan to support consuming your component library in TypeScript you'll need to set `generateTypeDeclarations: true` on the output target in your `stencil.config.ts`, like so: stencil.config.ts import { Config } from '@stencil/core';export const config: Config = { outputTargets: [ { type: 'dist-custom-elements', generateTypeDeclarations: true, }, // ... ], // ...}; Then you can set the `types` property in `package.json` so that consumers of your package can find the type definitions, like so: package.json { "types": "dist/components/index.d.ts", "dependencies": { "@stencil/core": "latest" }, ...} note If you set the `dir` property on the output target config, replace `dist/components` in the above snippet with the path set in the config. Publishing to NPM[](https://stenciljs.com/docs/publishing#publishing-to-npm "Direct link to Publishing to NPM") ----------------------------------------------------------------------------------------------------------------- [NPM](https://www.npmjs.com/) is an online software registry for sharing libraries, tools, utilities, packages, etc. To make your Stencil project widely available to be consumed, it's recommended to [publish the component library to NPM](https://docs.npmjs.com/getting-started/publishing-npm-packages) . Once the library is published to NPM, other projects are able to add your component library as a dependency and use the components within their own projects. Contents -------- * [Use Cases](https://stenciljs.com/docs/publishing#use-cases) * [Lazy Loading](https://stenciljs.com/docs/publishing#lazy-loading) * [Standalone](https://stenciljs.com/docs/publishing#standalone) * [Publishing to NPM](https://stenciljs.com/docs/publishing#publishing-to-npm) * * * [Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.35/guides/publishing.md) --- # Component API | Stencil [Skip to main content](https://stenciljs.com/docs/api#__docusaurus_skipToContent_fallback) [An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none) Version: v4.35 On this page The whole API provided by stencil can be condensed in a set of decorators, lifecycles hooks and rendering methods. Decorators[](https://stenciljs.com/docs/api#decorators "Direct link to Decorators") ------------------------------------------------------------------------------------- Decorators are a pure compiler-time construction used by stencil to collect all the metadata about a component, the properties, attributes and methods it might expose, the events it might emit or even the associated stylesheets. Once all the metadata has been collected, all the decorators are removed from the output, so they don't incur any runtime overhead. * [@Component()](https://stenciljs.com/docs/component) declares a new web component * [@Prop()](https://stenciljs.com/docs/properties#the-prop-decorator-prop) declares an exposed property/attribute * [@State()](https://stenciljs.com/docs/state#the-state-decorator-state) declares an internal state of the component * [@Watch()](https://stenciljs.com/docs/reactive-data#the-watch-decorator-watch) declares a hook that runs when a property or state changes * [@Element()](https://stenciljs.com/docs/host-element#element-decorator) declares a reference to the host element * [@Method()](https://stenciljs.com/docs/methods) declares an exposed public method * [@Event()](https://stenciljs.com/docs/events#event-decorator) declares a DOM event the component might emit * [@Listen()](https://stenciljs.com/docs/events#listen-decorator) listens for DOM events Lifecycle hooks[](https://stenciljs.com/docs/api#lifecycle-hooks "Direct link to Lifecycle hooks") ---------------------------------------------------------------------------------------------------- * [connectedCallback()](https://stenciljs.com/docs/component-lifecycle#connectedcallback) * [disconnectedCallback()](https://stenciljs.com/docs/component-lifecycle#disconnectedcallback) * [componentWillLoad()](https://stenciljs.com/docs/component-lifecycle#componentwillload) * [componentDidLoad()](https://stenciljs.com/docs/component-lifecycle#componentdidload) * [componentShouldUpdate(newValue, oldValue, propName): boolean](https://stenciljs.com/docs/component-lifecycle#componentshouldupdate) * [componentWillRender()](https://stenciljs.com/docs/component-lifecycle#componentwillrender) * [componentDidRender()](https://stenciljs.com/docs/component-lifecycle#componentdidrender) * [componentWillUpdate()](https://stenciljs.com/docs/component-lifecycle#componentwillupdate) * [componentDidUpdate()](https://stenciljs.com/docs/component-lifecycle#componentdidupdate) * **[render()](https://stenciljs.com/docs/templating-jsx) ** componentOnReady()[](https://stenciljs.com/docs/api#componentonready "Direct link to componentOnReady()") ----------------------------------------------------------------------------------------------------------- This isn't a true "lifecycle" method that would be declared on the component class definition, but instead is a utility method that can be used by an implementation consuming your Stencil component to detect when a component has finished its first render cycle. This method returns a promise which resolves after `componentDidRender()` on the _first_ render cycle. note `componentOnReady()` only resolves once per component lifetime. If you need to hook into subsequent render cycle, use `componentDidRender()` or `componentDidUpdate()`. Executing code after `componentOnReady()` resolves could look something like this: // Get a reference to the elementconst el = document.querySelector('my-component');el.componentOnReady().then(() => { // Place any code in here you want to execute when the component is ready console.log('my-component is ready');}); The availability of `componentOnReady()` depends on the component's compiled output type. This method is only available for lazy-loaded distribution types ([`dist`](https://stenciljs.com/docs/distribution) and [`www`](https://stenciljs.com/docs/www) ) and, as such, is not available for [`dist-custom-elements`](https://stenciljs.com/docs/custom-elements) output. If you want to simulate the behavior of `componentOnReady()` for non-lazy builds, you can implement a helper method to wrap the functionality similar to what the Ionic Framework does [here](https://github.com/ionic-team/ionic-framework/blob/main/core/src/utils/helpers.ts#L60-L79) . The `appload` event[](https://stenciljs.com/docs/api#the-appload-event "Direct link to the-appload-event") ------------------------------------------------------------------------------------------------------------ In addition to component-specific lifecycle hooks, a special event called `appload` will be emitted when the app and all of its child components have finished loading. You can listen for it on the `window` object. If you have multiple apps on the same page, you can determine which app emitted the event by checking `event.detail.namespace`. This will be the value of the [namespace config option](https://stenciljs.com/docs/config#namespace) you've set in your Stencil config. window.addEventListener('appload', (event) => { console.log(event.detail.namespace);}); Other[](https://stenciljs.com/docs/api#other "Direct link to Other") ---------------------------------------------------------------------- The following primitives can be imported from the `@stencil/core` package and used within the lifecycle of a component: * [**Host**](https://stenciljs.com/docs/host-element) : ``, is a functional component that can be used at the root of the render function to set attributes and event listeners to the host element itself. Refer to the [Host Element](https://stenciljs.com/docs/host-element)
page for usage info.
* **Fragment**: ``, often used via `<>...` syntax, lets you group elements without a wrapper node.
To use this feature, ensure that the following TypeScript compiler options are set:
* [`jsxFragmentFactory` is set](https://www.typescriptlang.org/tsconfig#jsxFragmentFactory)
to "Fragment"
* [`jsxFactory` is set](https://www.typescriptlang.org/tsconfig#jsxFactory)
to "h"
**Type:** `FunctionalComponent`
**Example:**
import { Component, Fragment, h } from '@stencil/core'@Component({ tag: 'cmp-fragment',})export class CmpFragment { render() { return ( <> ); }}
* **setAssetPath()**: Sets the path for Stencil to resolve local assets. Refer to the [Assets](https://stenciljs.com/docs/assets#setassetpath)
page for usage info.
**Type:** `(path: string) => string`
**Example:**
import { setAssetPath } from '@stencil/core';setAssetPath(`{window.location.origin}/`);
* **setMode()**: Sets the style mode of a component. Refer to the [Styling](https://stenciljs.com/docs/styling#style-modes)
page for usage info.
**Type:** `((elm: HTMLElement) => string | undefined | null) => void`
**Example:**
import { setMode } from '@stencil/core'// set mode based on a propertysetMode((el) => el.getAttribute('mode'));
* **getMode()**: Get the current style mode of your application. Refer to the [Styling](https://stenciljs.com/docs/styling#style-modes)
page for usage info.
**Type:** `(ref: any) => string | undefined`
**Example:**
import { getMode } from '@stencil/core'getMode(this);
* **getElement()**: Retrieve a Stencil element for a given reference.
**Type:** `(ref: any) => HTMLStencilElement`
**Example:**
import { getElement } from '@stencil/core'const stencilComponent = getElement(document.querySelector('my-cmp'))if (stencilComponent) { stencilComponent.componentOnReady().then(() => { ... })}
Contents
--------
* [Decorators](https://stenciljs.com/docs/api#decorators)
* [Lifecycle hooks](https://stenciljs.com/docs/api#lifecycle-hooks)
* [componentOnReady()](https://stenciljs.com/docs/api#componentonready)
* [The `appload` event](https://stenciljs.com/docs/api#the-appload-event)
* [Other](https://stenciljs.com/docs/api#other)
* * *
[Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.35/components/api.md)
---
# Component Lifecycle Methods | Stencil
[Skip to main content](https://stenciljs.com/docs/component-lifecycle#__docusaurus_skipToContent_fallback)
[An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none)
Version: v4.35
On this page
Components have numerous lifecycle methods which can be used to know when the component "will" and "did" load, update, and render. These methods can be added to a component to hook into operations at the right time.
Implement one of the following methods within a component class and Stencil will automatically call them in the right order:
componentDidLoad()componentDidUpdate()disconnectedCallback()@Watch(‘propName’)render()connectedCallback()componentShouldUpdate()componentWillRender()componentWillUpdate()componentDidRender()componentWillLoad()Component initializedChange in a value of prop or state triggers rerenderComponent removedComponent reattached
connectedCallback()[](https://stenciljs.com/docs/component-lifecycle#connectedcallback "Direct link to connectedCallback()")
------------------------------------------------------------------------------------------------------------------------------
Called every time the component is connected to the DOM. When the component is first connected, this method is called before `componentWillLoad`.
It's important to note that this method can be called more than once, every time, the element is **attached** or **moved** in the DOM. For logic that needs to run every time the element is attached or moved in the DOM, it is considered a best practice to use this lifecycle method.
const el = document.createElement('my-cmp');document.body.appendChild(el);// connectedCallback() called// componentWillLoad() called (first time)el.remove();// disconnectedCallback()document.body.appendChild(el);// connectedCallback() called again, but `componentWillLoad()` is not.
This `lifecycle` hook follows the same semantics as the one described by the [Custom Elements Spec](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements)
disconnectedCallback()[](https://stenciljs.com/docs/component-lifecycle#disconnectedcallback "Direct link to disconnectedCallback()")
---------------------------------------------------------------------------------------------------------------------------------------
Called every time the component is disconnected from the DOM, ie, it can be dispatched more than once, DO not confuse with a "onDestroy" kind of event.
This `lifecycle` hook follows the same semantics as the one described by the [Custom Elements Spec](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements)
.
componentWillLoad()[](https://stenciljs.com/docs/component-lifecycle#componentwillload "Direct link to componentWillLoad()")
------------------------------------------------------------------------------------------------------------------------------
Called once just after the component is first connected to the DOM. Since this method is only called once, it's a good place to load data asynchronously and to setup the state without triggering extra re-renders.
A promise can be returned, that can be used to wait for the first `render()`.
componentDidLoad()[](https://stenciljs.com/docs/component-lifecycle#componentdidload "Direct link to componentDidLoad()")
---------------------------------------------------------------------------------------------------------------------------
Called once just after the component is fully loaded and the first `render()` occurs.
componentShouldUpdate()[](https://stenciljs.com/docs/component-lifecycle#componentshouldupdate "Direct link to componentShouldUpdate()")
------------------------------------------------------------------------------------------------------------------------------------------
This hook is called when a component's [`Prop`](https://stenciljs.com/docs/properties)
or [`State`](https://stenciljs.com/docs/state)
property changes and a rerender is about to be requested. This hook receives three arguments: the new value, the old value and the name of the changed state. It should return a boolean to indicate if the component should rerender (`true`) or not (`false`).
A couple of things to notice is that this method will not be executed before the initial render, that is, when the component is first attached to the dom, nor when a rerender is already scheduled in the next frame.
Let’s say the following two props of a component change synchronously:
component.somePropA = 42;component.somePropB = 88;
The `componentShouldUpdate` will be first called with arguments: `42`, `undefined` and `somePropA`. If it does return `true`, the hook will not be called again since the rerender is already scheduled to happen. Instead, if the first hook returned `false`, then `componentShouldUpdate` will be called again with `88`, `undefined` and `somePropB` as arguments, triggered by the `component.somePropB = 88` mutation.
Since the execution of this hook might be conditioned, it's not good to rely on it to watch for prop changes, instead use the `@Watch` decorator for that.
componentWillRender()[](https://stenciljs.com/docs/component-lifecycle#componentwillrender "Direct link to componentWillRender()")
------------------------------------------------------------------------------------------------------------------------------------
Called before every `render()`.
A promise can be returned, that can be used to wait for the upcoming render.
componentDidRender()[](https://stenciljs.com/docs/component-lifecycle#componentdidrender "Direct link to componentDidRender()")
---------------------------------------------------------------------------------------------------------------------------------
Called after every `render()`.
componentWillUpdate()[](https://stenciljs.com/docs/component-lifecycle#componentwillupdate "Direct link to componentWillUpdate()")
------------------------------------------------------------------------------------------------------------------------------------
Called when the component is about to be updated because some `Prop()` or `State()` changed. It's never called during the first `render()`.
A promise can be returned, that can be used to wait for the next render.
componentDidUpdate()[](https://stenciljs.com/docs/component-lifecycle#componentdidupdate "Direct link to componentDidUpdate()")
---------------------------------------------------------------------------------------------------------------------------------
Called just after the component updates. It's never called during the first `render()`.
Rendering State[](https://stenciljs.com/docs/component-lifecycle#rendering-state "Direct link to Rendering State")
--------------------------------------------------------------------------------------------------------------------
It's always recommended to make any rendered state updates within `componentWillRender()`, since this is the method which get called _before_ the `render()` method. Alternatively, updating rendered state with the `componentDidLoad()`, `componentDidUpdate()` and `componentDidRender()` methods will cause another rerender, which isn't ideal for performance.
If state _must_ be updated in `componentDidUpdate()` or `componentDidRender()`, it has the potential of getting components stuck in an infinite loop. If updating state within `componentDidUpdate()` is unavoidable, then the method should also come with a way to detect if the props or state is "dirty" or not (is the data actually different or is it the same as before). By doing a dirty check, `componentDidUpdate()` is able to avoid rendering the same data, and which in turn calls `componentDidUpdate()` again.
Lifecycle Hierarchy[](https://stenciljs.com/docs/component-lifecycle#lifecycle-hierarchy "Direct link to Lifecycle Hierarchy")
--------------------------------------------------------------------------------------------------------------------------------
A useful feature of lifecycle methods is that they take their child component's lifecycle into consideration too. For example, if the parent component, `cmp-a`, has a child component, `cmp-b`, then `cmp-a` isn't considered "loaded" until `cmp-b` has finished loading. Another way to put it is that the deepest components finish loading first, then the `componentDidLoad()` calls bubble up.
It's also important to note that even though Stencil can lazy-load components, and has asynchronous rendering, the lifecycle methods are still called in the correct order. So while the top-level component could have already been loaded, all of its lifecycle methods are still called in the correct order, which means it'll wait for a child components to finish loading. The same goes for the exact opposite, where the child components may already be ready while the parent isn't.
In the example below we have a simple hierarchy of components. The numbered list shows the order of which the lifecycle methods will fire.
1. `cmp-a` - `componentWillLoad()`
2. `cmp-b` - `componentWillLoad()`
3. `cmp-c` - `componentWillLoad()`
4. `cmp-c` - `componentDidLoad()`
5. `cmp-b` - `componentDidLoad()`
6. `cmp-a` - `componentDidLoad()`
Even if some components may or may not be already loaded, the entire component hierarchy waits on its child components to finish loading and rendering.
Async Lifecycle Methods[](https://stenciljs.com/docs/component-lifecycle#async-lifecycle-methods "Direct link to Async Lifecycle Methods")
--------------------------------------------------------------------------------------------------------------------------------------------
Some lifecycle methods, e.g. `componentWillRender`, `componentWillLoad` and `componentWillUpdate`, can also return promises which allows the method to asynchronously retrieve data or perform any async tasks. A great example of this is fetching data to be rendered in a component. For example, this very site you're reading first fetches content data before rendering. But because `fetch()` is async, it's important that `componentWillLoad()` returns a `Promise` to ensure its parent component isn't considered "loaded" until all of its content has rendered.
Below is a quick example showing how `componentWillLoad()` is able to have its parent component wait on it to finish loading its data.
componentWillLoad() { return fetch('/some-data.json') .then(response => response.json()) .then(data => { this.content = data; });}
Example[](https://stenciljs.com/docs/component-lifecycle#example "Direct link to Example")
--------------------------------------------------------------------------------------------
This simple example shows a clock and updates the current time every second. The timer is started when the component is added to the DOM. Once it's removed from the DOM, the timer is stopped.
import { Component, State, h } from '@stencil/core';@Component({ tag: 'custom-clock'})export class CustomClock { timer: number; @State() time: number = Date.now(); connectedCallback() { this.timer = window.setInterval(() => { this.time = Date.now(); }, 1000); } disconnectedCallback() { window.clearInterval(this.timer); } render() { const time = new Date(this.time).toLocaleTimeString(); return ( { time } ); }}
Contents
--------
* [connectedCallback()](https://stenciljs.com/docs/component-lifecycle#connectedcallback)
* [disconnectedCallback()](https://stenciljs.com/docs/component-lifecycle#disconnectedcallback)
* [componentWillLoad()](https://stenciljs.com/docs/component-lifecycle#componentwillload)
* [componentDidLoad()](https://stenciljs.com/docs/component-lifecycle#componentdidload)
* [componentShouldUpdate()](https://stenciljs.com/docs/component-lifecycle#componentshouldupdate)
* [componentWillRender()](https://stenciljs.com/docs/component-lifecycle#componentwillrender)
* [componentDidRender()](https://stenciljs.com/docs/component-lifecycle#componentdidrender)
* [componentWillUpdate()](https://stenciljs.com/docs/component-lifecycle#componentwillupdate)
* [componentDidUpdate()](https://stenciljs.com/docs/component-lifecycle#componentdidupdate)
* [Rendering State](https://stenciljs.com/docs/component-lifecycle#rendering-state)
* [Lifecycle Hierarchy](https://stenciljs.com/docs/component-lifecycle#lifecycle-hierarchy)
* [Async Lifecycle Methods](https://stenciljs.com/docs/component-lifecycle#async-lifecycle-methods)
* [Example](https://stenciljs.com/docs/component-lifecycle#example)
* * *
[Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.35/components/component-lifecycle.md)
---
# Telemetry | Stencil
[Skip to main content](https://stenciljs.com/docs/telemetry#__docusaurus_skipToContent_fallback)
[An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none)
Version: v4.35
On this page
As of version 2.7.0, Stencil collects anonymous telemetry data about usage of our command line interface. Participation in this program is optional, and [you may opt-out](https://stenciljs.com/docs/telemetry#how-do-i-opt-out)
if you'd prefer not to share any information.
### Why Is Telemetry Collected?[](https://stenciljs.com/docs/telemetry#why-is-telemetry-collected "Direct link to Why Is Telemetry Collected?")
Ionic continues to invest in Stencil to make it the best web component compiler in the market. We spend hundreds of hours every year engaging with our community to learn how we can improve the product and create a more streamlined developer experience.
However, qualitative conversations are only half the picture. To fully understand the behavior of our users, we also need to look at quantitative data. Telemetry allows us to accurately gauge Stencil feature usage. The combination of qualitative and quantitative data helps us generate the most informed roadmap possible, ensuring Stencil’s growth for years to come.
### What Is Being Collected?[](https://stenciljs.com/docs/telemetry#what-is-being-collected "Direct link to What Is Being Collected?")
We track command line usage including commands and options. Specifically, we track the following anonymously:
* Command invoked (eg: stencil generate, stencil build, etc) with arguments
* Versions of Stencil and other dependencies like TypeScript
* Output targets
* Stencil packages
* General machine information like OS
An example telemetry event looks like this:
{ "yarn": false, "duration": 2762, "componentCount": 13, "targets": [ "www", "dist-lazy", "docs-readme", "docs-vscode" ], "packages": [ "@capacitor/cli@^3.1.1", "@capacitor/core@^3.1.1", "@stencil/core@latest", "@stencil/store@latest" ], "arguments": [ "--debug" ], "task": "build", "stencil": "2.6.0", "system": "node 16.4.2", "os_name": "darwin", "os_version": "20.5.0", "cpu_model": "Apple M1", "build": "20210714145743", "typescript": "4.2.3", "rollup": "2.42.3"}
### What about Sensitive Data (e.g. Secrets)?[](https://stenciljs.com/docs/telemetry#what-about-sensitive-data-eg-secrets "Direct link to What about Sensitive Data (e.g. Secrets)?")
We do not collect any metrics which may contain sensitive data. This includes, but is not limited to: environment variables, file paths, contents of files, logs, or serialized JavaScript errors.
### Will This Data Be Shared?[](https://stenciljs.com/docs/telemetry#will-this-data-be-shared "Direct link to Will This Data Be Shared?")
No. Data collected will not be shared outside of Ionic. The data collected is anonymous, not traceable to the source, and only meaningful in aggregate form. We take your privacy and our security very seriously. Stencil telemetry falls under the [Ionic Privacy Policy](https://ionicframework.com/privacy)
.
### How Do I Opt-Out?[](https://stenciljs.com/docs/telemetry#how-do-i-opt-out "Direct link to How Do I Opt-Out?")
You may opt-out by running the following command in the root of your project directory:
`npx stencil telemetry off`
You may check the status of telemetry collection at any time by running the command with no arguments in the root of your project directory:
`npx stencil telemetry`
You may re-enable telemetry if you'd like to re-join the program by running the following in the root of your project directory:
`npx stencil telemetry on`
Contents
--------
* [Why Is Telemetry Collected?](https://stenciljs.com/docs/telemetry#why-is-telemetry-collected)
* [What Is Being Collected?](https://stenciljs.com/docs/telemetry#what-is-being-collected)
* [What about Sensitive Data (e.g. Secrets)?](https://stenciljs.com/docs/telemetry#what-about-sensitive-data-eg-secrets)
* [Will This Data Be Shared?](https://stenciljs.com/docs/telemetry#will-this-data-be-shared)
* [How Do I Opt-Out?](https://stenciljs.com/docs/telemetry#how-do-i-opt-out)
* * *
[Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.35/telemetry.md)
---
# Component Decorator | Stencil
[Skip to main content](https://stenciljs.com/docs/component#__docusaurus_skipToContent_fallback)
[An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none)
Version: v4.35
On this page
`@Component()` is a decorator that designates a TypeScript class as a Stencil component. Every Stencil component gets transformed into a web component at build time.
import { Component } from '@stencil/core';@Component({ tag: 'todo-list', // additional options})export class TodoList { // implementation omitted}
Component Options[](https://stenciljs.com/docs/component#component-options "Direct link to Component Options")
----------------------------------------------------------------------------------------------------------------
The `@Component()` decorator takes one argument, an object literal containing configuration options for the component. This allows each component to be individually configured to suit the unique needs of each project.
Each option, its type, and whether it's required is described below.
### tag[](https://stenciljs.com/docs/component#tag "Direct link to tag")
**Required**
**Type: `string`**
**Details:**
This value sets the name of the custom element that Stencil will generate. To adhere to the [HTML spec](https://html.spec.whatwg.org/#valid-custom-element-name)
, the tag name must contain a dash ('-').
Ideally, the tag name is a globally unique value. Having a globally unique value helps prevent naming collisions with the global `CustomElementsRegistry`, where all custom elements are defined. It's recommended to choose a unique prefix for all your components within the same collection.
**Example**:
import { Component } from '@stencil/core';@Component({ tag: 'todo-list',})export class TodoList { // implementation omitted}
After compilation, the component defined in `TodoList` can be used in HTML or another TSX file:
![]()
tag const imageSrc = getAssetPath(`./assets/${this.image}`); return 
}}
In the example above, the following allows `todo-list` to display the provided asset:
1. The `TodoList`'s `@Component()` decorator has the `assetsDirs` property, and lists the file's sibling directory, `assets/`. This will copy the `assets` directory over to the distribution directory.
2. Stencil's [`getAssetPath()`](https://stenciljs.com/docs/assets#getassetpath)
is used to retrieve the path to the image to be used in the `![]()
` tag
For more information on configuring assets, please see Stencil's [Assets Guide](https://stenciljs.com/docs/assets)
### formAssociated[](https://stenciljs.com/docs/component#formassociated "Direct link to formAssociated")
**Optional**
**Type: `boolean`**
**Default: `false`**
If `true` the component will be [form-associated](https://html.spec.whatwg.org/dev/custom-elements.html#form-associated-custom-element)
, allowing you to take advantage of the [`ElementInternals`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/attachInternals)
API to enable your Stencil component to participate in forms.
A minimal form-associated Stencil component could look like this:
import { Component } from '@stencil/core';@Component({ tag: 'form-associated', formAssociated: true})export class FormAssociated { render() { return form associated! }}
See the documentation for [form-associated components](https://stenciljs.com/docs/form-associated)
for more info and examples.
### scoped[](https://stenciljs.com/docs/component#scoped "Direct link to scoped")
**Optional**
**Type: `boolean`**
**Default: `false`**
**Details:**
If `true`, the component will use [scoped stylesheets](https://stenciljs.com/docs/styling#scoped-css)
.
Scoped CSS is an alternative to using the native [shadow DOM](https://stenciljs.com/docs/styling#shadow-dom)
style encapsulation. It appends a data attribute to your styles to make them unique and thereby scope them to your component. It does not, however, prevent styles from the light DOM from seeping into your component.
To use the native [shadow DOM](https://stenciljs.com/docs/styling#shadow-dom)
, see the configuration for [`shadow`](https://stenciljs.com/docs/component#shadow)
.
This option cannot be set to `true` if `shadow` is enabled.
**Example**:
import { Component } from '@stencil/core';@Component({ tag: 'todo-list', scoped: true})export class TodoList { // implementation omitted}
### shadow[](https://stenciljs.com/docs/component#shadow "Direct link to shadow")
**Optional**
**Type: `boolean | { delegatesFocus: boolean }`**
**Default: `false`**
**Details:**
If `true`, the component will use [native Shadow DOM encapsulation](https://stenciljs.com/docs/styling#shadow-dom)
. It will fall back to `scoped` if the browser does not support shadow-dom natively.
`delegatesFocus` is a property that [provides focus](https://developer.mozilla.org/en-US/docs/Web/API/ShadowRoot/delegatesFocus)
to the first focusable entry in a component using Shadow DOM. If an object literal containing `delegatesFocus` is provided, the component will use [native Shadow DOM encapsulation](https://stenciljs.com/docs/styling#shadow-dom)
, regardless of the value assigned to `delegatesFocus`.
When `delegatesFocus` is set to `true`, the component will have `delegatesFocus: true` added to its shadow DOM.
When `delegatesFocus` is `true` and a non-focusable part of the component is clicked:
* the first focusable part of the component is given focus
* the component receives any available `focus` styling
If `shadow` is set to `false`, the component will not use native shadow DOM encapsulation.
This option cannot be set to enabled if `scoped` is enabled.
**Example 1**:
import { Component } from '@stencil/core';@Component({ tag: 'todo-list', shadow: true})export class TodoList { // implementation omitted}
**Example 2**:
import { Component } from '@stencil/core';@Component({ tag: 'todo-list', shadow: { delegatesFocus: true, }})export class TodoList { // implementation omitted}
### styleUrl[](https://stenciljs.com/docs/component#styleurl "Direct link to styleUrl")
**Optional**
**Type: `string`**
**Details:**
Relative URL to an external stylesheet containing styles to apply to your component. Out of the box, Stencil will only process CSS files (files ending with `.css`). Support for additional CSS variants, like Sass, can be added via [a plugin](https://stenciljs.com/docs/plugins#related-plugins)
.
**Example**:
Below is an example project's directory structure containing an example component and stylesheet.
src/└── components/ ├── todo-list.css └── todo-list.tsx
By setting `styleUrl`, Stencil will apply the `todo-list.css` stylesheet to the `todo-list` component:
import { Component } from '@stencil/core';@Component({ tag: 'todo-list', styleUrl: './todo-list.css',})export class TodoList { // implementation omitted}
### styleUrls[](https://stenciljs.com/docs/component#styleurls "Direct link to styleUrls")
**Optional**
**Type: `string[] | { [modeName: string]: string | string[]; }`**
**Details:**
A list of relative URLs to external stylesheets containing styles to apply to your component.
Alternatively, an object can be provided that maps a named "mode" to one or more stylesheets.
Out of the box, Stencil will only process CSS files (ending with `.css`). Support for additional CSS variants, like Sass, can be added via [a plugin](https://stenciljs.com/docs/plugins#related-plugins)
.
**Example**:
Below is an example project's directory structure containing an example component and stylesheet.
src/└── components/ ├── todo-list-1.css ├── todo-list-2.css └── todo-list.tsx
By setting `styleUrls`, Stencil will apply both stylesheets to the `todo-list` component:
Using an array of styles
import { Component } from '@stencil/core';@Component({ tag: 'todo-list', styleUrls: ['./todo-list-1.css', './todo-list-2.css']})export class TodoList { // implementation omitted}
Using modes
import { Component } from '@stencil/core';@Component({ tag: 'todo-list', styleUrls: { ios: 'todo-list-1.ios.scss', md: 'todo-list-2.md.scss', }})export class TodoList { // implementation omitted}
Read more on styling modes in the Components [Styling](https://stenciljs.com/docs/styling#style-modes)
section.
### styles[](https://stenciljs.com/docs/component#styles "Direct link to styles")
**Optional**
**Type: `string | { [modeName: string]: any }`**
**Details:**
A string that contains inlined CSS instead of using an external stylesheet. The performance characteristics of this feature are the same as using an external stylesheet.
When using `styles`, only CSS is permitted. See [`styleUrl`](https://stenciljs.com/docs/component#styleurl)
if you need more advanced features.
**Example**:
import { Component } from '@stencil/core';@Component({ tag: 'todo-list', styles: 'div { background-color: #fff }'})export class TodoList { // implementation omitted}
Embedding or Nesting Components[](https://stenciljs.com/docs/component#embedding-or-nesting-components "Direct link to Embedding or Nesting Components")
----------------------------------------------------------------------------------------------------------------------------------------------------------
Components can be composed easily by adding the HTML tag to the JSX code. Since the components are just HTML tags, nothing needs to be imported to use a Stencil component within another Stencil component.
Here's an example of using a component within another component:
import { Component, Prop, h } from '@stencil/core';@Component({ tag: 'my-embedded-component'})export class MyEmbeddedComponent { @Prop() color: string = 'blue'; render() { return ( ` example above we use the [`setFormValue`](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/setFormValue)
method to set a value in the surrounding form. This will read the `name` attribute off of the element and use it when setting the value, so the value typed by a user into the `input` will added to the form under the `"my-custom-input"` name.
This example just scratches the surface, and a great deal more is possible with the `ElementInternals` API, including [setting the element's validity](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/setValidity)
, reading the validity state of the form, reading other form values, and more.
Lifecycle Callbacks[](https://stenciljs.com/docs/form-associated#lifecycle-callbacks "Direct link to Lifecycle Callbacks")
----------------------------------------------------------------------------------------------------------------------------
Stencil allows developers building form-associated custom elements to define a [standard series of lifecycle callbacks](https://html.spec.whatwg.org/multipage/custom-elements.html#custom-element-reactions)
which enable their components to react dynamically to events in their lifecycle. These could allow fetching data when a form loads, changing styles when a form's `disabled` state is toggled, resetting form data cleanly, and more.
### `formAssociatedCallback`[](https://stenciljs.com/docs/form-associated#formassociatedcallback "Direct link to formassociatedcallback")
This callback is called when the browser both associates the element with and disassociates the element from a form element. The function is called with the form element as an argument. This could be used to set an `ariaLabel` when the form is ready to use, like so:
src/components/form-associated-cb.tsx
import { Component, h, AttachInternals } from '@stencil/core';@Component({ tag: 'form-associated', formAssociated: true,})export class FormAssociatedCmp { @AttachInternals() internals: ElementInternals; formAssociatedCallback(form) { form.ariaLabel = 'formAssociated called'; } render() { return ; }}
### `formDisabledCallback`[](https://stenciljs.com/docs/form-associated#formdisabledcallback "Direct link to formdisabledcallback")
This is called whenever the `disabled` state on the element _changes_. This could be used to keep a CSS class in sync with the disabled state, like so:
src/components/form-disabled-cb.tsx
import { Component, h, State } from '@stencil/core';@Component({ tag: 'form-disabled-cb', formAssociated: true,})export class MyComponent { @State() cssClass: string = ""; formDisabledCallback(disabled: boolean) { if (disabled) { this.cssClass = "background-mode"; } else { this.cssClass = ""; } } render() { return }}
### `formResetCallback`[](https://stenciljs.com/docs/form-associated#formresetcallback "Direct link to formresetcallback")
This is called when the form is reset, and should be used to reset the form-associated component's internal state and validation. For example, you could do something like the following:
src/components/form-reset-cb.tsx
import { Component, h, AttachInternals } from '@stencil/core';@Component({ tag: 'form-reset-cb', formAssociated: true,})export class MyComponent { @AttachInternals() internals: ElementInternals; formResetCallback() { this.internals.setValidity({}); this.internals.setFormValue(""); } render() { return }}
### `formStateRestoreCallback`[](https://stenciljs.com/docs/form-associated#formstaterestorecallback "Direct link to formstaterestorecallback")
This method will be called in the event that the browser automatically fills out your form element, an event that could take place in two different scenarios. The first is that the browser can restore the state of an element after navigating or restarting, and the second is that an input was made using a form auto-filling feature.
In either case, in order to correctly reset itself your form-associated component will need the previously selected value, but other state may also be necessary. For instance, the form value to be submitted for a date picker component would be a specific date, but in order to correctly restore the component's visual state it might also be necessary to know whether the picker should display a week or month view.
The [`setFormValue`](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/setFormValue)
method on `ElementInternals` provides some support for this use-case, allowing you to submit both a _value_ and a _state_, where the _state_ is not added to the form data sent to the server but could be used for storing some client-specific state. For instance, a pseudocode sketch of a date picker component that correctly restores whether the 'week' or 'month' view is active could look like:
src/components/fa-date-picker.tsx
import { Component, h, State, AttachInternals } from '@stencil/core';@Component({ tag: 'fa-date-picker', formAssociated: true,})export class MyDatePicker { @State() value: string = ""; @State() view: "weeks" | "months" = "weeks"; @AttachInternals() internals: ElementInternals; onInputChange(e) { e.preventDefault(); const date = e.target.value; this.setValue(date); } setValue(date: string) { // second 'state' parameter is used to store both // the input value (`date`) _and_ the current view this.internals.setFormValue(date, `${date}#${this.view}`); } formStateRestoreCallback(state, _mode) { const [date, view] = state.split("#"); this.view = view; this.setValue(date); } render() { return
. | | Contents -------- * [Config](https://stenciljs.com/docs/www#config) * * * [Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.35/output-targets/www.md) --- # Working with host elements | Stencil [Skip to main content](https://stenciljs.com/docs/host-element#__docusaurus_skipToContent_fallback) [An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none) Version: v4.35 On this page Stencil components render their children declaratively in their `render` method [using JSX](https://stenciljs.com/docs/templating-jsx) . Most of the time, the `render()` function describes the children elements that are about to be rendered, but it can also be used to render attributes of the host element itself. ``[](https://stenciljs.com/docs/host-element#host "Direct link to host")
--------------------------------------------------------------------------------
The `Host` functional component can be used at the root of the render function to set attributes and event listeners to the host element itself. This works just like any other JSX:
// Host is imported from '@stencil/core'import { Component, Host, h } from '@stencil/core';@Component({tag: 'todo-list'})export class TodoList { @Prop() open = false; render() { return ( ` is a virtual component, a virtual API exposed by stencil to declaratively set the attributes of the host element, it will never be rendered in the DOM, i.e. you will never see `` in Chrome Dev Tools for instance.
### `` can work as a ``[](https://stenciljs.com/docs/host-element#host-can-work-as-a-fragment "Direct link to host-can-work-as-a-fragment")
`` can also be used when more than one component needs to be rendered at the root level for example:
It could be achieved by a `render()` method like this:
@Component({tag: 'my-cmp'})export class MyCmp { render() { return ( ); }}
This JSX would render the following HTML:
Even if we don't use `` to render any attribute in the host element, it's a useful API to render many elements at the root level.
Element Decorator[](https://stenciljs.com/docs/host-element#element-decorator "Direct link to Element Decorator")
-------------------------------------------------------------------------------------------------------------------
The `@Element()` decorator is how to get access to the host element within the class instance. This returns an instance of an `HTMLElement`, so standard DOM methods/events can be used here.
import { Element } from '@stencil/core';...export class TodoList { @Element() el: HTMLElement; getListHeight(): number { return this.el.getBoundingClientRect().height; }}
In order to reference the host element when initializing a class member you'll need to use TypeScript's definite assignment assertion modifier to avoid a type error:
import { Element } from '@stencil/core';...export class TodoList { @Element() el!: HTMLElement; private listHeight = this.el.getBoundingClientRect().height;}
If you need to update the host element in response to prop or state changes, you should do so in the `render()` method using the `` element.
Styling[](https://stenciljs.com/docs/host-element#styling "Direct link to Styling")
-------------------------------------------------------------------------------------
See full information about styling on the [Styling page](https://stenciljs.com/docs/styling#shadow-dom-in-stencil)
.
CSS can be applied to the `` element by using its component tag defined in the `@Component` decorator.
@Component({ tag: 'my-cmp', styleUrl: 'my-cmp.css'})...
my-cmp.css:
my-cmp { width: 100px;}
### Shadow DOM[](https://stenciljs.com/docs/host-element#shadow-dom "Direct link to Shadow DOM")
Something to beware of is that Styling the `` element when using shadow DOM does not work quite the same. Instead of using the `my-cmp` element selector you must use `:host`.
@Component({ tag: 'my-cmp', styleUrl: 'my-cmp.css', shadow: true})...
my-cmp.css:
:host { width: 100px;}
Contents
--------
* [``](https://stenciljs.com/docs/host-element#host)
* [`` can work as a ``](https://stenciljs.com/docs/host-element#host-can-work-as-a-fragment)
* [Element Decorator](https://stenciljs.com/docs/host-element#element-decorator)
* [Styling](https://stenciljs.com/docs/host-element#styling)
* [Shadow DOM](https://stenciljs.com/docs/host-element#shadow-dom)
* * *
[Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.35/components/host-element.md)
---
# Functional Components | Stencil
[Skip to main content](https://stenciljs.com/docs/functional-components#__docusaurus_skipToContent_fallback)
[An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none)
Version: v4.35
On this page
Functional components are quite different to normal Stencil web components because they are a part of Stencil's JSX compiler. A functional component is basically a function that takes an object of props and turns it into JSX.
const Hello = props =>
Stencil provides a `FunctionalComponent` generic type that allows to specify an interface for the component's properties.
// Hello.tsximport { FunctionalComponent, h } from '@stencil/core';interface HelloProps { name: string;}export const Hello: FunctionalComponent = ({ name }) => ( {this.thingToDo} ; }}
note
Children components should not know about or reference their parent components. This allows Stencil to efficiently re-render your components. Passing a reference to a component as a prop may cause unintended side effects.
Mutability[](https://stenciljs.com/docs/properties#mutability "Direct link to Mutability")
--------------------------------------------------------------------------------------------
A Prop is by default immutable from inside the component logic. Once a value is set by a user, the component cannot update it internally. For more advanced control over the mutability of a prop, please see the [mutable option](https://stenciljs.com/docs/properties#prop-mutability-mutable)
section of this document.
Types[](https://stenciljs.com/docs/properties#types "Direct link to Types")
-----------------------------------------------------------------------------
Props can be a `boolean`, `number`, `string`, or even an `Object` or `Array`. The example below expands the `todo-list-item` to add a few more props with different types.
import { Component, Prop, h } from '@stencil/core';// `MyHttpService` is an `Object` in this exampleimport { MyHttpService } from '../some/local/directory/MyHttpService';@Component({ tag: 'todo-list-item',})export class ToDoListItem { @Prop() isComplete: boolean; @Prop() timesCompletedInPast: number; @Prop() thingToDo: string; @Prop() myHttpService: MyHttpService;}
### Boolean Props[](https://stenciljs.com/docs/properties#boolean-props "Direct link to Boolean Props")
A property on a Stencil component that has a type of `boolean` may be declared as:
import { Component, Prop, h } from '@stencil/core';@Component({ tag: 'todo-list-item',})export class ToDoListItem { @Prop() isComplete: boolean;}
To use this version of `todo-list-item` in HTML, we pass the string `"true"`/`"false"` to the component:
`) in-order to 'hit' the set() method, Stencil can only do so _after_ lazily fetching / loading the class component. This means one initial render / tick before being able to set the incoming, initial value.
This limitation does not exist on the [custom-elements output-target](https://stenciljs.com/docs/custom-elements)
.
Contents
--------
* [The Prop Decorator (`@Prop()`)](https://stenciljs.com/docs/properties#the-prop-decorator-prop)
* [Variable Casing](https://stenciljs.com/docs/properties#variable-casing)
* [Data Flow](https://stenciljs.com/docs/properties#data-flow)
* [Mutability](https://stenciljs.com/docs/properties#mutability)
* [Types](https://stenciljs.com/docs/properties#types)
* [Boolean Props](https://stenciljs.com/docs/properties#boolean-props)
* [Number Props](https://stenciljs.com/docs/properties#number-props)
* [String Props](https://stenciljs.com/docs/properties#string-props)
* [Object Props](https://stenciljs.com/docs/properties#object-props)
* [Array Props](https://stenciljs.com/docs/properties#array-props)
* [Advanced Prop Types](https://stenciljs.com/docs/properties#advanced-prop-types)
* [Default Values](https://stenciljs.com/docs/properties#default-values)
* [Inferring Types from Default Values](https://stenciljs.com/docs/properties#inferring-types-from-default-values)
* [Required Properties](https://stenciljs.com/docs/properties#required-properties)
* [Prop Validation](https://stenciljs.com/docs/properties#prop-validation)
* [@Prop() Options](https://stenciljs.com/docs/properties#prop-options)
* [Attribute Name (`attribute`)](https://stenciljs.com/docs/properties#attribute-name-attribute)
* [Prop Mutability (`mutable`)](https://stenciljs.com/docs/properties#prop-mutability-mutable)
* [Reflect Properties Values to Attributes (`reflect`)](https://stenciljs.com/docs/properties#reflect-properties-values-to-attributes-reflect)
* [Prop Getters and Setters](https://stenciljs.com/docs/properties#prop-getters-and-setters)
* * *
[Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.35/components/properties.md)
---
# Reactive Data, Handling arrays and objects | Stencil
[Skip to main content](https://stenciljs.com/docs/reactive-data#__docusaurus_skipToContent_fallback)
[An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none)
Version: v4.35
On this page
Stencil components update when props or state on a component change.
Rendering methods[](https://stenciljs.com/docs/reactive-data#rendering-methods "Direct link to Rendering methods")
--------------------------------------------------------------------------------------------------------------------
When props or state change on a component, the [`render()` method](https://stenciljs.com/docs/templating-jsx)
is scheduled to run.
The Watch Decorator (`@Watch()`)[](https://stenciljs.com/docs/reactive-data#the-watch-decorator-watch "Direct link to the-watch-decorator-watch")
---------------------------------------------------------------------------------------------------------------------------------------------------
`@Watch()` is a decorator that is applied to a method of a Stencil component. The decorator accepts a single argument, the name of a class member that is decorated with `@Prop()` or `@State()`, or a host attribute. A method decorated with `@Watch()` will automatically run when its associated class member or attribute changes.
// We import Prop & State to show how `@Watch()` can be used on// class members decorated with either `@Prop()` or `@State()`import { Component, Prop, State, Watch } from '@stencil/core';@Component({ tag: 'loading-indicator' })export class LoadingIndicator { // We decorate a class member with @Prop() so that we // can apply @Watch() @Prop() activated: boolean; // We decorate a class member with @State() so that we // can apply @Watch() @State() busy: boolean; // Apply @Watch() for the component's `activated` member. // Whenever `activated` changes, this method will fire. @Watch('activated') watchPropHandler(newValue: boolean, oldValue: boolean) { console.log('The old value of activated is: ', oldValue); console.log('The new value of activated is: ', newValue); } // Apply @Watch() for the component's `busy` member. // Whenever `busy` changes, this method will fire. @Watch('busy') watchStateHandler(newValue: boolean, oldValue: boolean) { console.log('The old value of busy is: ', oldValue); console.log('The new value of busy is: ', newValue); } @Watch('activated') @Watch('busy') watchMultiple(newValue: boolean, oldValue: boolean, propName:string) { console.log(`The new value of ${propName} is: `, newValue); }}
In the example above, there are two `@Watch()` decorators. One decorates `watchPropHandler`, which will fire when the class member `activated` changes. The other decorates `watchStateHandler`, which will fire when the class member `busy` changes.
When fired, the decorated method will receive the old and new values of the prop/state. This is useful for validation or the handling of side effects.
info
The `@Watch()` decorator does not fire when a component initially loads.
### Watching Native HTML Attributes[](https://stenciljs.com/docs/reactive-data#watching-native-html-attributes "Direct link to Watching Native HTML Attributes")
Stencil's `@Watch()` decorator also allows you to watch native HTML attributes on the constructed host element. Simply include the attribute name as the argument to the decorator (this is case-sensitive):
@Watch('aria-label')onAriaLabelChange(newVal: string, oldVal: string) { console.log('Label changed:', newVal, oldVal);}
note
Since native attributes are not `@Prop()` or `State()` members of the Stencil component, they will not automatically trigger a re-render when changed. If you wish to re-render a component in this instance, you can leverage the `forceUpdate()` method:
import { Component, forceUpdate, h } from '@stencil/core';@Watch('aria-label')onAriaLabelChange() { forceUpdate(this); // Forces a re-render}
Handling Arrays and Objects[](https://stenciljs.com/docs/reactive-data#handling-arrays-and-objects "Direct link to Handling Arrays and Objects")
--------------------------------------------------------------------------------------------------------------------------------------------------
When Stencil checks if a class member decorated with `@Prop()` or `@State()` has changed, it checks if the reference to the class member has changed. When a class member is an object or array, and is marked with `@Prop()` or `@State`, in-place mutation of an existing entity will _not_ cause `@Watch()` to fire, as it does not change the _reference_ to the class member.
### Updating Arrays[](https://stenciljs.com/docs/reactive-data#updating-arrays "Direct link to Updating Arrays")
For arrays, the standard mutable array operations such as `push()` and `unshift()` won't trigger a component update. These functions will change the content of the array, but won't change the reference to the array itself.
In order to make changes to an array, non-mutable array operators should be used. Non-mutable array operators return a copy of a new array that can be detected in a performant manner. These include `map()` and `filter()`, and the [spread operator syntax](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Spread_operator)
. The value returned by `map()`, `filter()`, etc., should be assigned to the `@Prop()` or `@State()` class member being watched.
For example, to push a new item to an array, create a new array with the existing values and the new value at the end:
import { Component, State, Watch, h } from '@stencil/core';@Component({ tag: 'rand-numbers'})export class RandomNumbers { // We decorate a class member with @State() so that we // can apply @Watch(). This will hold a list of randomly // generated numbers @State() randNumbers: number[] = []; private timer: NodeJS.Timer; // Apply @Watch() for the component's `randNumbers` member. // Whenever `randNumbers` changes, this method will fire. @Watch('randNumbers') watchStateHandler(newValue: number[], oldValue: number[]) { console.log('The old value of randNumbers is: ', oldValue); console.log('The new value of randNumbers is: ', newValue); } connectedCallback() { this.timer = setInterval(() => { // generate a random whole number const newVal = Math.ceil(Math.random() * 100); /** * This does not create a new array. When stencil * attempts to see if any Watched members have changed, * it sees the reference to its `randNumbers` State is * the same, and will not trigger `@Watch` or a re-render */ // this.randNumbers.push(newVal) /** * Using the spread operator, on the other hand, does * create a new array. `randNumbers` is reassigned * using the value returned by the spread operator. * The reference to `randNumbers` has changed, which * will trigger `@Watch` and a re-render */ this.randNumbers = [...this.randNumbers, newVal] }, 1000) } disconnectedCallback() { if (this.timer) { clearInterval(this.timer) } } render() { return( ); }}
It's important to note that it's the reassignment of `this.items` that is causing the rerender in `connectedCallback()`:
this.items = [...this.items, newTodo];
Mutating the existing reference to `this.items` like in the examples below will not cause a rerender, as Stencil will not know that the contents of the array has changed:
// updating `items` either of these ways will not// cause a rerenderthis.items.push(newTodo);this.items[this.items.length - 1] = newTodo;
Similar to the examples above, this code sample makes use of the [connectedCallback() lifecycle method](https://stenciljs.com/docs/component-lifecycle#connectedcallback)
to create a new `Item` and add it to `items` every 2000 milliseconds (every two seconds). The example above also makes use of the [disconnectedCallback() lifecycle method](https://stenciljs.com/docs/component-lifecycle#disconnectedcallback)
to properly clean up the timer that was created using `setInterval` in `connectedCallback()`.
Contents
--------
* [The State Decorator (`@State`)](https://stenciljs.com/docs/state#the-state-decorator-state)
* [When to Use `@State()`?](https://stenciljs.com/docs/state#when-to-use-state)
* [Examples](https://stenciljs.com/docs/state#examples)
* [Using `@State()` with `@Listen()`](https://stenciljs.com/docs/state#using-state-with-listen)
* [Complex Types](https://stenciljs.com/docs/state#complex-types)
* * *
[Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.35/components/state.md)
---
# Using JSX | Stencil
[Skip to main content](https://stenciljs.com/docs/templating-jsx#__docusaurus_skipToContent_fallback)
[An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none)
Version: v4.35
On this page
Stencil components are rendered using JSX, a popular, declarative template syntax. Each component has a `render` function that returns a tree of components that are rendered to the DOM at runtime.
Basics[](https://stenciljs.com/docs/templating-jsx#basics "Direct link to Basics")
------------------------------------------------------------------------------------
The `render` function is used to output a tree of components that will be drawn to the screen.
class MyComponent { render() { return ( ); }}
In this example we're returning the JSX representation of a `div`, with two child elements: an `h1` and a `p`.
### Host Element[](https://stenciljs.com/docs/templating-jsx#host-element "Direct link to Host Element")
If you want to modify the host element itself, such as adding a class or an attribute to the component itself, use the `` functional component. Check for more details [here](https://stenciljs.com/docs/host-element)
Data Binding[](https://stenciljs.com/docs/templating-jsx#data-binding "Direct link to Data Binding")
------------------------------------------------------------------------------------------------------
Components often need to render dynamic data. To do this in JSX, use `{ }` around a variable:
render() { return ( ` won't be reset and its lifecycle methods such as `componentWillLoad()` won't fire. Instead, the conditional merely triggers an update to the very same component.
If you want to destroy and recreate a component in a conditional, you can assign the `key` attribute. This tells Stencil that the components are actually different siblings:
{someCondition ? ` component with fresh internal state that also runs the lifecycle methods `componentWillLoad()` and `componentDidLoad()`.
Slots[](https://stenciljs.com/docs/templating-jsx#slots "Direct link to Slots")
---------------------------------------------------------------------------------
Components often need to render dynamic children in specific locations in their component tree, allowing a developer to supply child content when using our component, with our component placing that child component in the proper location.
To do this, you can use the [Slot](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/slot)
tag inside of your `my-component`.
// my-component.tsxrender() { return (
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. This file can be used as the root module when distributing your component library, see [Publishing](https://stenciljs.com/docs/publishing)
for more details. | note At this time, components that do not use JSX cannot be automatically defined. This is a known limitation of Stencil that users should be aware of. ### dir[](https://stenciljs.com/docs/v4.34/custom-elements#dir "Direct link to dir") _default: `'dist/components'`_ This config option allows you to change the output directory where the compiled output for this output target will be written. ### empty[](https://stenciljs.com/docs/v4.34/custom-elements#empty "Direct link to empty") _default: `true`_ Setting this flag to `true` will remove the contents of the [output directory](https://stenciljs.com/docs/v4.34/custom-elements#dir) between builds. ### externalRuntime[](https://stenciljs.com/docs/v4.34/custom-elements#externalruntime "Direct link to externalRuntime") _default: `true`_ Setting this flag to `true` results in the following behaviors: 1. Minification will follow what is specified in the [Stencil config](https://stenciljs.com/docs/v4.34/config#minifyjs) . 2. Filenames will not be hashed. 3. All imports from packages under `@stencil/core/*` will be marked as external and therefore not included in the generated Rollup bundle. Ensure that `@stencil/core` is included in your list of dependencies if you set this option to `true`. This is crucial to prevent any runtime errors. ### generateTypeDeclarations[](https://stenciljs.com/docs/v4.34/custom-elements#generatetypedeclarations "Direct link to generateTypeDeclarations") _default: `true`_ By default, Stencil will generate type declaration files (`.d.ts` files) as a part of the `dist-custom-elements` output target through the `generateTypeDeclarations` field on the target options. Type declaration files will be placed in the `dist/types` directory in the root of a Stencil project. At this time, this output destination is not able to be configured. Setting this flag to `false` will not generate type declaration files for the `dist-custom-elements` output target. note When set to generate type declarations, Stencil respects the export behavior selected via `customElementsExportBehavior` and generates type declarations specific to the content of the generated [output directory's](https://stenciljs.com/docs/v4.34/custom-elements#dir) `index.js` file. ### includeGlobalScripts[](https://stenciljs.com/docs/v4.34/custom-elements#includeglobalscripts "Direct link to includeGlobalScripts") _default: `false`_ Setting this flag to `true` will include [global scripts](https://stenciljs.com/docs/v4.34/config#globalscript) in the bundle and execute them once the bundle entry point in loaded. ### isPrimaryPackageOutputTarget[](https://stenciljs.com/docs/v4.34/custom-elements#isprimarypackageoutputtarget "Direct link to isPrimaryPackageOutputTarget") _default: `false`_ If `true`, this output target will be used to validate `package.json` fields for your project's distribution. See the overview of [primary package output target validation](https://stenciljs.com/docs/v4.34/output-targets#primary-package-output-target-validation) for more information. ### minify[](https://stenciljs.com/docs/v4.34/custom-elements#minify "Direct link to minify") _default: `false`_ Setting this flag to `true` will cause file minification to follow what is specified in the [Stencil config](https://stenciljs.com/docs/v4.34/config#minifyjs) . _However_, if [`externalRuntime`](https://stenciljs.com/docs/v4.34/custom-elements#externalruntime) is enabled, it will override this option and always result in minification being disabled. Making Assets Available[](https://stenciljs.com/docs/v4.34/custom-elements#making-assets-available "Direct link to Making Assets Available") ---------------------------------------------------------------------------------------------------------------------------------------------- For performance reasons, the generated bundle does not include [local assets](https://stenciljs.com/docs/v4.34/assets) built within the JavaScript output, but instead it's recommended to keep static assets as external files. By keeping them external this ensures they can be requested on-demand, rather than either welding their content into the JS file, or adding many URLs for the bundler to add to the output. One method to ensure [assets](https://stenciljs.com/docs/v4.34/assets) are available to external builds and http servers is to set the asset path using `setAssetPath()`. The `setAssetPath()` function is used to manually set the base path where static assets can be found. For the lazy-loaded output target the asset path is automatically set and assets copied to the correct build directory. However, for custom elements builds, the `setAssetPath(path)` should be used to customize the asset path depending on where they are found on the http server. If the component's script is a `type="module"`, it's recommended to use `import.meta.url`, such as `setAssetPath(import.meta.url)`. Other options include `setAssetPath(document.currentScript.src)`, or using a bundler's replace plugin to dynamically set the path at build time, such as `setAssetPath(process.env.ASSET_PATH)`. import { setAssetPath } from 'my-library/dist/components';setAssetPath(document.currentScript.src); 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 bundling, and where your assets can be loaded from. How the files are copied to the production build directory depends on the bundler or tooling. The configs below provide examples of how to do this automatically with popular bundlers. Example Bundler Configs[](https://stenciljs.com/docs/v4.34/custom-elements#example-bundler-configs "Direct link to Example Bundler Configs") ---------------------------------------------------------------------------------------------------------------------------------------------- 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. The following examples assume your component library is published to NPM as `my-library`. You should change this to the name you actually publish your library with. Users will need to install your library before importing them. * npm * Yarn * pnpm npm install my-library yarn add my-library pnpm add my-library ### webpack.config.js[](https://stenciljs.com/docs/v4.34/custom-elements#webpackconfigjs "Direct link to webpack.config.js") A webpack config will look something like the one below. Note how assets are copied from the library's `node_module` folder to `dist/assets` via the `CopyPlugin` utility. This is important if your library includes [local assets](https://stenciljs.com/docs/v4.34/assets) . const path = require('path');const CopyPlugin = require('copy-webpack-plugin');module.exports = { entry: './src/index.js', output: { filename: 'main.js', path: path.resolve(__dirname, 'dist'), }, module: { rules: [ { test: /\.css$/i, use: ['style-loader', 'css-loader'], }, ], }, plugins: [ new CopyPlugin({ patterns: [ { from: path.resolve(__dirname, 'node_modules/my-library/dist/my-library/assets'), to: path.resolve(__dirname, 'dist/assets'), }, ], }), ],}; ### rollup.config.js[](https://stenciljs.com/docs/v4.34/custom-elements#rollupconfigjs "Direct link to rollup.config.js") A Rollup config will look something like the one below. Note how assets are copied from the library's `node_module` folder to `dist/assets` via the `rollup-copy-plugin` utility. This is important if your library includes [local assets](https://stenciljs.com/docs/v4.34/assets) . import path from 'path';import commonjs from '@rollup/plugin-commonjs';import copy from 'rollup-plugin-copy';import postcss from 'rollup-plugin-postcss';import resolve from '@rollup/plugin-node-resolve';export default { input: 'src/index.js', output: [{ dir: path.resolve('dist/'), format: 'es' }], plugins: [ resolve(), commonjs(), postcss({ extensions: ['.css'], }), copy({ targets: [ { src: path.resolve(__dirname, 'node_modules/my-library/dist/my-library/assets'), dest: path.resolve(__dirname, 'dist'), }, ], }), ],}; Contents -------- * [Config](https://stenciljs.com/docs/v4.34/custom-elements#config) * [copy](https://stenciljs.com/docs/v4.34/custom-elements#copy) * [customElementsExportBehavior](https://stenciljs.com/docs/v4.34/custom-elements#customelementsexportbehavior) * [dir](https://stenciljs.com/docs/v4.34/custom-elements#dir) * [empty](https://stenciljs.com/docs/v4.34/custom-elements#empty) * [externalRuntime](https://stenciljs.com/docs/v4.34/custom-elements#externalruntime) * [generateTypeDeclarations](https://stenciljs.com/docs/v4.34/custom-elements#generatetypedeclarations) * [includeGlobalScripts](https://stenciljs.com/docs/v4.34/custom-elements#includeglobalscripts) * [isPrimaryPackageOutputTarget](https://stenciljs.com/docs/v4.34/custom-elements#isprimarypackageoutputtarget) * [minify](https://stenciljs.com/docs/v4.34/custom-elements#minify) * [Making Assets Available](https://stenciljs.com/docs/v4.34/custom-elements#making-assets-available) * [Example Bundler Configs](https://stenciljs.com/docs/v4.34/custom-elements#example-bundler-configs) * [webpack.config.js](https://stenciljs.com/docs/v4.34/custom-elements#webpackconfigjs) * [rollup.config.js](https://stenciljs.com/docs/v4.34/custom-elements#rollupconfigjs) * * * [Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.34/output-targets/custom-elements.md) --- # Custom Elements with Stencil | Stencil [Skip to main content](https://stenciljs.com/docs/custom-elements#__docusaurus_skipToContent_fallback) [An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none) Version: v4.35 On this page The `dist-custom-elements` output target creates custom elements that directly extend `HTMLElement` and provides simple utility functions for easily defining these elements on the [Custom Element Registry](https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry) . This output target excels in use in frontend frameworks and projects that will handle bundling, lazy-loading, and custom element registration themselves. 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 [dist output target](https://stenciljs.com/docs/distribution) . To generate components using the `dist-custom-elements` output target, add it to a project's `stencil.config.ts` file like so: stencil.config.ts import { Config } from '@stencil/core';export const config: Config = { // Other top-level config options here outputTargets: [ { type: 'dist-custom-elements', // Output target config options here }, // Other output targets here ],}; Config[](https://stenciljs.com/docs/custom-elements#config "Direct link to Config") ------------------------------------------------------------------------------------- ### copy[](https://stenciljs.com/docs/custom-elements#copy "Direct link to copy") _default: `undefined`_ An array of [copy tasks](https://stenciljs.com/docs/copy-tasks) to be executed during the build process. ### customElementsExportBehavior[](https://stenciljs.com/docs/custom-elements#customelementsexportbehavior "Direct link to customElementsExportBehavior") _default: `'default'`_ By default, the `dist-custom-elements` output target generates a single file per component, and exports each of those files individually. 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. 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.tsimport { 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. This file can be used as the root module when distributing your component library, see [Publishing](https://stenciljs.com/docs/publishing)
for more details. | note At this time, components that do not use JSX cannot be automatically defined. This is a known limitation of Stencil that users should be aware of. ### dir[](https://stenciljs.com/docs/custom-elements#dir "Direct link to dir") _default: `'dist/components'`_ This config option allows you to change the output directory where the compiled output for this output target will be written. ### empty[](https://stenciljs.com/docs/custom-elements#empty "Direct link to empty") _default: `true`_ Setting this flag to `true` will remove the contents of the [output directory](https://stenciljs.com/docs/custom-elements#dir) between builds. ### externalRuntime[](https://stenciljs.com/docs/custom-elements#externalruntime "Direct link to externalRuntime") _default: `true`_ Setting this flag to `true` results in the following behaviors: 1. Minification will follow what is specified in the [Stencil config](https://stenciljs.com/docs/config#minifyjs) . 2. Filenames will not be hashed. 3. All imports from packages under `@stencil/core/*` will be marked as external and therefore not included in the generated Rollup bundle. Ensure that `@stencil/core` is included in your list of dependencies if you set this option to `true`. This is crucial to prevent any runtime errors. ### generateTypeDeclarations[](https://stenciljs.com/docs/custom-elements#generatetypedeclarations "Direct link to generateTypeDeclarations") _default: `true`_ By default, Stencil will generate type declaration files (`.d.ts` files) as a part of the `dist-custom-elements` output target through the `generateTypeDeclarations` field on the target options. Type declaration files will be placed in the `dist/types` directory in the root of a Stencil project. At this time, this output destination is not able to be configured. Setting this flag to `false` will not generate type declaration files for the `dist-custom-elements` output target. note When set to generate type declarations, Stencil respects the export behavior selected via `customElementsExportBehavior` and generates type declarations specific to the content of the generated [output directory's](https://stenciljs.com/docs/custom-elements#dir) `index.js` file. ### includeGlobalScripts[](https://stenciljs.com/docs/custom-elements#includeglobalscripts "Direct link to includeGlobalScripts") _default: `false`_ Setting this flag to `true` will include [global scripts](https://stenciljs.com/docs/config#globalscript) in the bundle and execute them once the bundle entry point in loaded. ### isPrimaryPackageOutputTarget[](https://stenciljs.com/docs/custom-elements#isprimarypackageoutputtarget "Direct link to isPrimaryPackageOutputTarget") _default: `false`_ If `true`, this output target will be used to validate `package.json` fields for your project's distribution. See the overview of [primary package output target validation](https://stenciljs.com/docs/output-targets#primary-package-output-target-validation) for more information. ### minify[](https://stenciljs.com/docs/custom-elements#minify "Direct link to minify") _default: `false`_ Setting this flag to `true` will cause file minification to follow what is specified in the [Stencil config](https://stenciljs.com/docs/config#minifyjs) . _However_, if [`externalRuntime`](https://stenciljs.com/docs/custom-elements#externalruntime) is enabled, it will override this option and always result in minification being disabled. Making Assets Available[](https://stenciljs.com/docs/custom-elements#making-assets-available "Direct link to Making Assets Available") ---------------------------------------------------------------------------------------------------------------------------------------- For performance reasons, the generated bundle does not include [local assets](https://stenciljs.com/docs/assets) built within the JavaScript output, but instead it's recommended to keep static assets as external files. By keeping them external this ensures they can be requested on-demand, rather than either welding their content into the JS file, or adding many URLs for the bundler to add to the output. One method to ensure [assets](https://stenciljs.com/docs/assets) are available to external builds and http servers is to set the asset path using `setAssetPath()`. The `setAssetPath()` function is used to manually set the base path where static assets can be found. For the lazy-loaded output target the asset path is automatically set and assets copied to the correct build directory. However, for custom elements builds, the `setAssetPath(path)` should be used to customize the asset path depending on where they are found on the http server. If the component's script is a `type="module"`, it's recommended to use `import.meta.url`, such as `setAssetPath(import.meta.url)`. Other options include `setAssetPath(document.currentScript.src)`, or using a bundler's replace plugin to dynamically set the path at build time, such as `setAssetPath(process.env.ASSET_PATH)`. import { setAssetPath } from 'my-library/dist/components';setAssetPath(document.currentScript.src); 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 bundling, and where your assets can be loaded from. How the files are copied to the production build directory depends on the bundler or tooling. The configs below provide examples of how to do this automatically with popular bundlers. Example Bundler Configs[](https://stenciljs.com/docs/custom-elements#example-bundler-configs "Direct link to Example Bundler Configs") ---------------------------------------------------------------------------------------------------------------------------------------- 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. The following examples assume your component library is published to NPM as `my-library`. You should change this to the name you actually publish your library with. Users will need to install your library before importing them. * npm * Yarn * pnpm npm install my-library yarn add my-library pnpm add my-library ### webpack.config.js[](https://stenciljs.com/docs/custom-elements#webpackconfigjs "Direct link to webpack.config.js") A webpack config will look something like the one below. Note how assets are copied from the library's `node_module` folder to `dist/assets` via the `CopyPlugin` utility. This is important if your library includes [local assets](https://stenciljs.com/docs/assets) . const path = require('path');const CopyPlugin = require('copy-webpack-plugin');module.exports = { entry: './src/index.js', output: { filename: 'main.js', path: path.resolve(__dirname, 'dist'), }, module: { rules: [ { test: /\.css$/i, use: ['style-loader', 'css-loader'], }, ], }, plugins: [ new CopyPlugin({ patterns: [ { from: path.resolve(__dirname, 'node_modules/my-library/dist/my-library/assets'), to: path.resolve(__dirname, 'dist/assets'), }, ], }), ],}; ### rollup.config.js[](https://stenciljs.com/docs/custom-elements#rollupconfigjs "Direct link to rollup.config.js") A Rollup config will look something like the one below. Note how assets are copied from the library's `node_module` folder to `dist/assets` via the `rollup-copy-plugin` utility. This is important if your library includes [local assets](https://stenciljs.com/docs/assets) . import path from 'path';import commonjs from '@rollup/plugin-commonjs';import copy from 'rollup-plugin-copy';import postcss from 'rollup-plugin-postcss';import resolve from '@rollup/plugin-node-resolve';export default { input: 'src/index.js', output: [{ dir: path.resolve('dist/'), format: 'es' }], plugins: [ resolve(), commonjs(), postcss({ extensions: ['.css'], }), copy({ targets: [ { src: path.resolve(__dirname, 'node_modules/my-library/dist/my-library/assets'), dest: path.resolve(__dirname, 'dist'), }, ], }), ],}; Contents -------- * [Config](https://stenciljs.com/docs/custom-elements#config) * [copy](https://stenciljs.com/docs/custom-elements#copy) * [customElementsExportBehavior](https://stenciljs.com/docs/custom-elements#customelementsexportbehavior) * [dir](https://stenciljs.com/docs/custom-elements#dir) * [empty](https://stenciljs.com/docs/custom-elements#empty) * [externalRuntime](https://stenciljs.com/docs/custom-elements#externalruntime) * [generateTypeDeclarations](https://stenciljs.com/docs/custom-elements#generatetypedeclarations) * [includeGlobalScripts](https://stenciljs.com/docs/custom-elements#includeglobalscripts) * [isPrimaryPackageOutputTarget](https://stenciljs.com/docs/custom-elements#isprimarypackageoutputtarget) * [minify](https://stenciljs.com/docs/custom-elements#minify) * [Making Assets Available](https://stenciljs.com/docs/custom-elements#making-assets-available) * [Example Bundler Configs](https://stenciljs.com/docs/custom-elements#example-bundler-configs) * [webpack.config.js](https://stenciljs.com/docs/custom-elements#webpackconfigjs) * [rollup.config.js](https://stenciljs.com/docs/custom-elements#rollupconfigjs) * * * [Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.35/output-targets/custom-elements.md) --- # Publishing A Component Library | Stencil [Skip to main content](https://stenciljs.com/docs/publishing#__docusaurus_skipToContent_fallback) [An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none) Version: v4.35 On this page There are numerous strategies to publish and distribute your component library to be consumed by external projects. One of the benefits of Stencil is that is makes it easy to generate the various [output targets](https://stenciljs.com/docs/output-targets) that are right for your use-case. Use Cases[](https://stenciljs.com/docs/publishing#use-cases "Direct link to Use Cases") ----------------------------------------------------------------------------------------- To use your Stencil components in other projects, there are two different output targets to consider: [`dist`](https://stenciljs.com/docs/distribution) and [`dist-custom-elements`](https://stenciljs.com/docs/custom-elements) . Both export your components for different use cases. Luckily, both can be generated at the same time, using the same source code, and shipped in the same distribution. It would be up to the consumer of your component library to decide which build to use. ### Lazy Loading[](https://stenciljs.com/docs/publishing#lazy-loading "Direct link to Lazy Loading") If you prefer to have your components automatically loaded when used in your application, we recommend enabling the [`dist`](https://stenciljs.com/docs/distribution) output target. The bundle gives you a small entry file that registers all your components and defers loading the full component logic until it is rendered in your application. It doesn't matter if the actual application is written in HTML or created with vanilla JavaScript, jQuery, React, etc. Your users can import your component library, e.g. called `my-design-system`, either via a `script` tag: or by importing it in the bootstrap script of your application: import 'my-design-system'; To ensure that the right entry file is loaded when importing the project, define the following fields in your `package.json`: { "exports": "./dist/esm/my-design-system.js", "main": "./dist/cjs/my-design-system.js", "unpkg": "dist/my-design-system/my-design-system.esm.js",} Read more about various options when it comes to configuring your project's components for lazy loading in the [`dist`](https://stenciljs.com/docs/distribution) output target section. #### Considerations[](https://stenciljs.com/docs/publishing#considerations "Direct link to Considerations") To start, Stencil was designed to lazy-load itself only when the component was actually used on a page. There are many benefits to this approach, such as simply adding a script tag to any page and the entire library is available for use, yet only the components actually used are downloaded. For example, [`@ionic/core`](https://www.npmjs.com/package/@ionic/core) comes with over 100 components, but a webpage may only need `ion-toggle`. Instead of requesting the entire component library, or generating a custom bundle for just `ion-toggle`, the `dist` output target is able to generate a tiny entry build ready to load any of its components on-demand. However be aware that this approach is not ideal in all cases. It requires your application to ship the bundled components as static assets in order for them to load properly. Furthermore, having many nested component dependencies can have an impact on the performance of your application. For example, given you have a component `CmpA` which uses a Stencil component `CmpB` which itself uses another Stencil component `CmpC`. In order to fully render `CmpA` the browser has to load 3 scripts sequentially which can result in undesired rendering delays. ### Standalone[](https://stenciljs.com/docs/publishing#standalone "Direct link to Standalone") The [`dist-custom-elements`](https://stenciljs.com/docs/custom-elements) output target builds each component as a stand-alone class that extends `HTMLElement`. The output is a standardized custom element with the styles already attached and without any of Stencil's lazy-loading. This may be preferred for projects that are already handling bundling, lazy-loading and defining the custom elements themselves. The generated files will each export a component class and will already have the styles bundled. However, this build does not define the custom elements or apply any polyfills. Static assets referenced within components will need to be set using `setAssetPath` (see [Making Assets Available](https://stenciljs.com/docs/custom-elements#making-assets-available) ). You can use these standalone components by importing them via: import { MyComponent, defineCustomElementMyComponent } from 'my-design-system'// register to CustomElementRegistrydefineCustomElementMyComponent()// or extend custom element viaclass MyCustomComponent extends MyComponent { // ...}define('my-custom-component', MyCustomComponent) To ensure that the right entry file is loaded when importing the project, define different [exports fields](https://nodejs.org/api/packages.html#exports) in your `package.json`: { "exports": { ".": { "import": "./dist/components/index.js", "types": "./dist/components/index.d.ts" }, "./my-component": { "import": "./dist/components/my-component.js", "types": "./dist/components/my-component.d.ts" } }, "types": "dist/components/index.d.ts",} This allows us to map certain import paths to specific components within our project and allows users to only import the component code they are interested in and reduce the amount of code that needs to downloaded by the browser, e.g.: // this import loads all compiled componentsimport { MyComponent } from 'my-design-system'// only import compiled code for MyComponentimport { MyComponent } from 'my-design-system/my-component' If you define exports targets for all your components as shown above and by using [`customElementsExportBehavior: 'auto-define-custom-elements'`](https://stenciljs.com/docs/custom-elements#customelementsexportbehavior) as output target option, you can skip the `defineCustomElement` call and directly import the component where you need it: import 'my-design-system/my-component' note If you are distributing both the `dist` and `dist-custom-elements`, then it's best to pick one of them as the main entry depending on which use case is more prominent. Read more about various options when it comes to distributing your components as standalone components in the [`dist-custom-elements`](https://stenciljs.com/docs/custom-elements) output target section. The output directory will also contain an `index.js` file which exports some helper methods by default. The contents of the file will look something like: export { setAssetPath, setPlatformOptions } from '@stencil/core/internal/client'; note The contents may look different if [`customElementsExportBehavior`](https://stenciljs.com/docs/custom-elements#customelementsexportbehavior) is specified! #### Considerations[](https://stenciljs.com/docs/publishing#considerations-1 "Direct link to Considerations") The `dist-custom-elements` is a direct build of the custom element that extends `HTMLElement`, without any lazy-loading. This distribution strategy may be preferred for projects that use an external bundler such as [Vite](https://vitejs.dev/) , [WebPack](https://webpack.js.org/) or [Rollup](https://rollupjs.org/) to compile the application. They ensure that only the components used within your application are bundled into compilation. #### Usage in TypeScript[](https://stenciljs.com/docs/publishing#usage-in-typescript "Direct link to Usage in TypeScript") If you plan to support consuming your component library in TypeScript you'll need to set `generateTypeDeclarations: true` on the output target in your `stencil.config.ts`, like so: stencil.config.ts import { Config } from '@stencil/core';export const config: Config = { outputTargets: [ { type: 'dist-custom-elements', generateTypeDeclarations: true, }, // ... ], // ...}; Then you can set the `types` property in `package.json` so that consumers of your package can find the type definitions, like so: package.json { "types": "dist/components/index.d.ts", "dependencies": { "@stencil/core": "latest" }, ...} note If you set the `dir` property on the output target config, replace `dist/components` in the above snippet with the path set in the config. Publishing to NPM[](https://stenciljs.com/docs/publishing#publishing-to-npm "Direct link to Publishing to NPM") ----------------------------------------------------------------------------------------------------------------- [NPM](https://www.npmjs.com/) is an online software registry for sharing libraries, tools, utilities, packages, etc. To make your Stencil project widely available to be consumed, it's recommended to [publish the component library to NPM](https://docs.npmjs.com/getting-started/publishing-npm-packages) . Once the library is published to NPM, other projects are able to add your component library as a dependency and use the components within their own projects. Contents -------- * [Use Cases](https://stenciljs.com/docs/publishing#use-cases) * [Lazy Loading](https://stenciljs.com/docs/publishing#lazy-loading) * [Standalone](https://stenciljs.com/docs/publishing#standalone) * [Publishing to NPM](https://stenciljs.com/docs/publishing#publishing-to-npm) * * * [Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.35/guides/publishing.md) --- # Component API | Stencil [Skip to main content](https://stenciljs.com/docs/api#__docusaurus_skipToContent_fallback) [An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none) Version: v4.35 On this page The whole API provided by stencil can be condensed in a set of decorators, lifecycles hooks and rendering methods. Decorators[](https://stenciljs.com/docs/api#decorators "Direct link to Decorators") ------------------------------------------------------------------------------------- Decorators are a pure compiler-time construction used by stencil to collect all the metadata about a component, the properties, attributes and methods it might expose, the events it might emit or even the associated stylesheets. Once all the metadata has been collected, all the decorators are removed from the output, so they don't incur any runtime overhead. * [@Component()](https://stenciljs.com/docs/component) declares a new web component * [@Prop()](https://stenciljs.com/docs/properties#the-prop-decorator-prop) declares an exposed property/attribute * [@State()](https://stenciljs.com/docs/state#the-state-decorator-state) declares an internal state of the component * [@Watch()](https://stenciljs.com/docs/reactive-data#the-watch-decorator-watch) declares a hook that runs when a property or state changes * [@Element()](https://stenciljs.com/docs/host-element#element-decorator) declares a reference to the host element * [@Method()](https://stenciljs.com/docs/methods) declares an exposed public method * [@Event()](https://stenciljs.com/docs/events#event-decorator) declares a DOM event the component might emit * [@Listen()](https://stenciljs.com/docs/events#listen-decorator) listens for DOM events Lifecycle hooks[](https://stenciljs.com/docs/api#lifecycle-hooks "Direct link to Lifecycle hooks") ---------------------------------------------------------------------------------------------------- * [connectedCallback()](https://stenciljs.com/docs/component-lifecycle#connectedcallback) * [disconnectedCallback()](https://stenciljs.com/docs/component-lifecycle#disconnectedcallback) * [componentWillLoad()](https://stenciljs.com/docs/component-lifecycle#componentwillload) * [componentDidLoad()](https://stenciljs.com/docs/component-lifecycle#componentdidload) * [componentShouldUpdate(newValue, oldValue, propName): boolean](https://stenciljs.com/docs/component-lifecycle#componentshouldupdate) * [componentWillRender()](https://stenciljs.com/docs/component-lifecycle#componentwillrender) * [componentDidRender()](https://stenciljs.com/docs/component-lifecycle#componentdidrender) * [componentWillUpdate()](https://stenciljs.com/docs/component-lifecycle#componentwillupdate) * [componentDidUpdate()](https://stenciljs.com/docs/component-lifecycle#componentdidupdate) * **[render()](https://stenciljs.com/docs/templating-jsx) ** componentOnReady()[](https://stenciljs.com/docs/api#componentonready "Direct link to componentOnReady()") ----------------------------------------------------------------------------------------------------------- This isn't a true "lifecycle" method that would be declared on the component class definition, but instead is a utility method that can be used by an implementation consuming your Stencil component to detect when a component has finished its first render cycle. This method returns a promise which resolves after `componentDidRender()` on the _first_ render cycle. note `componentOnReady()` only resolves once per component lifetime. If you need to hook into subsequent render cycle, use `componentDidRender()` or `componentDidUpdate()`. Executing code after `componentOnReady()` resolves could look something like this: // Get a reference to the elementconst el = document.querySelector('my-component');el.componentOnReady().then(() => { // Place any code in here you want to execute when the component is ready console.log('my-component is ready');}); The availability of `componentOnReady()` depends on the component's compiled output type. This method is only available for lazy-loaded distribution types ([`dist`](https://stenciljs.com/docs/distribution) and [`www`](https://stenciljs.com/docs/www) ) and, as such, is not available for [`dist-custom-elements`](https://stenciljs.com/docs/custom-elements) output. If you want to simulate the behavior of `componentOnReady()` for non-lazy builds, you can implement a helper method to wrap the functionality similar to what the Ionic Framework does [here](https://github.com/ionic-team/ionic-framework/blob/main/core/src/utils/helpers.ts#L60-L79) . The `appload` event[](https://stenciljs.com/docs/api#the-appload-event "Direct link to the-appload-event") ------------------------------------------------------------------------------------------------------------ In addition to component-specific lifecycle hooks, a special event called `appload` will be emitted when the app and all of its child components have finished loading. You can listen for it on the `window` object. If you have multiple apps on the same page, you can determine which app emitted the event by checking `event.detail.namespace`. This will be the value of the [namespace config option](https://stenciljs.com/docs/config#namespace) you've set in your Stencil config. window.addEventListener('appload', (event) => { console.log(event.detail.namespace);}); Other[](https://stenciljs.com/docs/api#other "Direct link to Other") ---------------------------------------------------------------------- The following primitives can be imported from the `@stencil/core` package and used within the lifecycle of a component: * [**Host**](https://stenciljs.com/docs/host-element) : `
...
...
...
); }}
* [**h()**](https://stenciljs.com/docs/templating-jsx)
: It's used within the `render()` to turn the JSX into Virtual DOM elements.
* **render()**: a utility method to render a virtual DOM created by `h()` into a container.
**Type:** `(vnode: VNode, container: Element) => void` **Example:**
import { render } from '@stencil/core'const vdom = ( Hello World!
)render(vdom, document.body)
* [**readTask()**](https://developers.google.com/web/fundamentals/performance/rendering/avoid-large-complex-layouts-and-layout-thrashing)
: Schedules a DOM-read task. The provided callback will be executed in the best moment to perform DOM reads without causing layout thrashing.
**Type:** `(task: Function) => void`
* [**writeTask()**](https://developers.google.com/web/fundamentals/performance/rendering/avoid-large-complex-layouts-and-layout-thrashing)
: Schedules a DOM-write task. The provided callback will be executed in the best moment to perform DOM mutations without causing layout thrashing.
**Type:** `(task: Function) => void`
* **forceUpdate()**: Schedules a new render of the given instance or element even if no state changed. Notice `forceUpdate()` is not synchronous and might perform the DOM render in the next frame.
**Type:** `(ref: any) => void`
**Example:**
import { forceUpdate } from '@stencil/core'// inside a class component functionforceUpdate(this);
* **getAssetPath()**: Gets the path to local assets. Refer to the [Assets](https://stenciljs.com/docs/assets#getassetpath)
page for usage info.
**Type:** `(path: string) => string`
**Example:**
import { Component, Prop, getAssetPath, h } from '@stencil/core'@Component({ tag: 'cmp-asset',})export class CmpAsset { @Prop() icon: string; render() { return ( ); }}
* **setAssetPath()**: Sets the path for Stencil to resolve local assets. Refer to the [Assets](https://stenciljs.com/docs/assets#setassetpath)
page for usage info.
**Type:** `(path: string) => string`
**Example:**
import { setAssetPath } from '@stencil/core';setAssetPath(`{window.location.origin}/`);
* **setMode()**: Sets the style mode of a component. Refer to the [Styling](https://stenciljs.com/docs/styling#style-modes)
page for usage info.
**Type:** `((elm: HTMLElement) => string | undefined | null) => void`
**Example:**
import { setMode } from '@stencil/core'// set mode based on a propertysetMode((el) => el.getAttribute('mode'));
* **getMode()**: Get the current style mode of your application. Refer to the [Styling](https://stenciljs.com/docs/styling#style-modes)
page for usage info.
**Type:** `(ref: any) => string | undefined`
**Example:**
import { getMode } from '@stencil/core'getMode(this);
* **getElement()**: Retrieve a Stencil element for a given reference.
**Type:** `(ref: any) => HTMLStencilElement`
**Example:**
import { getElement } from '@stencil/core'const stencilComponent = getElement(document.querySelector('my-cmp'))if (stencilComponent) { stencilComponent.componentOnReady().then(() => { ... })}
Contents
--------
* [Decorators](https://stenciljs.com/docs/api#decorators)
* [Lifecycle hooks](https://stenciljs.com/docs/api#lifecycle-hooks)
* [componentOnReady()](https://stenciljs.com/docs/api#componentonready)
* [The `appload` event](https://stenciljs.com/docs/api#the-appload-event)
* [Other](https://stenciljs.com/docs/api#other)
* * *
[Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.35/components/api.md)
---
# Component Lifecycle Methods | Stencil
[Skip to main content](https://stenciljs.com/docs/component-lifecycle#__docusaurus_skipToContent_fallback)
[An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none)
Version: v4.35
On this page
Components have numerous lifecycle methods which can be used to know when the component "will" and "did" load, update, and render. These methods can be added to a component to hook into operations at the right time.
Implement one of the following methods within a component class and Stencil will automatically call them in the right order:
componentDidLoad()componentDidUpdate()disconnectedCallback()@Watch(‘propName’)render()connectedCallback()componentShouldUpdate()componentWillRender()componentWillUpdate()componentDidRender()componentWillLoad()Component initializedChange in a value of prop or state triggers rerenderComponent removedComponent reattached
connectedCallback()[](https://stenciljs.com/docs/component-lifecycle#connectedcallback "Direct link to connectedCallback()")
------------------------------------------------------------------------------------------------------------------------------
Called every time the component is connected to the DOM. When the component is first connected, this method is called before `componentWillLoad`.
It's important to note that this method can be called more than once, every time, the element is **attached** or **moved** in the DOM. For logic that needs to run every time the element is attached or moved in the DOM, it is considered a best practice to use this lifecycle method.
const el = document.createElement('my-cmp');document.body.appendChild(el);// connectedCallback() called// componentWillLoad() called (first time)el.remove();// disconnectedCallback()document.body.appendChild(el);// connectedCallback() called again, but `componentWillLoad()` is not.
This `lifecycle` hook follows the same semantics as the one described by the [Custom Elements Spec](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements)
disconnectedCallback()[](https://stenciljs.com/docs/component-lifecycle#disconnectedcallback "Direct link to disconnectedCallback()")
---------------------------------------------------------------------------------------------------------------------------------------
Called every time the component is disconnected from the DOM, ie, it can be dispatched more than once, DO not confuse with a "onDestroy" kind of event.
This `lifecycle` hook follows the same semantics as the one described by the [Custom Elements Spec](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements)
.
componentWillLoad()[](https://stenciljs.com/docs/component-lifecycle#componentwillload "Direct link to componentWillLoad()")
------------------------------------------------------------------------------------------------------------------------------
Called once just after the component is first connected to the DOM. Since this method is only called once, it's a good place to load data asynchronously and to setup the state without triggering extra re-renders.
A promise can be returned, that can be used to wait for the first `render()`.
componentDidLoad()[](https://stenciljs.com/docs/component-lifecycle#componentdidload "Direct link to componentDidLoad()")
---------------------------------------------------------------------------------------------------------------------------
Called once just after the component is fully loaded and the first `render()` occurs.
componentShouldUpdate()[](https://stenciljs.com/docs/component-lifecycle#componentshouldupdate "Direct link to componentShouldUpdate()")
------------------------------------------------------------------------------------------------------------------------------------------
This hook is called when a component's [`Prop`](https://stenciljs.com/docs/properties)
or [`State`](https://stenciljs.com/docs/state)
property changes and a rerender is about to be requested. This hook receives three arguments: the new value, the old value and the name of the changed state. It should return a boolean to indicate if the component should rerender (`true`) or not (`false`).
A couple of things to notice is that this method will not be executed before the initial render, that is, when the component is first attached to the dom, nor when a rerender is already scheduled in the next frame.
Let’s say the following two props of a component change synchronously:
component.somePropA = 42;component.somePropB = 88;
The `componentShouldUpdate` will be first called with arguments: `42`, `undefined` and `somePropA`. If it does return `true`, the hook will not be called again since the rerender is already scheduled to happen. Instead, if the first hook returned `false`, then `componentShouldUpdate` will be called again with `88`, `undefined` and `somePropB` as arguments, triggered by the `component.somePropB = 88` mutation.
Since the execution of this hook might be conditioned, it's not good to rely on it to watch for prop changes, instead use the `@Watch` decorator for that.
componentWillRender()[](https://stenciljs.com/docs/component-lifecycle#componentwillrender "Direct link to componentWillRender()")
------------------------------------------------------------------------------------------------------------------------------------
Called before every `render()`.
A promise can be returned, that can be used to wait for the upcoming render.
componentDidRender()[](https://stenciljs.com/docs/component-lifecycle#componentdidrender "Direct link to componentDidRender()")
---------------------------------------------------------------------------------------------------------------------------------
Called after every `render()`.
componentWillUpdate()[](https://stenciljs.com/docs/component-lifecycle#componentwillupdate "Direct link to componentWillUpdate()")
------------------------------------------------------------------------------------------------------------------------------------
Called when the component is about to be updated because some `Prop()` or `State()` changed. It's never called during the first `render()`.
A promise can be returned, that can be used to wait for the next render.
componentDidUpdate()[](https://stenciljs.com/docs/component-lifecycle#componentdidupdate "Direct link to componentDidUpdate()")
---------------------------------------------------------------------------------------------------------------------------------
Called just after the component updates. It's never called during the first `render()`.
Rendering State[](https://stenciljs.com/docs/component-lifecycle#rendering-state "Direct link to Rendering State")
--------------------------------------------------------------------------------------------------------------------
It's always recommended to make any rendered state updates within `componentWillRender()`, since this is the method which get called _before_ the `render()` method. Alternatively, updating rendered state with the `componentDidLoad()`, `componentDidUpdate()` and `componentDidRender()` methods will cause another rerender, which isn't ideal for performance.
If state _must_ be updated in `componentDidUpdate()` or `componentDidRender()`, it has the potential of getting components stuck in an infinite loop. If updating state within `componentDidUpdate()` is unavoidable, then the method should also come with a way to detect if the props or state is "dirty" or not (is the data actually different or is it the same as before). By doing a dirty check, `componentDidUpdate()` is able to avoid rendering the same data, and which in turn calls `componentDidUpdate()` again.
Lifecycle Hierarchy[](https://stenciljs.com/docs/component-lifecycle#lifecycle-hierarchy "Direct link to Lifecycle Hierarchy")
--------------------------------------------------------------------------------------------------------------------------------
A useful feature of lifecycle methods is that they take their child component's lifecycle into consideration too. For example, if the parent component, `cmp-a`, has a child component, `cmp-b`, then `cmp-a` isn't considered "loaded" until `cmp-b` has finished loading. Another way to put it is that the deepest components finish loading first, then the `componentDidLoad()` calls bubble up.
It's also important to note that even though Stencil can lazy-load components, and has asynchronous rendering, the lifecycle methods are still called in the correct order. So while the top-level component could have already been loaded, all of its lifecycle methods are still called in the correct order, which means it'll wait for a child components to finish loading. The same goes for the exact opposite, where the child components may already be ready while the parent isn't.
In the example below we have a simple hierarchy of components. The numbered list shows the order of which the lifecycle methods will fire.
My favorite color is {this.color}
); }}
import { Component, h } from '@stencil/core';@Component({ tag: 'my-parent-component'})export class MyParentComponent { render() { return ( Mock Date Picker, mode: {this.view} this.onInputChange(e)}>
}}
Note that the `formStateRestoreCallback` also receives a second argument, `mode`, which can be either `"restore"` or `"autocomplete"`, indicating the reason for the form restoration.
For more on form restoration, including a complete example, check out [this great blog post on the subject](https://web.dev/articles/more-capable-form-controls#restoring-form-state)
.
Resources[](https://stenciljs.com/docs/form-associated#resources "Direct link to Resources")
----------------------------------------------------------------------------------------------
* [WHATWG specification for form-associated custom elements](https://html.spec.whatwg.org/dev/custom-elements.html#form-associated-custom-elements)
* [ElementInternals and Form-Associated Custom Elements](https://webkit.org/blog/13711/elementinternals-and-form-associated-custom-elements/)
from the WebKit blog
* [Web.dev post detailing how form-associated lifecycle callbacks work](https://web.dev/articles/more-capable-form-controls#lifecycle_callbacks)
Footnotes[](https://stenciljs.com/docs/form-associated#footnote-label "Direct link to Footnotes")
---------------------------------------------------------------------------------------------------
1. See [https://caniuse.com/?search=attachInternals](https://caniuse.com/?search=attachInternals)
for up-to-date adoption estimates. [↩](https://stenciljs.com/docs/form-associated#user-content-fnref-1)
Contents
--------
* [Creating a Form-Associated Component](https://stenciljs.com/docs/form-associated#creating-a-form-associated-component)
* [Lifecycle Callbacks](https://stenciljs.com/docs/form-associated#lifecycle-callbacks)
* [`formAssociatedCallback`](https://stenciljs.com/docs/form-associated#formassociatedcallback)
* [`formDisabledCallback`](https://stenciljs.com/docs/form-associated#formdisabledcallback)
* [`formResetCallback`](https://stenciljs.com/docs/form-associated#formresetcallback)
* [`formStateRestoreCallback`](https://stenciljs.com/docs/form-associated#formstaterestorecallback)
* [Resources](https://stenciljs.com/docs/form-associated#resources)
* * *
[Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.35/components/form-associated.md)
---
# Webapp Output Target | Stencil
[Skip to main content](https://stenciljs.com/docs/www#__docusaurus_skipToContent_fallback)
[An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none)
Version: v4.35
On this page
The `www` output target type is oriented for webapps and websites, hosted from an http server, which can benefit from prerendering and service workers, such as this very site you're reading. If the `outputTarget` config is not provided it'll default to having just the `www` type.
Even if a project is meant to only build a reusable component library, the `www` output target is useful to build out and test the components throughout development.
outputTargets: [ { type: 'www' }]
Config[](https://stenciljs.com/docs/www#config "Direct link to Config")
-------------------------------------------------------------------------
| Property | Description | Default |
| --- | --- | --- |
| `baseUrl` | The `baseUrl` represents the site's "base" url to be served from. For example, this site's base url is `https://stenciljs.com/`. However, if the entire site's output is to live within a sub directory, then this directory's path should be the `baseUrl`. For example, Ionic's documentation is a stand-alone Stencil site that lives in the `/docs` directory within `https://ionicframework.com/`. In this example, `https://ionicframework.com/docs/` would be the base url. | `/` |
| `buildDir` | The `buildDir` is the directory of Stencil's generated scripts, such as the component files. For production builds, this directory will contain both `es5` and `esm` builds for each component. (Don't worry, users only request the one their browser needs.) | `build` |
| `dir` | The `dir` config specifies the public web distribution directory. This directory is commonly the root directory of an app to be served, such as serving static files from. This directory is built and rebuilt directly from the source files. Additionally, since this is a build target, all files will be deleted and rebuilt after each build, so it's best to always copy source files into this directory. It's recommended this directory is not committed to a repository. | `www` |
| `empty` | By default, before each build the `dir` directory will be emptied of all files. However, to prevent this directory from being emptied change this value to `false`. | `true` |
| `indexHtml` | The `indexHtml` property represents the location of the root index html file. | `index.html` |
| `serviceWorker` | The `serviceWorker` config lets you customize the service worker that gets automatically generated by the Stencil compiler. To override Stencil's defaults, set any of the values listed in the [Workbox documentation](https://developers.google.com/web/tools/workbox/modules/workbox-build#full_generatesw_config). | | Contents -------- * [Config](https://stenciljs.com/docs/www#config) * * * [Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.35/output-targets/www.md) --- # Working with host elements | Stencil [Skip to main content](https://stenciljs.com/docs/host-element#__docusaurus_skipToContent_fallback) [An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none) Version: v4.35 On this page Stencil components render their children declaratively in their `render` method [using JSX](https://stenciljs.com/docs/templating-jsx) . Most of the time, the `render()` function describes the children elements that are about to be rendered, but it can also be used to render attributes of the host element itself. `
Title
Message
Title
Message
Hello, {props.name}!
; When the JSX transpiler encounters such a component, it will take its attributes, pass them into the function as the `props` object, and replace the component with the JSX that is returned by the function.Hello, {props.name}
, children]; The JSX transpiler passes all child elements of the component as an array into the function's `children` argument.I'm a child element.
Hello, {name}!
); Working with children[](https://stenciljs.com/docs/functional-components#working-with-children "Direct link to Working with children") ---------------------------------------------------------------------------------------------------------------------------------------- The second argument of a functional component receives the passed children, but in order to work with them, `FunctionalComponent` provides a utils object that exposes a `map()` method to transform the children, and a `forEach()` method to read them. Reading the `children` array is not recommended since the stencil compiler can rename the vNode properties in prod mode. export interface FunctionalUtilities { forEach: (children: VNode[], cb: (vnode: ChildNode, index: number, array: ChildNode[]) => void) => void; map: (children: VNode[], cb: (vnode: ChildNode, index: number, array: ChildNode[]) => ChildNode) => VNode[];}export interface ChildNode { vtag?: string | number | Function; vkey?: string | number; vtext?: string; vchildren?: VNode[]; vattrs?: any; vname?: string;} **Example:** export const AddClass: FunctionalComponent = (_, children, utils) => ( utils.map(children, child => ({ ...child, vattrs: { ...child.vattrs, class: `${child.vattrs.class} add-class` } } ))); note When using a functional component in JSX, its name must start with a capital letter. Therefore it makes sense to export it as such. Disclaimer[](https://stenciljs.com/docs/functional-components#disclaimer "Direct link to Disclaimer") ------------------------------------------------------------------------------------------------------- There are a few major differences between functional components and class components. Since functional components are just syntactic sugar within JSX, they... * aren't compiled into web components, * don't create a DOM node, * don't have a Shadow DOM or scoped styles, * don't have lifecycle hooks, * are stateless. When deciding whether to use functional components, one concept to keep in mind is that often the UI of your application can be a function of its state, i. e., given the same state, it always renders the same UI. If a component has to hold state, deal with events, etc, it should probably be a class component. If a component's purpose is to simply encapsulate some markup so it can be reused across your app, it can probably be a functional component (especially if you're using a component library and thus don't need to style it). caution Stencil does not support re-exporting a functional component from a "barrel file" and dynamically rendering it in another component. This is a [known limitation](https://github.com/ionic-team/stencil/issues/5246) within Stencil. Instead, either use class components and remove the import or import the functional component directly. Contents -------- * [Working with children](https://stenciljs.com/docs/functional-components#working-with-children) * [Disclaimer](https://stenciljs.com/docs/functional-components#disclaimer) * * * [Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.35/components/functional-components.md) --- # SEO Meta Tags in SSG | Stencil [Skip to main content](https://stenciljs.com/docs/v4.33/static-site-generation-meta-tags#__docusaurus_skipToContent_fallback) [An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none) This is documentation for Stencil **v4.33**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](https://stenciljs.com/docs/static-site-generation-meta-tags) ** (v4.35). Version: v4.33 On this page Web Apps need to list detailed meta information about content in order to maximize SEO and provide good social media embed experiences. One of the benefits to Stencil's prerendering is that most DOM apis are available in the NodeJS environment too. For example, to set the document title, simply run `document.title = "Page Title"`. Similarly, meta tags can be set using standard DOM APIs as found in the browser, such as `document.head` and `document.createElement('meta')`. For this reason, your component's runtime can take care of much of this custom work during prerendering. That said, the Prerender Config also includes options that allow individual pages to be modified arbitrarily during prerendering. For example, the `afterHydrate(document, url)` hook can be used to update the parsed `document` before it is serialized into an HTML string. The `document` argument is a [standard `Document`](https://developer.mozilla.org/en-US/docs/Web/API/Document) , while the `url` argument is a [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL) for the location of the page being rendered. In the example below, the `afterHydrate(document, url)` hook is setting the document title from url's pathname. import { PrerenderConfig } from '@stencil/core';export const config: PrerenderConfig = { afterHydrate(document, url) { document.title = url.pathname; }}; @stencil/helmet[](https://stenciljs.com/docs/v4.33/static-site-generation-meta-tags#stencilhelmet "Direct link to @stencil/helmet") ------------------------------------------------------------------------------------------------------------------------------------- The `@stencil/helmet` package was a library for managing meta tags dynamically. It has since been deprecated. For additional information regarding this package, please see its [GitHub page](https://github.com/ionic-team/stencil-helmet) Contents -------- * [@stencil/helmet](https://stenciljs.com/docs/v4.33/static-site-generation-meta-tags#stencilhelmet) * * * [Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.33/static-site-generation/meta.md) --- # Methods | Stencil [Skip to main content](https://stenciljs.com/docs/methods#__docusaurus_skipToContent_fallback) [An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none) Version: v4.35 On this page The `@Method()` decorator is used to expose methods on the public API. Functions decorated with the `@Method()` decorator can be called directly from the element, i.e. they are intended to be callable from the outside! note Developers should try to rely on publicly exposed methods as little as possible, and instead default to using properties and events as much as possible. As an app scales, we've found it's easier to manage and pass data through @Prop rather than public methods. import { Method } from '@stencil/core';export class TodoList { @Method() async showPrompt() { // show a prompt }} Call the method like this: note Developers should ensure that the component is defined by using the whenDefined method of the custom element registry before attempting to call public methods. (async () => { await customElements.whenDefined('todo-list'); const todoListElement = document.querySelector('todo-list'); await todoListElement.showPrompt();})(); Public methods must be async[](https://stenciljs.com/docs/methods#public-methods-must-be-async "Direct link to Public methods must be async") ----------------------------------------------------------------------------------------------------------------------------------------------- Stencil's architecture is async at all levels which allows for many performance benefits and ease of use. By ensuring publicly exposed methods using the `@Method` decorator return a promise: * Developers can call methods before the implementation was downloaded without componentOnReady(), which queues the method calls and resolves after the component has finished loading. * Interaction with the component is the same whether it still needs to be lazy-loaded, or is already fully hydrated. * By keeping a component's public API async, apps could move the components transparently to [Web Worker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API) and the API would still be the same. * Returning a promise is only required for publicly exposed methods which have the `@Method` decorator. All other component methods are private to the component and are not required to be async. // VALID: using async@Method()async myMethod() { return 42;}// VALID: using Promise.resolve()@Method()myMethod2() { return Promise.resolve(42);}// VALID: even if it returns nothing, it needs to be async@Method()async myMethod3() { console.log(42);}// INVALID@Method()notOk() { return 42;} Private methods[](https://stenciljs.com/docs/methods#private-methods "Direct link to Private methods") -------------------------------------------------------------------------------------------------------- Non-public methods can still be used to organize the business logic of your component and they do NOT have to return a Promise. class Component { // Since `getData` is not a public method exposed with @Method // it does not need to be async getData() { return this.someData; } render() { return ({this.getData()}
); }}
Contents
--------
* [Public methods must be async](https://stenciljs.com/docs/methods#public-methods-must-be-async)
* [Private methods](https://stenciljs.com/docs/methods#private-methods)
* * *
[Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.35/components/methods.md)
---
# Properties | Stencil
[Skip to main content](https://stenciljs.com/docs/properties#__docusaurus_skipToContent_fallback)
[An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none)
Version: v4.35
On this page
Props are custom attributes/properties exposed publicly on an HTML element. They allow developers to pass data to a component to render or otherwise use.
The Prop Decorator (`@Prop()`)[](https://stenciljs.com/docs/properties#the-prop-decorator-prop "Direct link to the-prop-decorator-prop")
------------------------------------------------------------------------------------------------------------------------------------------
Props are declared on a component using Stencil's `@Prop()` decorator, like so:
// First, we import Prop from '@stencil/core'import { Component, Prop, h } from '@stencil/core';@Component({ tag: 'todo-list',})export class TodoList { // Second, we decorate a class member with @Prop() @Prop() name: string; render() { // Within the component's class, its props are // accessed via `this`. This allows us to render // the value passed to `todo-list` return To-Do List Name: {this.name}
}}
In the example above, `@Prop()` is placed before (decorates) the `name` class member, which is a string. By adding `@Prop()` to `name`, Stencil will expose `name` as an attribute on the element, which can be set wherever the component is used:
{/* Here we use the component in a TSX file */}{this.thingToDo}
; }}
Since `thingToDo` is a prop, we can provide a value for it when we use our `todo-list-item` component. Providing a value to a camelCased prop like `thingToDo` is nearly identical in TSX and HTML.
When we use our component in a TSX file, an attribute uses camelCase:
To-Do List Name: Stencil To Do List
- {/* Below are three Stencil components that are children of `todo-list`, each representing an item on our list */}
- isComplete has a value of - {this.isComplete} - and a typeof value of "{typeof this.isComplete}"
- label has a value of - {this.label} - and a typeof value of "{typeof this.label}"
- thingToDo has a value of - {this.thingToDo} - and a typeof value of "{typeof this.thingToDo}"
- completeMsg has a value of - {this.completeMsg} - and a typeof value of "{typeof this.completeMsg}"
- label has a value of - {this.label} - and a typeof value of "{typeof this.label}"
- thingToDo has a value of - {this.thingToDo} - and a typeof value of "{typeof this.thingToDo}"
The number is {this.aNumber} and the string is {this.aString}
}}
Regardless of if we use this component in HTML or TSX, "The number is 42 and the string is defaultValue" is displayed when no values are passed to our component:
Hello, World! I'm {this.contents[0]}
; }}
In the example above, updating the Prop in place using `this.contents.push('Stencil')` would have no effect. Stencil does not see the change to `this.contents`, since it looks at the _reference_ of the Prop, and sees that it has not changed. This is done for performance reasons. If Stencil had to walk every slot of the array to determine if it changed, it would incur a performance hit. Rather, it is considered better for performance and more idiomatic to re-assign the Prop (in the example above, we use the spread operator).
The same holds for objects as well. Rather than mutating an existing object in-place, a new object should be created using the spread operator. This object will be different-by-reference and therefore will trigger a re-render:
import { Component, Prop, h } from '@stencil/core';export type MyContents = {name: string};@Component({ tag: 'my-component',})export class MyComponent { @Prop({mutable: true}) contents: MyContents; timer: NodeJS.Timer; connectedCallback() { this.timer = setTimeout(() => { // this does not create a new object. when stencil // attempts to see if any of its Props have changed, // it sees the reference to its `contents` Prop is // the same, and will not trigger a render // this.contents.name = 'Stencil'; // this does create a new object, and therefore a // new reference to the Prop. Stencil will pick up // this change and rerender this.contents = {...this.contents, name: 'Stencil'}; // after 3 seconds, the component will re-render due // to the reference change in `this.contents` }, 3000); } disconnectedCallback() { if (this.timer) { clearTimeout(this.timer); } } render() { return Hello, World! I'm {this.contents.name}
; }}
### Reflect Properties Values to Attributes (`reflect`)[](https://stenciljs.com/docs/properties#reflect-properties-values-to-attributes-reflect "Direct link to reflect-properties-values-to-attributes-reflect")
In some cases it may be useful to keep a Prop in sync with an attribute. In this case you can set the `reflect` option in the `@Prop()` decorator to `true`. When a prop is reflected, it will be rendered in the DOM as an HTML attribute.
Take the following component as example:
import { Component, Prop, h } from '@stencil/core';@Component({ tag: 'todo-list-item',})export class ToDoListItem { @Prop({ reflect: false }) isComplete: boolean = false; @Prop({ reflect: true }) timesCompletedInPast: number = 2; @Prop({ reflect: true }) thingToDo: string = "Read Reflect Section of Stencil Docs";}
The component in the example above uses [default values](https://stenciljs.com/docs/properties#default-values)
, and can be used in HTML like so:
randNumbers contains:
) }}
### Updating an object[](https://stenciljs.com/docs/reactive-data#updating-an-object "Direct link to Updating an object")
The spread operator should be used to update objects. As with arrays, mutating an object will not trigger a view update in Stencil. However, using the spread operator and assigning its return value to the `@Prop()` or `@State()` class member being watched will. Below is an example:
import { Component, State, Watch, h } from '@stencil/core';export type NumberContainer = { val: number,}@Component({ tag: 'rand-numbers'})export class RandomNumbers { // We decorate a class member with @State() so that we // can apply @Watch(). This will hold a randomly generated // number. @State() numberContainer: NumberContainer = { val: 0 }; private timer: NodeJS.Timer; // Apply @Watch() for the component's `numberContainer` member. // Whenever `numberContainer` changes, this method will fire. @Watch('numberContainer') watchStateHandler(newValue: NumberContainer, oldValue: NumberContainer) { console.log('The old value of numberContainer is: ', oldValue); console.log('The new value of numberContainer is: ', newValue); } connectedCallback() { this.timer = setInterval(() => { // generate a random whole number const newVal = Math.ceil(Math.random() * 100); /** * This does not create a new object. When stencil * attempts to see if any Watched members have changed, * it sees the reference to its `numberContainer` State is * the same, and will not trigger `@Watch` or are-render */ // this.numberContainer.val = newVal; /** * Using the spread operator, on the other hand, does * create a new object. `numberContainer` is reassigned * using the value returned by the spread operator. * The reference to `numberContainer` has changed, which * will trigger `@Watch` and a re-render */ this.numberContainer = {...this.numberContainer, val: newVal}; }, 1000) } disconnectedCallback() { if (this.timer) { clearInterval(this.timer) } } render() { return - {this.randNumbers.map((num) =>
- {num} )}
numberContainer contains: {this.numberContainer.val}
; }}
Contents
--------
* [Rendering methods](https://stenciljs.com/docs/reactive-data#rendering-methods)
* [The Watch Decorator (`@Watch()`)](https://stenciljs.com/docs/reactive-data#the-watch-decorator-watch)
* [Watching Native HTML Attributes](https://stenciljs.com/docs/reactive-data#watching-native-html-attributes)
* [Handling Arrays and Objects](https://stenciljs.com/docs/reactive-data#handling-arrays-and-objects)
* [Updating Arrays](https://stenciljs.com/docs/reactive-data#updating-arrays)
* [Updating an object](https://stenciljs.com/docs/reactive-data#updating-an-object)
* * *
[Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.35/components/reactive-data.md)
---
# Internal state | Stencil
[Skip to main content](https://stenciljs.com/docs/state#__docusaurus_skipToContent_fallback)
[An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none)
Version: v4.35
On this page
'State' is a general term that refers to the values and objects that are stored on a class or an instance of a class for use now or in the future.
Like a regular TypeScript class, a Stencil component may have one or more internal class members for holding value(s) that make up the component's state. Stencil allows developers to optionally mark class members holding some part of the class's state with the `@State()` decorator to trigger a rerender when the state changes.
The State Decorator (`@State`)[](https://stenciljs.com/docs/state#the-state-decorator-state "Direct link to the-state-decorator-state")
-----------------------------------------------------------------------------------------------------------------------------------------
Stencil provides a decorator to trigger a rerender when certain class members change. A component's class members that should trigger a rerender must be decorated using Stencil's `@State()` decorator, like so:
// First, we import State from '@stencil/core'import { Component, State, h } from '@stencil/core';@Component({ tag: 'current-time',})export class CurrentTime { // Second, we decorate a class member with @State() // When `currentTime` changes, a rerender will be // triggered @State() currentTime: number = Date.now(); render() { // Within the component's class, its members are // accessed via `this`. This allows us to render // the value stored in `currentTime` const time = new Date(this.currentTime).toLocaleTimeString(); return ( {time} ); }}
In the example above, `@State()` is placed before (decorates) the `currentTime` class member, which is a number. This marks `currentTime` so that any time its value changes, the component rerenders.
However, the example above doesn't demonstrate the real power of using `@State`. `@State` members are meant to only be updated within a class, which the example above never does after the initial assignment of `currentTime`. This means that our `current-time` component will never rerender! We fix that in the example below to update `current-time` every 1000 milliseconds (1 second):
import { Component, State, h } from '@stencil/core';@Component({ tag: 'current-time',})export class CurrentTime { timer: number; // `currentTime` is decorated with `@State()`, // as we need to trigger a rerender when its // value changes to show the latest time @State() currentTime: number = Date.now(); connectedCallback() { this.timer = window.setInterval(() => { // the assignment to `this.currentTime` // will trigger a re-render this.currentTime = Date.now(); }, 1000); } disconnectedCallback() { window.clearInterval(this.timer); } render() { const time = new Date(this.currentTime).toLocaleTimeString(); return ( {time} ); }}
The example above makes use of the [connectedCallback() lifecycle method](https://stenciljs.com/docs/component-lifecycle#connectedcallback)
to set `currentTime` to the value of `Date.now()` every 1000 milliseconds (or, every one second). Because the value of `currentTime` changes every second, Stencil calls the `render` function on `current-time`, which pretty-prints the current time.
The example above also makes use of the [disconnectedCallback() lifecycle method](https://stenciljs.com/docs/component-lifecycle#disconnectedcallback)
to properly clean up the timer that was created using `setInterval` in `connectedCallback()`. This isn't necessary for using `@State`, but is a general good practice when using `setInterval`.
When to Use `@State()`?[](https://stenciljs.com/docs/state#when-to-use-state "Direct link to when-to-use-state")
------------------------------------------------------------------------------------------------------------------
`@State()` should be used for all class members that should trigger a rerender when they change. However, not all internal state might need to be decorated with `@State()`. If you know for sure that the value will either not change or that it does not need to trigger a re-rendering, `@State()` is not necessary. It is considered a 'best practice' to only use `@State()` when absolutely necessary. Revisiting our `current-time` component:
import { Component, State, h } from '@stencil/core';@Component({ tag: 'current-time',})export class CurrentTime { // `timer` is not decorated with `@State()`, as // we do not wish to trigger a rerender when its // value changes timer: number; // `currentTime` is decorated with `@State()`, // as we need to trigger a rerender when its // value changes to show the latest time @State() currentTime: number = Date.now(); connectedCallback() { // the assignment to `this.timer` will not // trigger a re-render this.timer = window.setInterval(() => { // the assignment to `this.currentTime` // will trigger a re-render this.currentTime = Date.now(); }, 1000); } disconnectedCallback() { window.clearInterval(this.timer); } render() { const time = new Date(this.currentTime).toLocaleTimeString(); return ( {time} ); }}
Examples[](https://stenciljs.com/docs/state#examples "Direct link to Examples")
---------------------------------------------------------------------------------
### Using `@State()` with `@Listen()`[](https://stenciljs.com/docs/state#using-state-with-listen "Direct link to using-state-with-listen")
This example makes use of `@State` and [`@Listen`](https://stenciljs.com/docs/events#listen-decorator)
decorators. We define a class member called `isOpen` and decorate it with `@State()`. With the use of `@Listen()`, we respond to click events toggling the value of `isOpen`.
import { Component, Listen, State, h } from '@stencil/core';@Component({ tag: 'my-toggle-button'})export class MyToggleButton { // `isOpen` is decorated with `@State()`, // changes to it will trigger a rerender @State() isOpen: boolean = true; @Listen('click', { capture: true }) handleClick() { // whenever a click event occurs on // the component, update `isOpen`, // triggering the rerender this.isOpen = !this.isOpen; } render() { return ; }}
### Complex Types[](https://stenciljs.com/docs/state#complex-types "Direct link to Complex Types")
For more advanced use cases, `@State()` can be used with a complex type. In the example below, we print a list of `Item` entries. Although we start with zero `Item`s initially, we use the same pattern as we did before to add a new `Item` to `ItemList`'s `items` array once every 2000 milliseconds (2 seconds). Every time a new entry is added to `items`, a rerender occurs:
import { Component, State, h } from '@stencil/core';// a user defined, complex type describing an 'Item'type Item = { id: number; description: string,}@Component({ tag: 'item-list',})export class ItemList { // `timer` is not decorated with `@State()`, as // we do not wish to trigger a rerender when its // value changes timer: number; // `items` will trigger a rerender if // the value assigned to the variable changes @State() items: Item[] = []; connectedCallback() { // the assignment to `this.timer` will not // trigger a re-render this.timer = window.setInterval(() => { const newTodo: Item = { description: "Item", id: this.items.length + 1 }; // the assignment to `this.items` will // trigger a re-render. the assignment // using '=' is important here, as we // need that to make sure the rerender // occurs this.items = [...this.items, newTodo]; }, 2000); } disconnectedCallback() { window.clearInterval(this.timer); } render() { return ( To-Do List
- {this.items.map((todo) =>
- {todo.description} #{todo.id} )}
Hello World
This is JSX!
Hello {this.name}
)}
note
If you're familiar with ES6 template variables, JSX variables are very similar, just without the `$`:
//ES6`Hello ${this.name}`//JSXHello {this.name}
Conditionals[](https://stenciljs.com/docs/templating-jsx#conditionals "Direct link to Conditionals")
------------------------------------------------------------------------------------------------------
If we want to conditionally render different content, we can use JavaScript if/else statements: Here, if `name` is not defined, we can just render a different element.
render() { if (this.name) { return ( Hello {this.name}
) } else { return ( Hello, World
) }}
Additionally, inline conditionals can be created using the JavaScript ternary operator:
render() { return ( {this.name ?
);}
**Please note:** Stencil reuses DOM elements for better performance. Consider the following code:
{someCondition ? Hello {this.name}
:Hello World
}A Component
` above:
render(){ return( )}
Slots can also have `name`s to allow for specifying slot output location:
// my-component.tsxrender(){ return [ )}
### Slots Outside Shadow DOM[](https://stenciljs.com/docs/templating-jsx#slots-outside-shadow-dom "Direct link to Slots Outside Shadow DOM")
caution
Slots are native to the [Shadow DOM](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM)
, but Stencil polyfills the behavior to work for non-shadow components as well. However, you may encounter issues using slots outside the Shadow DOM especially with component trees mixing shadow and non-shadow components, or when passing a slot through many levels of components. In many cases, this behavior can be remedied by wrapping the `slot` in an additional element (like a `div` or `span`) so the Stencil runtime can correctly "anchor" the relocated content in its new location.
There are known use cases that the Stencil runtime is not able to support:
* Forwarding slotted content to another slot with a different name:
It is recommended that slot names stay consistent when slotting content through multiple levels of components. **Avoid** defining slot tags like `
Child Element
Here is my main content
,I'll be placed before the h1
I'll be placed after the h1
{this.todos.map((todo) => ( { todo.taskName } )}
{ todos[0].taskName } { todos[1].taskName }
)}
If this array of children is dynamic, i.e., if any nodes may be added, removed, or reordered, then it's a good idea to set a unique `key` attribute on each element like so:
render() { return ( {this.todos.map((todo) => ( ))}
)}
When nodes in a children array are rearranged Stencil makes an effort to preserve DOM nodes across renders but it isn't able to do so in all cases. Setting a `key` attribute lets Stencil ensure it can match up new and old children across renders and thereby avoid recreating DOM nodes unnecessarily.
caution
Do not use an array index or some other non-unique value as a key. Try to ensure that each child has a key which does not change and which is unique among all its siblings.
### Automatic Key Insertion[](https://stenciljs.com/docs/templating-jsx#automatic-key-insertion "Direct link to Automatic Key Insertion")
During compilation Stencil will automatically add key attributes to any JSX nodes in your component's render method which are not nested within curly braces. This allows Stencil’s runtime to accurately reconcile children when their order changes or when a child is conditionally rendered.
For instance, consider a render method looking something like this:
render() { return ( {todo.taskName}
{ this.disabled &&
); }
While it might seem like adding a key attribute to the `#slot-wrapper` div could help ensure that elements will be matched up correctly when the component re-renders, this is actually superfluous because Stencil will automatically add a key to that element when it compiles your component.
note
The Stencil compiler can only safely perform automatic key insertion in certain scenarios where there is no danger of the keys accidentally causing elements to be considered different when they should be treated the same (or vice versa).
In particular, the compiler will not automatically insert `key` attributes if a component's `render` method has more than one `return` statement or if it returns a [conditional expression](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Conditional_operator)
. Additionally, the compiler will not add key attributes to any JSX which is found within curly braces (`{ }`).
Handling User Input[](https://stenciljs.com/docs/templating-jsx#handling-user-input "Direct link to Handling User Input")
---------------------------------------------------------------------------------------------------------------------------
Stencil uses native [DOM events](https://developer.mozilla.org/en-US/docs/Web/Events)
.
Here's an example of handling a button click. Note the use of the [Arrow function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions)
.
...export class MyComponent { private handleClick = () => { alert('Received the button click!'); } render() { return ( ); }}
Here's another example of listening to input `change`. Note the use of the [Arrow function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions)
.
...export class MyComponent { private inputChanged = (event: Event) => { console.log('input changed: ', (event.target as HTMLInputElement).value); } render() { return ( ); }}
Complex Template Content[](https://stenciljs.com/docs/templating-jsx#complex-template-content "Direct link to Complex Template Content")
------------------------------------------------------------------------------------------------------------------------------------------
So far we've seen examples of how to return only a single root element. We can also nest elements inside our root element
In the case where a component has multiple "top level" elements, the `render` function can return an array. Note the comma in between the `no key!
} ` elements.
render() { return ([ // first top level element , // second top level element, note the , above // first top level element );}
It is also possible to use `innerHTML` to inline content straight into an element. This can be helpful when, for example, loading an svg dynamically and then wanting to render that inside of a `div`. This works just like it does in normal HTML:
Getting a reference to a DOM element[](https://stenciljs.com/docs/templating-jsx#getting-a-reference-to-a-dom-element "Direct link to Getting a reference to a DOM element")
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
In cases where you need to get a direct reference to an element, like you would normally do with `document.querySelector`, you might want to use a `ref` in JSX. Lets look at an example of using a `ref` in a form:
@Component({ tag: 'app-home',})export class AppHome { textInput!: HTMLInputElement; handleSubmit = (event: Event) => { event.preventDefault(); console.log(this.textInput.value); } render() { return ( ); }}
In this example we are using `ref` to get a reference to our input `ref={(el) => this.textInput = el as HTMLInputElement}`. We can then use that ref to do things such as grab the value from the text input directly `this.textInput.value`.
Avoid Shared JSX Nodes[](https://stenciljs.com/docs/templating-jsx#avoid-shared-jsx-nodes "Direct link to Avoid Shared JSX Nodes")
------------------------------------------------------------------------------------------------------------------------------------
The renderer caches element lookups in order to improve performance. However, a side effect from this is that the exact same JSX node should not be shared within the same renderer.
In the example below, the `sharedNode` variable is reused multiple times within the `render()` function. The renderer is able to optimize its DOM element lookups by caching the reference, however, this causes issues when nodes are reused. Instead, it's recommended to always generate unique nodes like the changed example below.
@Component({ tag: 'my-cmp',})export class MyCmp { render() {- const sharedNode =
Contents
--------
* [start()](https://stenciljs.com/docs/dev-server-api#start)
* * *
[Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.35/core/dev-server-api.md)
---
# Hydrate App | Stencil
[Skip to main content](https://stenciljs.com/docs/hydrate-app#__docusaurus_skipToContent_fallback)
[An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none)
Version: v4.35
On this page
The hydrate app is a Stencil output target which generates a module that can be used on a NodeJS server to hydrate HTML and implement server side rendering (SSR). This functionality is used internally by the Stencil compiler for prerendering, as well as for the Angular Universal SSR for the Ionic framework. However, like Stencil components, the hydrate app itself is not restricted to one framework.
_Note that Stencil does **NOT** use Puppeteer for SSR or prerendering._
How to Use the Hydrate App[](https://stenciljs.com/docs/hydrate-app#how-to-use-the-hydrate-app "Direct link to How to Use the Hydrate App")
---------------------------------------------------------------------------------------------------------------------------------------------
Server side rendering (SSR) can be accomplished in a similar way to prerendering. Instead of using the `--prerender` CLI flag, you can an output target of type `'dist-hydrate-script'` to your `stencil.config.ts`, like so:
outputTargets: [ { type: 'dist-hydrate-script', },];
This will generate a `hydrate` app in your root project directory that can be imported and used by your Node server.
After publishing your component library, you can import the hydrate app into your server's code like this:
import { createWindowFromHtml, hydrateDocument, renderToString, streamToString } from 'yourpackage/hydrate';
The hydrate app module exports 3 functions, `hydrateDocument`, `renderToString` and `streamToString`. `hydrateDocument` takes a [document](https://developer.mozilla.org/en-US/docs/Web/API/HTMLDocument)
as its input while `renderToString` as well as `streamToString` takes a raw HTML string. While `hydrateDocument` and `renderToString` return a Promise which wraps a result object, `streamToString` returns a [`Readable`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream)
stream that can be passed into a server response.
### hydrateDocument[](https://stenciljs.com/docs/hydrate-app#hydratedocument "Direct link to hydrateDocument")
You can use `hydrateDocument` as a part of your server's response logic before serving the web page. `hydrateDocument` takes two arguments, a [document](https://developer.mozilla.org/en-US/docs/Web/API/HTMLDocument)
and a config object. The function returns a promise with the hydrated results, with the hydrated HTML under the `html` property.
_Example taken from Ionic Angular server_
import { hydrateDocument, createWindowFromHtml } from 'yourpackage/hydrate';export function hydrateComponents(template: string) { const win = createWindowFromHtml(template, Math.random().toString()) return hydrateDocument(win.document) .then((hydrateResults) => { // execute logic based on results console.log(hydrateResults.html); return hydrateResults; });}
You can call the `hydrateComponents` function from your Node.js server, e.g.:
import Koa from 'koa';const app = new Koa();app.use(async (ctx) => { const res = await hydrateComponents(` Document * * * * ``` */
#### renderToString Options[](https://stenciljs.com/docs/hydrate-app#rendertostring-options "Direct link to renderToString Options")
##### `approximateLineWidth`[](https://stenciljs.com/docs/hydrate-app#approximatelinewidth "Direct link to approximatelinewidth")
**Type:** `number`
Determines when line breaks are being set when serializing the component.
##### `prettyHtml`[](https://stenciljs.com/docs/hydrate-app#prettyhtml "Direct link to prettyhtml")
**Default:** `false`
**Type:** `boolean`
If set to `true` it prettifies the serialized HTML code, intends elements and escapes text nodes.
##### `removeAttributeQuotes`[](https://stenciljs.com/docs/hydrate-app#removeattributequotes "Direct link to removeattributequotes")
**Type:** `boolean`
**Default:** `false`
If set to `true` it removes attribute quotes when possible, e.g. replaces `someAttribute="foo"` to `someAttribute=foo`.
##### `removeEmptyAttributes`[](https://stenciljs.com/docs/hydrate-app#removeemptyattributes "Direct link to removeemptyattributes")
**Type:** `boolean`
**Default:** `true`
If set to `true` it removes attribute that don't have values, e.g. remove `class=""`.
##### `removeHtmlComments`[](https://stenciljs.com/docs/hydrate-app#removehtmlcomments "Direct link to removehtmlcomments")
**Type:** `boolean`
**Default:** `false`
If set to `true` it removes any abundant HTML comments. Stencil still requires to insert hydration comments to be able to reconcile the component.
##### `beforeHydrate`[](https://stenciljs.com/docs/hydrate-app#beforehydrate "Direct link to beforehydrate")
**Type:** `(document: Document, url: URL) => | Promise`
Allows to modify the document and all its containing components to be modified before the hydration process starts. This allows e.g. to assign properties to the components dynamically:
await renderToString(response.body, { beforeHydrate: (doc: Document) => { doc.querySelector(`my-component`).someComplexThing = new Map(...) },})
##### `afterHydrate`[](https://stenciljs.com/docs/hydrate-app#afterhydrate "Direct link to afterhydrate")
**Type:** `(document: Document, url: URL, results: PrerenderUrlResults) => | Promise`
Allows to modify the document and all its containing components after the component was rendered in the virtual DOM and before the serialization process starts.
##### `serializeShadowRoot`[](https://stenciljs.com/docs/hydrate-app#serializeshadowroot "Direct link to serializeshadowroot")
**Default:** `'declarative-shadow-dom'`
**Type:**
'declarative-shadow-dom' | 'scoped' | { 'declarative-shadow-dom'?: string[]; scoped?: string[]; default: 'declarative-shadow-dom' | 'scoped';} | false;
Configure how Stencil serializes a component's shadow-root:
* `declarative-shadow-dom` - all `shadow: true` components will be rendered with a [Declarative Shadow DOM](https://developer.chrome.com/docs/css-ui/declarative-shadow-dom)
.
* `scoped` - all `shadow: true` components will be rendered with Stencil's custom scoped behavior; a light-dom tree and single `` during SSR which is converted into a shadow-root during client-side hydration.
* Alternatively you can mix `scoped` and `declarative-shadow-dom` behavior, for example:
* `{ 'declarative-shadow-dom': ['tag-1'], default: 'scoped'; }` will render component `tag-1` with DSD, but all others with Stencil's scoped behavior.
* `{ 'scoped': ['tag-1'], default: 'declarative-shadow-dom'; }` will render component tag `tag-1` with Stencil's scoped behavior, but all others with DSD.
* `false`, will not render any `shadow: true` component on the server; delaying hydration until runtime.
**Declarative Shadow DOM Example:**
const results = await hydrate.renderToString( ` * * * * ``` */
**Scoped Example:**
const results = await hydrate.renderToString( ` * * * * ``` */
##### `fullDocument`[](https://stenciljs.com/docs/hydrate-app#fulldocument "Direct link to fulldocument")
**Type:** `boolean`
**Default:** `true`
If set to `true`, Stencil will serialize a complete HTML document for a server to respond. If set to `false` it will only render the components within the given template.
Contents
--------
* [How to Use the Hydrate App](https://stenciljs.com/docs/hydrate-app#how-to-use-the-hydrate-app)
* [hydrateDocument](https://stenciljs.com/docs/hydrate-app#hydratedocument)
* [renderToString](https://stenciljs.com/docs/hydrate-app#rendertostring)
* * *
[Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.35/guides/hydrate-app.md)
---
# Plugin Config | Stencil
[Skip to main content](https://stenciljs.com/docs/plugins#__docusaurus_skipToContent_fallback)
[An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none)
Version: v4.35
On this page
Stencil plugins[](https://stenciljs.com/docs/plugins#stencil-plugins "Direct link to Stencil plugins")
--------------------------------------------------------------------------------------------------------
By default, Stencil does not come with `Sass` or `PostCSS` support. However, either can be added using the `plugins` array.
import { Config } from '@stencil/core';import { sass } from '@stencil/sass';export const config: Config = { plugins: [ sass() ]};
Rollup plugins[](https://stenciljs.com/docs/plugins#rollup-plugins "Direct link to Rollup plugins")
-----------------------------------------------------------------------------------------------------
The `rollupPlugins` config can be used to add your own [Rollup](https://rollupjs.org/)
plugins. Under the hood, stencil ships with some built-in plugins including `node-resolve` and `commonjs`, since the execution order of rollup plugins is important, stencil provides an API to inject custom plugin **before node-resolve** and after **commonjs transform**:
export const config = { rollupPlugins: { before: [ // Plugins injected before rollupNodeResolve() resolvePlugin() ], after: [ // Plugins injected after commonjs() nodePolyfills() ] }}
### Related Plugins[](https://stenciljs.com/docs/plugins#related-plugins "Direct link to Related Plugins")
* [@stencil/sass](https://www.npmjs.com/package/@stencil/sass)
* [@stencil-community/postcss](https://www.npmjs.com/package/@stencil-community/postcss)
* [@stencil-community/less](https://www.npmjs.com/package/@stencil-community/less)
* (Deprecated) [@stencil/stylus](https://www.npmjs.com/package/@stencil/stylus)
Node Polyfills[](https://stenciljs.com/docs/plugins#node-polyfills "Direct link to Node Polyfills")
-----------------------------------------------------------------------------------------------------
See the [Node Polyfills in Module bundling](https://stenciljs.com/docs/module-bundling#node-polyfills)
for other examples.
Contents
--------
* [Stencil plugins](https://stenciljs.com/docs/plugins#stencil-plugins)
* [Rollup plugins](https://stenciljs.com/docs/plugins#rollup-plugins)
* [Related Plugins](https://stenciljs.com/docs/plugins#related-plugins)
* [Node Polyfills](https://stenciljs.com/docs/plugins#node-polyfills)
* * *
[Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.35/config/plugins.md)
---
# Hydrate App | Stencil
[Skip to main content](https://stenciljs.com/docs/v4.34/hydrate-app#__docusaurus_skipToContent_fallback)
[An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none)
This is documentation for Stencil **v4.34**, which is no longer actively maintained.
For up-to-date documentation, see the **[latest version](https://stenciljs.com/docs/hydrate-app)
** (v4.35).
Version: v4.34
On this page
The hydrate app is a Stencil output target which generates a module that can be used on a NodeJS server to hydrate HTML and implement server side rendering (SSR). This functionality is used internally by the Stencil compiler for prerendering, as well as for the Angular Universal SSR for the Ionic framework. However, like Stencil components, the hydrate app itself is not restricted to one framework.
_Note that Stencil does **NOT** use Puppeteer for SSR or prerendering._
How to Use the Hydrate App[](https://stenciljs.com/docs/v4.34/hydrate-app#how-to-use-the-hydrate-app "Direct link to How to Use the Hydrate App")
---------------------------------------------------------------------------------------------------------------------------------------------------
Server side rendering (SSR) can be accomplished in a similar way to prerendering. Instead of using the `--prerender` CLI flag, you can an output target of type `'dist-hydrate-script'` to your `stencil.config.ts`, like so:
outputTargets: [ { type: 'dist-hydrate-script', },];
This will generate a `hydrate` app in your root project directory that can be imported and used by your Node server.
After publishing your component library, you can import the hydrate app into your server's code like this:
import { createWindowFromHtml, hydrateDocument, renderToString, streamToString } from 'yourpackage/hydrate';
The hydrate app module exports 3 functions, `hydrateDocument`, `renderToString` and `streamToString`. `hydrateDocument` takes a [document](https://developer.mozilla.org/en-US/docs/Web/API/HTMLDocument)
as its input while `renderToString` as well as `streamToString` takes a raw HTML string. While `hydrateDocument` and `renderToString` return a Promise which wraps a result object, `streamToString` returns a [`Readable`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream)
stream that can be passed into a server response.
### hydrateDocument[](https://stenciljs.com/docs/v4.34/hydrate-app#hydratedocument "Direct link to hydrateDocument")
You can use `hydrateDocument` as a part of your server's response logic before serving the web page. `hydrateDocument` takes two arguments, a [document](https://developer.mozilla.org/en-US/docs/Web/API/HTMLDocument)
and a config object. The function returns a promise with the hydrated results, with the hydrated HTML under the `html` property.
_Example taken from Ionic Angular server_
import { hydrateDocument, createWindowFromHtml } from 'yourpackage/hydrate';export function hydrateComponents(template: string) { const win = createWindowFromHtml(template, Math.random().toString()) return hydrateDocument(win.document) .then((hydrateResults) => { // execute logic based on results console.log(hydrateResults.html); return hydrateResults; });}
You can call the `hydrateComponents` function from your Node.js server, e.g.:
import Koa from 'koa';const app = new Koa();app.use(async (ctx) => { const res = await hydrateComponents(` Document * * * * ``` */
#### renderToString Options[](https://stenciljs.com/docs/v4.34/hydrate-app#rendertostring-options "Direct link to renderToString Options")
##### `approximateLineWidth`[](https://stenciljs.com/docs/v4.34/hydrate-app#approximatelinewidth "Direct link to approximatelinewidth")
**Type:** `number`
Determines when line breaks are being set when serializing the component.
##### `prettyHtml`[](https://stenciljs.com/docs/v4.34/hydrate-app#prettyhtml "Direct link to prettyhtml")
**Default:** `false`
**Type:** `boolean`
If set to `true` it prettifies the serialized HTML code, intends elements and escapes text nodes.
##### `removeAttributeQuotes`[](https://stenciljs.com/docs/v4.34/hydrate-app#removeattributequotes "Direct link to removeattributequotes")
**Type:** `boolean`
**Default:** `false`
If set to `true` it removes attribute quotes when possible, e.g. replaces `someAttribute="foo"` to `someAttribute=foo`.
##### `removeEmptyAttributes`[](https://stenciljs.com/docs/v4.34/hydrate-app#removeemptyattributes "Direct link to removeemptyattributes")
**Type:** `boolean`
**Default:** `true`
If set to `true` it removes attribute that don't have values, e.g. remove `class=""`.
##### `removeHtmlComments`[](https://stenciljs.com/docs/v4.34/hydrate-app#removehtmlcomments "Direct link to removehtmlcomments")
**Type:** `boolean`
**Default:** `false`
If set to `true` it removes any abundant HTML comments. Stencil still requires to insert hydration comments to be able to reconcile the component.
##### `beforeHydrate`[](https://stenciljs.com/docs/v4.34/hydrate-app#beforehydrate "Direct link to beforehydrate")
**Type:** `(document: Document, url: URL) => | Promise`
Allows to modify the document and all its containing components to be modified before the hydration process starts. This allows e.g. to assign properties to the components dynamically:
await renderToString(response.body, { beforeHydrate: (doc: Document) => { doc.querySelector(`my-component`).someComplexThing = new Map(...) },})
##### `afterHydrate`[](https://stenciljs.com/docs/v4.34/hydrate-app#afterhydrate "Direct link to afterhydrate")
**Type:** `(document: Document, url: URL, results: PrerenderUrlResults) => | Promise`
Allows to modify the document and all its containing components after the component was rendered in the virtual DOM and before the serialization process starts.
##### `serializeShadowRoot`[](https://stenciljs.com/docs/v4.34/hydrate-app#serializeshadowroot "Direct link to serializeshadowroot")
**Default:** `'declarative-shadow-dom'`
**Type:**
'declarative-shadow-dom' | 'scoped' | { 'declarative-shadow-dom'?: string[]; scoped?: string[]; default: 'declarative-shadow-dom' | 'scoped';} | false;
Configure how Stencil serializes a component's shadow-root:
* `declarative-shadow-dom` - all `shadow: true` components will be rendered with a [Declarative Shadow DOM](https://developer.chrome.com/docs/css-ui/declarative-shadow-dom)
.
* `scoped` - all `shadow: true` components will be rendered with Stencil's custom scoped behavior; a light-dom tree and single `` during SSR which is converted into a shadow-root during client-side hydration.
* Alternatively you can mix `scoped` and `declarative-shadow-dom` behavior, for example:
* `{ 'declarative-shadow-dom': ['tag-1'], default: 'scoped'; }` will render component `tag-1` with DSD, but all others with Stencil's scoped behavior.
* `{ 'scoped': ['tag-1'], default: 'declarative-shadow-dom'; }` will render component tag `tag-1` with Stencil's scoped behavior, but all others with DSD.
* `false`, will not render any `shadow: true` component on the server; delaying hydration until runtime.
**Declarative Shadow DOM Example:**
const results = await hydrate.renderToString( ` * * * * ``` */
**Scoped Example:**
const results = await hydrate.renderToString( ` * * * * ``` */
##### `fullDocument`[](https://stenciljs.com/docs/v4.34/hydrate-app#fulldocument "Direct link to fulldocument")
**Type:** `boolean`
**Default:** `true`
If set to `true`, Stencil will serialize a complete HTML document for a server to respond. If set to `false` it will only render the components within the given template.
Contents
--------
* [How to Use the Hydrate App](https://stenciljs.com/docs/v4.34/hydrate-app#how-to-use-the-hydrate-app)
* [hydrateDocument](https://stenciljs.com/docs/v4.34/hydrate-app#hydratedocument)
* [renderToString](https://stenciljs.com/docs/v4.34/hydrate-app#rendertostring)
* * *
[Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.34/guides/hydrate-app.md)
---
# Storybook Integration | Stencil
[Skip to main content](https://stenciljs.com/docs/storybook#__docusaurus_skipToContent_fallback)
[An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none)
Version: v4.35
On this page
[Storybook](https://storybook.js.org/)
is a powerful tool for developing, testing, and documenting UI components in isolation. It's open-source, widely adopted, and integrates seamlessly with modern frontend frameworks—including Stencil (v2.30.0 and above).
With the latest Stencil version, you can now build and preview your components directly in Storybook.
Getting Started[](https://stenciljs.com/docs/storybook#getting-started "Direct link to Getting Started")
----------------------------------------------------------------------------------------------------------
> 🔧 **Note:** Native support for Stencil in the Storybook CLI is currently in progress ([see pull request](https://github.com/storybookjs/storybook/pull/31205)
> ).
>
> In the meantime, follow this manual setup guide for Storybook Version 8, then optionally run the following command to migrate to Storybook Version 9:
>
> npx storybook@latest upgrade
### Install Dependencies[](https://stenciljs.com/docs/storybook#install-dependencies "Direct link to Install Dependencies")
Add the necessary dev dependencies to your project:
npm install --save-dev storybook@8 @storybook/addon-essentials@8 @storybook/addon-links@8 @storybook/addon-interactions@8 @stencil/core@latest @stencil/storybook-plugin
### Configure Storybook[](https://stenciljs.com/docs/storybook#configure-storybook "Direct link to Configure Storybook")
Create a `.storybook/main.ts` file with the following configuration:
const config = { stories: ["../src/**/*.stories.@(js|jsx|ts|tsx)"], addons: [ "@storybook/addon-links", "@storybook/addon-essentials", "@storybook/addon-interactions", ], framework: { name: "@stencil/storybook-plugin" },};export default config;
By default, the Stencil Storybook plugin registers the component specified via the `component` property in your story. However, if your component depends on other custom elements from your Stencil library, you'll want to ensure those are available too.
To do this, you can embed the [Stencil Loader](https://stenciljs.com/docs/next/distribution#loader)
in the Storybook preview script to **lazily register all components** globally:
// .storybook/preview.tsximport { defineCustomElements } from '../loader/index.js';/** * Registers all custom elements in the Storybook preview. * This is useful if your components rely on other nested Stencil components. */defineCustomElements();
### Adding Global Styles[](https://stenciljs.com/docs/storybook#adding-global-styles "Direct link to Adding Global Styles")
If your components rely on global stylesheets (e.g., a design system or component library), you can include them using a `preview-head.html` file. This file will be injected into the `` of the Storybook preview iframe:
This ensures all your components render correctly with the required styles in place.
### Add a Script[](https://stenciljs.com/docs/storybook#add-a-script "Direct link to Add a Script")
In your `package.json`, add the following Storybook script:
"scripts": { "storybook": "storybook dev -p 6006 --no-open"}
Creating Your First Story[](https://stenciljs.com/docs/storybook#creating-your-first-story "Direct link to Creating Your First Story")
----------------------------------------------------------------------------------------------------------------------------------------
It's recommended to place your story file next to your component for better co-location and discoverability. For example:
src/components/my-component/my-component.stories.tsx
If you prefer a different structure, that's perfectly fine—just make sure your `stories` pattern in `.storybook/main.ts` includes the correct paths.
Here’s an example story for a `MyComponent`:
import type { Meta, StoryObj } from '@stencil/storybook-plugin';import { h } from '@stencil/core';import { MyComponent } from './my-component';const meta: Meta = { title: 'MyComponent', component: MyComponent, parameters: { layout: 'centered', }, argTypes: { first: { control: 'text' }, last: { control: 'text' }, middle: { control: 'text' }, }, args: { first: 'John', last: 'Doe', middle: 'Michael' },};export default meta;type Story = StoryObj;export const Primary: Story = { args: { first: 'John', last: 'Doe', middle: 'Michael', }, render: (props) =>
Stencil provides a `FunctionalComponent` generic type that allows to specify an interface for the component's properties.
// Hello.tsximport { FunctionalComponent, h } from '@stencil/core';interface HelloProps { name: string;}export const Hello: FunctionalComponent = ({ name }) => ( ;
To migrate away from usages of `context`, please see [the original deprecation announcement](https://github.com/ionic-team/stencil/blob/main/BREAKING_CHANGES.md#propcontext)
. To migrate away from usages of `connect`, please see [the original deprecation announcement](https://github.com/ionic-team/stencil/blob/main/BREAKING_CHANGES.md#propconnect)
.
### Legacy Browser Support Removed[](https://stenciljs.com/docs/introduction/upgrading-to-stencil-four#legacy-browser-support-removed "Direct link to Legacy Browser Support Removed")
In Stencil v3.0.0, we announced [the deprecation of IE 11, pre-Chromium Edge, and Safari 10 support](https://github.com/ionic-team/stencil/blob/1a8ff39073a88d1372beaa98434dbe2247f68a85/BREAKING_CHANGES.md?plain=1#L78)
. 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](https://stenciljs.com/docs/support-policy#browser-support)
).
By dropping these browsers, a few configuration options are no longer valid in a Stencil configuration file:
#### `__deprecated__cssVarsShim`[](https://stenciljs.com/docs/introduction/upgrading-to-stencil-four#__deprecated__cssvarsshim "Direct link to __deprecated__cssvarsshim")
The `extras.__deprecated__cssVarsShim` option caused Stencil to include a polyfill for [CSS variables](https://developer.mozilla.org/en-US/docs/Web/CSS/--*)
. This field should be removed from a project's Stencil configuration file (`stencil.config.ts`).
#### `__deprecated__dynamicImportShim`[](https://stenciljs.com/docs/introduction/upgrading-to-stencil-four#__deprecated__dynamicimportshim "Direct link to __deprecated__dynamicimportshim")
The `extras.__deprecated__dynamicImportShim` option caused Stencil to include a polyfill for the [dynamic `import()` function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import)
for use at runtime. This field should be removed from a project's Stencil configuration file (`stencil.config.ts`).
#### `__deprecated__safari10`[](https://stenciljs.com/docs/introduction/upgrading-to-stencil-four#__deprecated__safari10 "Direct link to __deprecated__safari10")
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`).
#### `__deprecated__shadowDomShim`[](https://stenciljs.com/docs/introduction/upgrading-to-stencil-four#__deprecated__shadowdomshim "Direct link to __deprecated__shadowdomshim")
The `extras.__deprecated__shadowDomShim` option would check whether a shim for [shadow DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_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[](https://stenciljs.com/docs/introduction/upgrading-to-stencil-four#legacy-cache-stats-config-flag-removed "Direct link to 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[](https://stenciljs.com/docs/introduction/upgrading-to-stencil-four#drop-node-14-support "Direct link to 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](https://stenciljs.com/docs/support-policy#javascript-runtime)
.
Information Included in `docs-json` Expanded[](https://stenciljs.com/docs/introduction/upgrading-to-stencil-four#information-included-in-docs-json-expanded "Direct link to 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`](https://stenciljs.com/docs/docs-json#supplementalpublictypes)
option for the JSON documentation output target.
### `JsonDocsEvent`[](https://stenciljs.com/docs/introduction/upgrading-to-stencil-four#jsondocsevent "Direct link to 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](https://github.com/ionic-team/ionic-framework/blob/1f0c8049a339e3a77c468ddba243041d08ead0be/core/src/components/modal/modal.tsx#L289-L292)
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`[](https://stenciljs.com/docs/introduction/upgrading-to-stencil-four#jsondocsmethod "Direct link to 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](https://github.com/ionic-team/ionic-framework/blob/1f0c8049a339e3a77c468ddba243041d08ead0be/core/src/components/select/select.tsx#L261-L313)
on the `Select` component in Ionic Framework:
{ "complexType": { "signature": "(event?: UIEvent) => Promise", "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" }}
Additional Packages[](https://stenciljs.com/docs/introduction/upgrading-to-stencil-four#additional-packages "Direct link to 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](https://github.com/ionic-team/stencil-ds-output-targets/releases/tag/%40stencil%2Fangular-output-target%400.7.1) | [GitHub](https://github.com/ionic-team/stencil-ds-output-targets) | [Stencil Doc Site](https://stenciljs.com/docs/angular) |
| `@stencil/sass` | [3.0.4](https://github.com/ionic-team/stencil-sass/releases/tag/v3.0.4) | [GitHub](https://github.com/ionic-team/stencil-sass) | [GitHub README](https://github.com/ionic-team/stencil-sass) |
| `@stencil/store` | [2.0.8](https://github.com/ionic-team/stencil-store/releases/tag/v2.0.8) | [GitHub](https://github.com/ionic-team/stencil-store) | [Stencil Doc Site](https://stenciljs.com/docs/stencil-store) |
| `@stencil/react-output-target` | [0.5.1](https://github.com/ionic-team/stencil-ds-output-targets/releases/tag/%40stencil%2Freact-output-target%400.5.1) | [GitHub](https://github.com/ionic-team/stencil-ds-output-targets) | [Stencil Doc Site](https://stenciljs.com/docs/react) |
| `@stencil/vue-output-target` | [0.8.6](https://github.com/ionic-team/stencil-ds-output-targets/releases/tag/%40stencil%2Fvue-output-target%400.8.6) | [GitHub](https://github.com/ionic-team/stencil-ds-output-targets) | [Stencil Doc Site](https://stenciljs.com/docs/vue) |
Need Help Upgrading?[](https://stenciljs.com/docs/introduction/upgrading-to-stencil-four#need-help-upgrading "Direct link to Need Help Upgrading?")
-----------------------------------------------------------------------------------------------------------------------------------------------------
Be sure to look at the Stencil [v4.0.0 Breaking Changes Guide](https://github.com/ionic-team/stencil/blob/main/BREAKING_CHANGES.md#stencil-v400)
.
If you need help upgrading, please post a thread on the [Stencil Discord](https://chat.stenciljs.com/)
.
Contents
--------
* [Getting Started](https://stenciljs.com/docs/introduction/upgrading-to-stencil-four#getting-started)
* [Updating Your Code](https://stenciljs.com/docs/introduction/upgrading-to-stencil-four#updating-your-code)
* [New Configuration Defaults](https://stenciljs.com/docs/introduction/upgrading-to-stencil-four#new-configuration-defaults)
* [In Browser Compilation Support Removed](https://stenciljs.com/docs/introduction/upgrading-to-stencil-four#in-browser-compilation-support-removed)
* [Legacy Context and Connect APIs Removed](https://stenciljs.com/docs/introduction/upgrading-to-stencil-four#legacy-context-and-connect-apis-removed)
* [Legacy Browser Support Removed](https://stenciljs.com/docs/introduction/upgrading-to-stencil-four#legacy-browser-support-removed)
* [Legacy Cache Stats Config Flag Removed](https://stenciljs.com/docs/introduction/upgrading-to-stencil-four#legacy-cache-stats-config-flag-removed)
* [Drop Node 14 Support](https://stenciljs.com/docs/introduction/upgrading-to-stencil-four#drop-node-14-support)
* [Information Included in `docs-json` Expanded](https://stenciljs.com/docs/introduction/upgrading-to-stencil-four#information-included-in-docs-json-expanded)
* [`JsonDocsEvent`](https://stenciljs.com/docs/introduction/upgrading-to-stencil-four#jsondocsevent)
* [`JsonDocsMethod`](https://stenciljs.com/docs/introduction/upgrading-to-stencil-four#jsondocsmethod)
* [Additional Packages](https://stenciljs.com/docs/introduction/upgrading-to-stencil-four#additional-packages)
* [Need Help Upgrading?](https://stenciljs.com/docs/introduction/upgrading-to-stencil-four#need-help-upgrading)
* * *
[Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.35/introduction/upgrading-to-stencil-four.md)
---
# WebdriverIO Overview | Stencil
[Skip to main content](https://stenciljs.com/docs/v4.33/testing/webdriverio/overview#__docusaurus_skipToContent_fallback)
[An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none)
This is documentation for Stencil **v4.33**, which is no longer actively maintained.
For up-to-date documentation, see the **[latest version](https://stenciljs.com/docs/testing/webdriverio/overview)
** (v4.35).
Version: v4.33
On this page
WebdriverIO is a progressive automation framework built to automate modern web and mobile applications. It simplifies the interaction with your project and provides a set of plugins that help you create a scalable, robust and stable test suite.
Testing with WebdriverIO has the following advantages:
* **Cross Browser Support**: WebdriverIO is designed to support all platforms, either on desktop or mobile. You can run tests on actual browser your users are using, including covering different versions of them.
* **Real User Interaction**: Interaction with elements in WebdriverIO through the WebDriver protocol is much closer to native user-triggered interactions than what can be achieved with emulated DOM environments (such as JSDom or Stencil's own Mock-Doc).
* **Web Platform Support**: Running tests in actual browsers allows you to tap into the latest Web Platform features for testing your components, often not available when using virtual DOM environments.
* **Real Environments**: Run your tests in an environment that your users are using and not somewhere that re-implements web standards with polyfills like JSDOM.
Set Up[](https://stenciljs.com/docs/v4.33/testing/webdriverio/overview#set-up "Direct link to Set Up")
--------------------------------------------------------------------------------------------------------
To get started with WebdriverIO, all you need to do is to run their project starter:
* npm
* Yarn
* pnpm
npm init wdio@latest .
yarn create wdio@latest .
pnpm create wdio@latest .
This will initiate WebdriverIO's configuration wizard that walks you through the setup. Make sure you select the following options when walking through it:
* **What type of testing would you like to do?** Select either:
* `Component or Unit Testing - in the browser` if you are interested adding unit tests for your components
* `E2E Testing - of Web or Mobile Applications` if you like to test your whole applicationYou can always add either of them later on
* **Which framework do you use for building components?**: if you select _Component or Unit Testing_ make sure to select `StencilJS` as preset so WebdriverIO knows how to compile your components properly
The following questions can be answered as desired. Once setup the wizard has created a `wdio.conf.ts` file and a `wdio` script to run your tests.
CJS vs. ESM
WebdriverIO's generated config and test files use ESM syntax for imports. If you generated a project via the [`create-stencil`](https://www.npmjs.com/package/create-stencil)
starter package your project is likely setup for CommonJS. To avoid any incompatibility issues, we recommend to rename your `wdio.conf.ts` to `wdio.conf.mts` and update the `wdio` script in your `package.json`.
Type Clashes
It's possible that you run into TypeScript issues as WebdriverIO uses Mocha for component testing and Stencil Jest. Both register the same globals, e.g. `it` which causes type clashes. To fix these we recommend to add the following to your `tsconfig.json`:
"types": ["jest"]
This will ensure that Jest types will be preferred.
You should be able to run your first test on the auto-generated test file via:
* npm
* Yarn
* pnpm
npm run wdio
yarn wdio
pnpm run wdio
More information on setting up WebdriverIO can be found in their [documentation](https://webdriver.io/docs/component-testing/stencil)
.
Integration with Stencil[](https://stenciljs.com/docs/v4.33/testing/webdriverio/overview#integration-with-stencil "Direct link to Integration with Stencil")
--------------------------------------------------------------------------------------------------------------------------------------------------------------
If you have been using Stencil's test runner for unit or end-to-end tests to can continue to do so. For basic implementation details that don't require any web platform features, running tests through the Stencil test runner might still be the faster choice, since no browser needs to be spawned. However you can also migrate over to only one single framework one test at a time.
We recommend to create a new NPM script for running both, Stencil and WebdriverIO tests, starting with Stencil tests first as they are likely to run faster. In your `package.json` this can be structured like so:
package.json
{ "scripts:": { "test.e2e": "stencil test && wdio run wdio.conf.ts" }}
Make sure that each test runner picks up their respective tests by defining the `testRegex` property in your Stencil config, e.g.:
stencil.config.ts
import { Config } from '@stencil/core';export const config: Config = { // ... testing: { testRegex: '(/__tests__/.*|\\.?(spec))\\.(ts|js)$', },};
This will make Stencil pick up all files ending with `.spec.ts` or `.spec.js` while WebdriverIO picks up tests ending with `.test.ts`.
Contents
--------
* [Set Up](https://stenciljs.com/docs/v4.33/testing/webdriverio/overview#set-up)
* [Integration with Stencil](https://stenciljs.com/docs/v4.33/testing/webdriverio/overview#integration-with-stencil)
* * *
[Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.33/testing/webdriverio/01-overview.md)
---
# Vitest | Stencil
[Skip to main content](https://stenciljs.com/docs/v4.33/testing/vitest#__docusaurus_skipToContent_fallback)
[An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none)
This is documentation for Stencil **v4.33**, which is no longer actively maintained.
For up-to-date documentation, see the **[latest version](https://stenciljs.com/docs/testing/vitest)
** (v4.35).
Version: v4.33
On this page
[Vitest](https://vitest.dev/)
is a popular and modern test framework for unit testing. You can use Vitest to test Stencil components in the browser using its [browser mode feature](https://vitest.dev/guide/browser.html)
.
caution
Vitest browser mode is an experimental feature and in early development. As such, it may not yet be fully optimized, and there may be some bugs or issues that have not yet been ironed out.
Set Up[](https://stenciljs.com/docs/v4.33/testing/vitest#set-up "Direct link to Set Up")
------------------------------------------------------------------------------------------
To get started with Vitest, all you need to install it via:
* npm
* Yarn
* pnpm
npm install vitest @vitest/browser unplugin-stencil webdriverio
yarn add vitest @vitest/browser unplugin-stencil webdriverio
pnpm add vitest @vitest/browser unplugin-stencil webdriverio
This command installs:
* `vitest`: the core test framework
* `@vitest/browser`: enables testing in browser environments
* `unplugin-stencil`: integrates Stencil's compiler with Vitest for seamless testing
* `webdriverio`: facilitates browser management for tests
Next, we create a Vitest configuration as following:
vitest.config.ts
import stencil from 'unplugin-stencil/vite'import { defineConfig } from 'vitest/config'export default defineConfig({ test: { browser: { enabled: true, headless: true, name: 'chrome' }, }, plugins: [stencil()]})
This configuration enables tests to run in a headless Chrome browser.
Writing Tests[](https://stenciljs.com/docs/v4.33/testing/vitest#writing-tests "Direct link to Writing Tests")
---------------------------------------------------------------------------------------------------------------
Once you've setup Vitest you can start write your first test. In order to render a Stencil component into the browser, all you need to do is import the component and initiate an instance of the component on the page:
src/components/my-component/my-component.test.ts
import { expect, test } from 'vitest'import '../src/components/my-component/my-component.js'test('should render component correctly', async () => { const cmp = document.createElement('my-component') cmp.setAttribute('first', 'Stencil') cmp.setAttribute('last', `'Don't call me a framework' JS`) document.body.appendChild(cmp) await new Promise((resolve) => requestIdleCallback(resolve)) expect(cmp.shadowRoot?.querySelector('div')?.innerText) .toBe(`Hello, World! I'm Stencil 'Don't call me a framework' JS`)})
Lastly, let's add a Vitest script to our `package.json`:
{ "scripts": { "test": "vitest --run" },}
Execute the tests using:
* npm
* Yarn
* pnpm
npm test
yarn test
pnpm test
Expected output:
❯ npm test> [email protected] test> vitest --runThe CJS build of Vite's Node API is deprecated. See https://vitejs.dev/guide/troubleshooting.html#vite-cjs-node-api-deprecated for more details. RUN v1.5.0 /private/tmp/vitest Browser runner started at http://localhost:5173/[19:39.9] build, vitest, prod mode, started ...[19:39.9] transpile started ...[19:40.0] transpile finished in 72 ms[19:40.0] generate custom elements + source maps started ...[19:40.1] generate custom elements + source maps finished in 137 ms[19:40.1] build finished in 227 ms ✓ src/components/my-component/my-component.test.ts (1) ✓ should render component correctly Test Files 1 passed (1) Tests 1 passed (1) Start at 14:19:36 Duration 3.19s (transform 0ms, setup 0ms, collect 721ms, tests 22ms, environment 0ms, prepare 0ms)
### Use JSX[](https://stenciljs.com/docs/v4.33/testing/vitest#use-jsx "Direct link to Use JSX")
The example above creates the Stencil instance using basic DOM primitives. If you prefer to use JSX also for rendering Stencil components in your test, just create a `jsx.ts` utility file with the following content:
src/utils/jsx.ts
export const createElement = (tag, props, ...children) => { if (typeof tag === 'function') { return tag(props, ...children) } const element = document.createElement(tag) Object.entries(props || {}).forEach(([name, value]) => { if (name.startsWith('on') && name.toLowerCase() in window) { element.addEventListener(name.toLowerCase().substr(2), value) } else { element.setAttribute(name, value.toString()) } }) children.forEach((child) => { appendChild(element, child) }) return element}export const appendChild = (parent, child) => { if (Array.isArray(child)) { child.forEach((nestedChild) => appendChild(parent, nestedChild)) } else { parent.appendChild(child.nodeType ? child : document.createTextNode(child)) }}export const createFragment = (_, ...children) => { return children}
Now update your test, import the `createElement` method and tell the JSX engine to use that method for rendering the JSX snippet. Our test should look as follows:
src/components/my-component/my-component.test.tsx
/** @jsx createElement */import { expect, test } from 'vitest'import { createElement } from '../../utils/jsx'import './my-component.js'test('should render the component with jsx', async () => { const cmp = >export const withSSR = (nextConfig: NextConfig): NextConfig => { return stencilConfig({ from: '@placid/react', module: import('./components.js'), hydrateModule: import('@placid/core/hydrate'), })(nextConfig)}
Then expose framework-specific helpers through clean export paths:
packages/react/package.json
{ "name": "@your-company/react", "exports": { ".": { "import": "./dist/components.js", "types": "./dist/components.d.ts" }, "./next": { "import": "./dist/next.js", "types": "./dist/next.d.ts" }, "./vite": { "import": "./dist/vite.js", "types": "./dist/vite.d.ts" }, "./server": { "import": "./dist/components.server.js", "types": "./dist/components.server.d.ts" } }, "dependencies": { "@your-company/core": "workspace:*", "@stencil/react-output-target": "^1.0.3", "@stencil/ssr": "^0.1.1" }}
**Note:** the exports path `./next` and `./vite` export above example for either Vite or Next.js based setups.
With this approach, consumers have a much cleaner experience:
next.config.mjs
import { withSSR } from '@your-company/react/next';const nextConfig = { // your existing Next.js configuration};export default withSSR(nextConfig);
Limitations[](https://stenciljs.com/docs/server-side-rendering#limitations "Direct link to Limitations")
----------------------------------------------------------------------------------------------------------
When server-side rendering Stencil components, there are a few potential pitfalls and limitations you might encounter. To help you avoid these issues, here are some key tips and best practices.
### Performance[](https://stenciljs.com/docs/server-side-rendering#performance "Direct link to Performance")
By default Stencil server-side renders a component into a [Declarative Shadow DOM](https://web.dev/articles/declarative-shadow-dom)
, which includes all structural information and styles. While this ensures accurate rendering, it can significantly increase document size if not managed carefully.
For example, consider a button component:
import { Component, Fragment, h } from '@stencil/core'@Component({ tag: 'my-btn', styleUrl: './button.css'})export class MyBtn { render() { return ( <> ); }}
And this `button.css` which imports additional common styles:
/* button.css */@import "../css/base.css";@import "../css/tokens.css";@import "../css/animations.css";@import "../css/utilities.css";/* component-specific styles */button { ...}
When SSR is performed, the entire CSS (including imports) is bundled with the component's declarative shadow DOM. Rendering multiple instances of this button in SSR can lead to repeated inclusion of styles, bloating the document size and delaying [First Contentful Paint (FCP)](https://web.dev/articles/fcp)
.
Here are some ways to mitigate this:
* **Use CSS Variables**: CSS variables can pierce the Shadow DOM, reducing the need for redundant styles.
* **Use the `::part` pseudo-element**: This allows you to style parts of the Shadow DOM from outside the component, minimizing the internal CSS.
* **Optimize Component-Specific CSS**: Only include the necessary styles for each component.
* **Limit SSR Scope**: In Next.js, apply `use client` to sections that don't need SSR to reduce unnecessary rendering.
Compared to many other web-component frameworks Stencil understands to render a component as actual web component as well as a scoped component. A scoped component doesn't use a Shadow DOM and style encapsulation is emulated. This provides an advantage in the SSR context as you don't have to ship the same styles multiple times when you render specific components in different places.
With the `serializeShadowRoot` of the `@stencil/ssr` package you can define which components should be rendered as actual web-component in a declarative shadow DOM and which should be rendered as a scoped component. You can define certain components that appear a lot in your initial DOM as scoped components to avoid sending duplicate styles for them, e.g.:
next.config.js
import stencilSSR from '@stencil/ssr/next';/** @type {import('next').NextConfig} */const nextConfig = { // ...};export default stencilSSR({ module: import('component-library-react'), from: 'component-library-react', hydrateModule: import('component-library/hydrate'), serializeShadowRoot: { /** * By default all Stencil components are rendered with a Declarative Shadow DOM */ default: 'declarative-shadow-dom', /** * However, you can define a set of components that will be rendered in scoped mode, * allowing to send only one set of styles that are applied to all components. */ scoped: ['my-button'], },})(nextConfig);
Once the Stencil runtime activates, it transforms the scoped component back into a classic web component with a Shadow-DOM and reformats its styles.
### Avoid Non-Primitive Parameters[](https://stenciljs.com/docs/server-side-rendering#avoid-non-primitive-parameters "Direct link to Avoid Non-Primitive Parameters")
When building components, it's common to pass complex data structures like objects to components as props. For example, a footer menu could be structured as an object rather than as separate components for each menu item:
const menu = generateMenuData({ ... })return ( )
While this approach works fine in the browser, it poses challenges for SSR. While Stencil generally **supports** the serialization of complex objects within parameters, it can't resolve the value of any function calls, e.g. here `generateMenuData(...)` during the SSR process (except when using runtime based SSR within Next.js applications).
We recommend to **not** depend on external data structures when it comes to rendering Stencil components.
### Cross-Component State Handling[](https://stenciljs.com/docs/server-side-rendering#cross-component-state-handling "Direct link to Cross-Component State Handling")
When propagating state between parent and child components, patterns like reducers or context providers (as in React) are often used. However, this can be problematic with SSR in frameworks like Next.js, where each component is rendered independently.
Consider the following structure:
When ParentComponent is rendered on the server, Stencil will attempt to stringify its children (e.g., ChildComponent) for the light DOM. The intermediate markup may look like this:
...
At this stage, ParentComponent can access and manipulate its children. However, when ChildComponent is rendered in isolation, it won't have access to the parent's state or context, potentially leading to inconsistencies.
To prevent this, ensure that components rendered on the server don't depend on external state or context. If the component relies on data fetched at runtime, it's better to display a loading placeholder during SSR.
Contents
--------
* [Hydrate Module](https://stenciljs.com/docs/server-side-rendering#hydrate-module)
* [Two SSR Approaches](https://stenciljs.com/docs/server-side-rendering#two-ssr-approaches)
* [Strategy 1: The Compiler Approach (Universal SSR)](https://stenciljs.com/docs/server-side-rendering#strategy-1-the-compiler-approach-universal-ssr)
* [Strategy 2: The Runtime Approach (Next.js Server Components)](https://stenciljs.com/docs/server-side-rendering#strategy-2-the-runtime-approach-nextjs-server-components)
* [Choosing Your Strategy](https://stenciljs.com/docs/server-side-rendering#choosing-your-strategy)
* [Enable SSR for StencilJS](https://stenciljs.com/docs/server-side-rendering#enable-ssr-for-stenciljs)
* [Vite](https://stenciljs.com/docs/server-side-rendering#vite)
* [Next.js](https://stenciljs.com/docs/server-side-rendering#nextjs)
* [Nuxt](https://stenciljs.com/docs/server-side-rendering#nuxt)
* [Custom Config Wrapper](https://stenciljs.com/docs/server-side-rendering#custom-config-wrapper)
* [Limitations](https://stenciljs.com/docs/server-side-rendering#limitations)
* [Performance](https://stenciljs.com/docs/server-side-rendering#performance)
* [Avoid Non-Primitive Parameters](https://stenciljs.com/docs/server-side-rendering#avoid-non-primitive-parameters)
* [Cross-Component State Handling](https://stenciljs.com/docs/server-side-rendering#cross-component-state-handling)
* * *
[Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.35/guides/server-side-rendering.md)
---
# React Integration with Stencil | Stencil
[Skip to main content](https://stenciljs.com/docs/react#__docusaurus_skipToContent_fallback)
[An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none)
Version: v4.35
On this page
**Supports: React v17+ • TypeScript v5+ • Stencil v4.2.0+**
Automate the creation of React component wrappers for your Stencil web components.
This package includes an output target for code generation that allows developers to generate a React component wrapper for each Stencil component and a minimal runtime package built around [@lit/react](https://www.npmjs.com/package/@lit/react)
that is required to use the generated React components in your React library or application.
* ♻️ Automate the generation of React component wrappers for Stencil components
* 🌐 Generate React functional component wrappers with JSX bindings for custom events and properties
* ⌨️ Typings and auto-completion for React components in your IDE
* 🚀 Support for Server Side Rendering (SSR) when used with frameworks like [Next.js](https://nextjs.org/)
To generate these framework wrappers, Stencil provides an Output Target library called [`@stencil/react-output-target`](https://www.npmjs.com/package/@stencil/react-output-target)
that can be added to your `stencil.config.ts` file. This also enables Stencil components to be used within e.g. Next.js or other React based application frameworks.
Setup[](https://stenciljs.com/docs/react#setup "Direct link to Setup")
------------------------------------------------------------------------
### Project Structure[](https://stenciljs.com/docs/react#project-structure "Direct link to Project Structure")
We recommend using a [monorepo](https://www.toptal.com/front-end/guide-to-monorepos)
structure for your component library with component wrappers. Your project workspace should contain your Stencil component library and the library for the generated React component wrappers.
An example project set-up may look similar to:
top-most-directory/└── packages/ ├── stencil-library/ │ ├── stencil.config.js │ └── src/components/ └── react-library/ └── src/ ├── components/ └── index.ts
This guide uses Lerna for the monorepo, but you can use other solutions such as Nx, Turborepo, etc.
To use Lerna with this walk through, globally install Lerna:
* npm
* Yarn
* pnpm
npm install --global lerna
yarn global add lerna
pnpm add --global lerna
#### Creating a Monorepo[](https://stenciljs.com/docs/react#creating-a-monorepo "Direct link to Creating a Monorepo")
note
If you already have a monorepo, skip this section.
* npm
* Yarn
* pnpm
# From your top-most-directory/, initialize a workspacelerna init# install dependenciesnpm install# install typescript and node typesnpm install typescript @types/node --save-dev
# From your top-most-directory/, initialize a workspacelerna init# install dependenciesyarn install# install typescript and node typesyarn add typescript @types/node --dev
# From your top-most-directory/, initialize a workspacelerna init# install dependenciespnpm install# install typescript and node typespnpm add typescript @types/node --save-dev
#### Creating a Stencil Component Library[](https://stenciljs.com/docs/react#creating-a-stencil-component-library "Direct link to Creating a Stencil Component Library")
note
If you already have a Stencil component library, skip this section.
From the `packages/` directory, run the following commands to create a Stencil component library:
* npm
* Yarn
* pnpm
npm init stencil components stencil-librarycd stencil-library# Install dependenciesnpm install
yarn create stencil components stencil-librarycd stencil-library# Install dependenciesyarn install
pnpm create stencil components stencil-librarycd stencil-library# Install dependenciespnpm install
##### Component Imports[](https://stenciljs.com/docs/react#component-imports "Direct link to Component Imports")
If you encounter import errors in your `components.ts` file, update the Stencil library's `package.json` to include comprehensive exports:
package.json
"exports": { ".": { "import": "./dist/stencil-library/stencil-library.esm.js", "require": "./dist/stencil-library/stencil-library.cjs.js" }, "./dist/*": { "import": "./dist/*", "types": "./dist/*" }, "./components/*": { "import": "./dist/components/*.js", "types": "./dist/components/*.d.ts" }, "./loader": { "import": "./loader/index.js", "require": "./loader/index.cjs", "types": "./loader/index.d.ts" }}
#### Creating a React Component Library[](https://stenciljs.com/docs/react#creating-a-react-component-library "Direct link to Creating a React Component Library")
note
If you already have a React component library, skip this section.
The first time you want to create the component wrappers, you will need to have a React library package to write to.
Run the following commands from the root directory of your monorepo to create a React component library:
* npm
* Yarn
* pnpm
# Create a projectlerna create react-library # fill out the prompts accordinglycd packages/react-library# Install core dependenciesnpm install react react-dom typescript @types/react --save-dev# Install output target runtime dependencynpm install @stencil/react-output-target --save
# Create a projectlerna create react-library # fill out the prompts accordinglycd packages/react-library# Install core dependenciesyarn add react react-dom typescript @types/react --dev# Install output target runtime dependencyyarn add @stencil/react-output-target
# Create a projectlerna create react-library # fill out the prompts accordinglycd packages/react-library# Install core dependenciespnpm add react react-dom typescript @types/react --save-dev# Install output target runtime dependencypnpm add @stencil/react-output-target
Lerna does not ship with a TypeScript configuration. At the root of the workspace, create a `tsconfig.json`:
tsconfig.json
{ "compilerOptions": { "module": "commonjs", "declaration": true, "noImplicitAny": false, "removeComments": true, "noLib": false, "emitDecoratorMetadata": true, "experimentalDecorators": true, "target": "es6", "sourceMap": true, "lib": ["es6"] }, "exclude": ["node_modules", "**/*.spec.ts", "**/__tests__/**"]}
In your `react-library` project, create a project specific `tsconfig.json` that will extend the root config:
packages/react-library/tsconfig.json
{ "extends": "../../tsconfig.json", "compilerOptions": { "outDir": "./dist", "target": "ES2020", "useDefineForClassFields": true, "lib": ["ES2020", "DOM", "DOM.Iterable"], "module": "ESNext", "moduleResolution": "bundler", "skipLibCheck": true, "jsx": "react", "allowSyntheticDefaultImports": true, "declarationDir": "./dist/types" }, "include": ["lib"], "exclude": ["node_modules"]}
Update the generated `package.json` in your `react-library`, adding the following options to the existing config:
packages/react-library/package.json
{- "main": "lib/react-library.js",+ "main": "dist/index.js",+ "module": "dist/index.js",+ "types": "dist/types/index.d.ts", "scripts": {- "test": "node ./__tests__/react-library.test.js"+ "test": "node ./__tests__/react-library.test.js",+ "build": "npm run tsc",+ "tsc": "tsc -p . --outDir ./dist"- }+ }, "files": [- "lib"+ "dist" ],+ "publishConfig": {+ "access": "public"+ },+ "dependencies": {+ "stencil-library": "*"+ }}
note
The `stencil-library` dependency is how Lerna knows to resolve the internal Stencil library dependency. See Lerna's documentation on [package dependency management](https://lerna.js.org/docs/getting-started#package-dependency-management)
for more information.
### Adding the React Output Target[](https://stenciljs.com/docs/react#adding-the-react-output-target "Direct link to Adding the React Output Target")
#### Step 1 - Stencil Component Library[](https://stenciljs.com/docs/react#step-1---stencil-component-library "Direct link to Step 1 - Stencil Component Library")
Install the `@stencil/react-output-target` dependency to your Stencil component library package.
* npm
* Yarn
* pnpm
# Install dependencynpm install @stencil/react-output-target --save-dev
# Install dependencyyarn add @stencil/react-output-target --dev
# Install dependencypnpm add @stencil/react-output-target --save-dev
In your project's `stencil.config.ts`, add the `reactOutputTarget` configuration to the `outputTargets` array:
stencil.config.ts
import { reactOutputTarget } from '@stencil/react-output-target';export const config: Config = { namespace: 'stencil-library', outputTargets: [ reactOutputTarget({ // Relative path to where the React components will be generated outDir: '../react-library/lib/components/stencil-generated/', }), // dist-custom-elements output target is required for the React output target { type: 'dist-custom-elements' }, ],};
tip
The `outDir` is the relative path to the file that will be generated with all of the React component wrappers. You will replace the file path to match your project's structure and respective names.
See the [API section below](https://stenciljs.com/docs/react#api)
for details on each of the output target's options.
note
In order to compile Stencil components optimized for server side rendering in e.g. Next.js applications that use [AppRouter](https://nextjs.org/docs/app)
, make sure to provide the [`hydrateModule`](https://stenciljs.com/docs/react#hydratemodule)
property to the output target configuration.
You can now build your Stencil component library to generate the component wrappers.
* npm
* Yarn
* pnpm
# Build the library and wrappersnpm run build
# Build the library and wrappersyarn build
# Build the library and wrapperspnpm run build
If the build is successful, you’ll see the new generated file in your React component library at the location specified by the `outDir` argument.
#### Step 2 - React Component Library[](https://stenciljs.com/docs/react#step-2---react-component-library "Direct link to Step 2 - React Component Library")
Install the `@stencil/react-output-target` dependency to your React component library package. This step is required to add the runtime dependencies required to use the generated React components.
* npm
* Yarn
* pnpm
# Install dependencynpm install @stencil/react-output-target --save
# Install dependencyyarn add @stencil/react-output-target
# Install dependencypnpm add @stencil/react-output-target
Verify or update your `tsconfig.json` file to include the following settings:
{ "compilerOptions": { "module": "esnext", "moduleResolution": "bundler" }}
info
`moduleResolution": "bundler"` is required to resolve the secondary entry points in the `@stencil/react-output-target` runtime package. You can learn more about this setting in the [TypeScript documentation](https://www.typescriptlang.org/docs/handbook/modules/theory.html#module-resolution)
.
Verify or install TypeScript v5.0 or later in your project:
* npm
* Yarn
* pnpm
# Install dependencynpm install typescript@5 --save-dev
# Install dependencyyarn add typescript@5 --dev
# Install dependencypnpm add typescript@5 --save-dev
No additional configuration is needed in the React component library. The generated component wrappers will reference the runtime dependencies directly.
### Add the Components to your React Component Library's Entry File[](https://stenciljs.com/docs/react#add-the-components-to-your-react-component-librarys-entry-file "Direct link to Add the Components to your React Component Library's Entry File")
In order to make the generated files available within your React component library and its consumers, you’ll need to export everything from within your entry file. First, rename `react-library.js` to `index.ts`. Then, modify the contents to match the following:
packages/react-library/src/index.ts
export * from './components/stencil-generated/components';
### Link Your Packages (Optional)[](https://stenciljs.com/docs/react#link-your-packages-optional "Direct link to Link Your Packages (Optional)")
note
If you are using a monorepo tool (Lerna, Nx, etc.), skip this section.
Before you can successfully build a local version of your React component library, you will need to link the Stencil package to the React package.
From your Stencil project's directory, run the following command:
* npm
* Yarn
* pnpm
# Link the working directorynpm link
# Link the working directoryyarn link
# Link the working directorypnpm link
From your React component library's directory, run the following command:
* npm
* Yarn
* pnpm
# Link the package namenpm link name-of-your-stencil-package
# Link the package nameyarn link name-of-your-stencil-package
# Link the package namepnpm link name-of-your-stencil-package
The name of your Stencil package should match the `name` property from the Stencil component library's `package.json`.
Your component libraries are now linked together. You can make changes in the Stencil component library and run `npm run build` to propagate the changes to the React component library.
tip
As an alternative to `npm link` , you can also run `npm install` with a relative path to your Stencil component library. This strategy, however, will modify your `package.json` so it is important to make sure you do not commit those changes.
Consumer Usage[](https://stenciljs.com/docs/react#consumer-usage "Direct link to Consumer Usage")
---------------------------------------------------------------------------------------------------
### Creating a Consumer React App[](https://stenciljs.com/docs/react#creating-a-consumer-react-app "Direct link to Creating a Consumer React App")
note
If you already have a React app, skip this section.
From the `packages/` directory, run the following commands to create a starter React app:
# Create the React appnpm create vite@latest my-app -- --template react-ts# of if using yarnyarn create vite my-app --template react-tscd ./my-app# install dependenciesnpm install# or if using yarnyarn install
You'll also need to link your React component library as a dependency. This step makes it so your React app will be able to correctly resolve imports from your React library. This is easily done by modifying your React app's `package.json` to include the following:
"dependencies": { "react-library": "*"}
### Consuming the React Wrapper Components[](https://stenciljs.com/docs/react#consuming-the-react-wrapper-components "Direct link to Consuming the React Wrapper Components")
This section covers how developers consuming your React component wrappers will use your package and component wrappers.
Before you can consume your React component wrappers, you'll need to build your React component library. From `packages/react-library` run:
* npm
* Yarn
* pnpm
npm run build
yarn build
pnpm run build
To make use of your React component library in your React application, import your components from your React component library in the file where you want to use them.
App.tsx
import './App.css';import { MyComponent } from 'react-library';function App() { return ( ; async onAction() { await this.myTestComponent.nativeElement.testComponentMethod(); }}
### Why aren't my custom interfaces exported from within the index.d.ts file?[](https://stenciljs.com/docs/angular#why-arent-my-custom-interfaces-exported-from-within-the-indexdts-file "Direct link to Why aren't my custom interfaces exported from within the index.d.ts file?")
Usually when beginning this process, you may bump into a situation where you find that some of the interfaces you've used in your Stencil component library aren't working in your Angular component library. You can resolve this issue by adding an `interfaces.d.ts` file located within the root of your Stencil component library's project folder, then manually exporting types from that file e.g. `export * from './components';`
When adding this file, it's also recommended to update your package.json's types property to be the distributed file, something like: `"types": "dist/types/interfaces.d.ts"`
Contents
--------
* [Supported Angular Versions](https://stenciljs.com/docs/angular#supported-angular-versions)
* [Setup](https://stenciljs.com/docs/angular#setup)
* [Project Structure](https://stenciljs.com/docs/angular#project-structure)
* [Adding the Angular Output Target](https://stenciljs.com/docs/angular#adding-the-angular-output-target)
* [Registering Custom Elements](https://stenciljs.com/docs/angular#registering-custom-elements)
* [Link Your Packages (Optional)](https://stenciljs.com/docs/angular#link-your-packages-optional)
* [Consumer Usage](https://stenciljs.com/docs/angular#consumer-usage)
* [Angular with Modules](https://stenciljs.com/docs/angular#angular-with-modules)
* [Angular with Standalone Components](https://stenciljs.com/docs/angular#angular-with-standalone-components)
* [API](https://stenciljs.com/docs/angular#api)
* [componentCorePackage](https://stenciljs.com/docs/angular#componentcorepackage)
* [customElementsDir](https://stenciljs.com/docs/angular#customelementsdir)
* [excludeComponents](https://stenciljs.com/docs/angular#excludecomponents)
* [directivesArrayFile](https://stenciljs.com/docs/angular#directivesarrayfile)
* [directivesProxyFile](https://stenciljs.com/docs/angular#directivesproxyfile)
* [outputType](https://stenciljs.com/docs/angular#outputtype)
* [valueAccessorConfigs](https://stenciljs.com/docs/angular#valueaccessorconfigs)
* [FAQs](https://stenciljs.com/docs/angular#faqs)
* [Do I have to use the `dist` output target?](https://stenciljs.com/docs/angular#do-i-have-to-use-the-dist-output-target)
* [What is the best format to write event names?](https://stenciljs.com/docs/angular#what-is-the-best-format-to-write-event-names)
* [How do I bind input events directly to a value accessor?](https://stenciljs.com/docs/angular#how-do-i-bind-input-events-directly-to-a-value-accessor)
* [How do I access components with ViewChild or ViewChildren?](https://stenciljs.com/docs/angular#how-do-i-access-components-with-viewchild-or-viewchildren)
* [Why aren't my custom interfaces exported from within the index.d.ts file?](https://stenciljs.com/docs/angular#why-arent-my-custom-interfaces-exported-from-within-the-indexdts-file)
* * *
[Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.35/framework-integration/angular.md)
---
# Stencil Core Dev Server API | Stencil
[Skip to main content](https://stenciljs.com/docs/v4.34/dev-server-api#__docusaurus_skipToContent_fallback)
[An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none)
This is documentation for Stencil **v4.34**, which is no longer actively maintained.
For up-to-date documentation, see the **[latest version](https://stenciljs.com/docs/dev-server-api)
** (v4.35).
Version: v4.34
On this page
The CLI API can be found at `@stencil/core/dev-server`.
start()[](https://stenciljs.com/docs/v4.34/dev-server-api#start "Direct link to start()")
-------------------------------------------------------------------------------------------
start(stencilDevServerConfig: StencilDevServerConfig, logger: Logger, watcher?: CompilerWatcher): Promise
Contents
--------
* [start()](https://stenciljs.com/docs/v4.34/dev-server-api#start)
* * *
[Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.34/core/dev-server-api.md)
---
# Stencil Documentation Generation | Stencil
[Skip to main content](https://stenciljs.com/docs/doc-generation#__docusaurus_skipToContent_fallback)
[An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none)
Version: v4.35
On this page
* [`docs-readme`: Documentation readme files formatted in markdown](https://stenciljs.com/docs/docs-readme)
* [`docs-json`: Documentation data formatted in JSON](https://stenciljs.com/docs/docs-json)
* [`docs-custom`: Custom documentation generation](https://stenciljs.com/docs/docs-custom)
* [`docs-vscode`: Documentation generation for VS Code](https://stenciljs.com/docs/docs-vscode)
* [`stats`: Stats about the compiled files](https://stenciljs.com/docs/stats)
Docs Auto-Generation[](https://stenciljs.com/docs/doc-generation#docs-auto-generation "Direct link to Docs Auto-Generation")
------------------------------------------------------------------------------------------------------------------------------
As apps scale with more and more components, and team size and members continue to adjust over time, it's vital all components are well documented, and that the documentation itself is maintained. Maintaining documentation is right up there with some of the least interesting things developers must do, but that doesn't mean it can't be made easier.
Throughout the build process, the compiler is able to extract documentation from each component, to include JSDocs comments, types of each member on the component (thanks TypeScript!) and CSS Variables (CSS Custom Properties).
### Component Property Docs Example:[](https://stenciljs.com/docs/doc-generation#component-property-docs-example "Direct link to Component Property Docs Example:")
To add a description to a `@Prop`, simply add a comment on the previous line:
/** (optional) The icon to display */@Prop() iconType = "";
### CSS Example:[](https://stenciljs.com/docs/doc-generation#css-example "Direct link to CSS Example:")
Stencil will also document CSS variables when you specify them via jsdoc-style comments inside your css or scss files:
:root { /** * @prop --primary: Primary header color. */ --primary: blue; }
Contents
--------
* [Docs Auto-Generation](https://stenciljs.com/docs/doc-generation#docs-auto-generation)
* [Component Property Docs Example:](https://stenciljs.com/docs/doc-generation#component-property-docs-example)
* [CSS Example:](https://stenciljs.com/docs/doc-generation#css-example)
* * *
[Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.35/documentation-generation/01-overview.md)
---
# WebdriverIO Overview | Stencil
[Skip to main content](https://stenciljs.com/docs/testing/webdriverio/overview#__docusaurus_skipToContent_fallback)
[An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none)
Version: v4.35
On this page
WebdriverIO is a progressive automation framework built to automate modern web and mobile applications. It simplifies the interaction with your project and provides a set of plugins that help you create a scalable, robust and stable test suite.
Testing with WebdriverIO has the following advantages:
* **Cross Browser Support**: WebdriverIO is designed to support all platforms, either on desktop or mobile. You can run tests on actual browser your users are using, including covering different versions of them.
* **Real User Interaction**: Interaction with elements in WebdriverIO through the WebDriver protocol is much closer to native user-triggered interactions than what can be achieved with emulated DOM environments (such as JSDom or Stencil's own Mock-Doc).
* **Web Platform Support**: Running tests in actual browsers allows you to tap into the latest Web Platform features for testing your components, often not available when using virtual DOM environments.
* **Real Environments**: Run your tests in an environment that your users are using and not somewhere that re-implements web standards with polyfills like JSDOM.
Set Up[](https://stenciljs.com/docs/testing/webdriverio/overview#set-up "Direct link to Set Up")
--------------------------------------------------------------------------------------------------
To get started with WebdriverIO, all you need to do is to run their project starter:
* npm
* Yarn
* pnpm
npm init wdio@latest .
yarn create wdio@latest .
pnpm create wdio@latest .
This will initiate WebdriverIO's configuration wizard that walks you through the setup. Make sure you select the following options when walking through it:
* **What type of testing would you like to do?** Select either:
* `Component or Unit Testing - in the browser` if you are interested adding unit tests for your components
* `E2E Testing - of Web or Mobile Applications` if you like to test your whole applicationYou can always add either of them later on
* **Which framework do you use for building components?**: if you select _Component or Unit Testing_ make sure to select `StencilJS` as preset so WebdriverIO knows how to compile your components properly
The following questions can be answered as desired. Once setup the wizard has created a `wdio.conf.ts` file and a `wdio` script to run your tests.
CJS vs. ESM
WebdriverIO's generated config and test files use ESM syntax for imports. If you generated a project via the [`create-stencil`](https://www.npmjs.com/package/create-stencil)
starter package your project is likely setup for CommonJS. To avoid any incompatibility issues, we recommend to rename your `wdio.conf.ts` to `wdio.conf.mts` and update the `wdio` script in your `package.json`.
Type Clashes
It's possible that you run into TypeScript issues as WebdriverIO uses Mocha for component testing and Stencil Jest. Both register the same globals, e.g. `it` which causes type clashes. To fix these we recommend to add the following to your `tsconfig.json`:
"types": ["jest"]
This will ensure that Jest types will be preferred.
You should be able to run your first test on the auto-generated test file via:
* npm
* Yarn
* pnpm
npm run wdio
yarn wdio
pnpm run wdio
More information on setting up WebdriverIO can be found in their [documentation](https://webdriver.io/docs/component-testing/stencil)
.
Integration with Stencil[](https://stenciljs.com/docs/testing/webdriverio/overview#integration-with-stencil "Direct link to Integration with Stencil")
--------------------------------------------------------------------------------------------------------------------------------------------------------
If you have been using Stencil's test runner for unit or end-to-end tests to can continue to do so. For basic implementation details that don't require any web platform features, running tests through the Stencil test runner might still be the faster choice, since no browser needs to be spawned. However you can also migrate over to only one single framework one test at a time.
We recommend to create a new NPM script for running both, Stencil and WebdriverIO tests, starting with Stencil tests first as they are likely to run faster. In your `package.json` this can be structured like so:
package.json
{ "scripts:": { "test.e2e": "stencil test && wdio run wdio.conf.ts" }}
Make sure that each test runner picks up their respective tests by defining the `testRegex` property in your Stencil config, e.g.:
stencil.config.ts
import { Config } from '@stencil/core';export const config: Config = { // ... testing: { testRegex: '(/__tests__/.*|\\.?(spec))\\.(ts|js)$', },};
This will make Stencil pick up all files ending with `.spec.ts` or `.spec.js` while WebdriverIO picks up tests ending with `.test.ts`.
Contents
--------
* [Set Up](https://stenciljs.com/docs/testing/webdriverio/overview#set-up)
* [Integration with Stencil](https://stenciljs.com/docs/testing/webdriverio/overview#integration-with-stencil)
* * *
[Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.35/testing/webdriverio/01-overview.md)
---
# WebdriverIO Overview | Stencil
[Skip to main content](https://stenciljs.com/docs/v4.34/testing/webdriverio/overview#__docusaurus_skipToContent_fallback)
[An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none)
This is documentation for Stencil **v4.34**, which is no longer actively maintained.
For up-to-date documentation, see the **[latest version](https://stenciljs.com/docs/testing/webdriverio/overview)
** (v4.35).
Version: v4.34
On this page
WebdriverIO is a progressive automation framework built to automate modern web and mobile applications. It simplifies the interaction with your project and provides a set of plugins that help you create a scalable, robust and stable test suite.
Testing with WebdriverIO has the following advantages:
* **Cross Browser Support**: WebdriverIO is designed to support all platforms, either on desktop or mobile. You can run tests on actual browser your users are using, including covering different versions of them.
* **Real User Interaction**: Interaction with elements in WebdriverIO through the WebDriver protocol is much closer to native user-triggered interactions than what can be achieved with emulated DOM environments (such as JSDom or Stencil's own Mock-Doc).
* **Web Platform Support**: Running tests in actual browsers allows you to tap into the latest Web Platform features for testing your components, often not available when using virtual DOM environments.
* **Real Environments**: Run your tests in an environment that your users are using and not somewhere that re-implements web standards with polyfills like JSDOM.
Set Up[](https://stenciljs.com/docs/v4.34/testing/webdriverio/overview#set-up "Direct link to Set Up")
--------------------------------------------------------------------------------------------------------
To get started with WebdriverIO, all you need to do is to run their project starter:
* npm
* Yarn
* pnpm
npm init wdio@latest .
yarn create wdio@latest .
pnpm create wdio@latest .
This will initiate WebdriverIO's configuration wizard that walks you through the setup. Make sure you select the following options when walking through it:
* **What type of testing would you like to do?** Select either:
* `Component or Unit Testing - in the browser` if you are interested adding unit tests for your components
* `E2E Testing - of Web or Mobile Applications` if you like to test your whole applicationYou can always add either of them later on
* **Which framework do you use for building components?**: if you select _Component or Unit Testing_ make sure to select `StencilJS` as preset so WebdriverIO knows how to compile your components properly
The following questions can be answered as desired. Once setup the wizard has created a `wdio.conf.ts` file and a `wdio` script to run your tests.
CJS vs. ESM
WebdriverIO's generated config and test files use ESM syntax for imports. If you generated a project via the [`create-stencil`](https://www.npmjs.com/package/create-stencil)
starter package your project is likely setup for CommonJS. To avoid any incompatibility issues, we recommend to rename your `wdio.conf.ts` to `wdio.conf.mts` and update the `wdio` script in your `package.json`.
Type Clashes
It's possible that you run into TypeScript issues as WebdriverIO uses Mocha for component testing and Stencil Jest. Both register the same globals, e.g. `it` which causes type clashes. To fix these we recommend to add the following to your `tsconfig.json`:
"types": ["jest"]
This will ensure that Jest types will be preferred.
You should be able to run your first test on the auto-generated test file via:
* npm
* Yarn
* pnpm
npm run wdio
yarn wdio
pnpm run wdio
More information on setting up WebdriverIO can be found in their [documentation](https://webdriver.io/docs/component-testing/stencil)
.
Integration with Stencil[](https://stenciljs.com/docs/v4.34/testing/webdriverio/overview#integration-with-stencil "Direct link to Integration with Stencil")
--------------------------------------------------------------------------------------------------------------------------------------------------------------
If you have been using Stencil's test runner for unit or end-to-end tests to can continue to do so. For basic implementation details that don't require any web platform features, running tests through the Stencil test runner might still be the faster choice, since no browser needs to be spawned. However you can also migrate over to only one single framework one test at a time.
We recommend to create a new NPM script for running both, Stencil and WebdriverIO tests, starting with Stencil tests first as they are likely to run faster. In your `package.json` this can be structured like so:
package.json
{ "scripts:": { "test.e2e": "stencil test && wdio run wdio.conf.ts" }}
Make sure that each test runner picks up their respective tests by defining the `testRegex` property in your Stencil config, e.g.:
stencil.config.ts
import { Config } from '@stencil/core';export const config: Config = { // ... testing: { testRegex: '(/__tests__/.*|\\.?(spec))\\.(ts|js)$', },};
This will make Stencil pick up all files ending with `.spec.ts` or `.spec.js` while WebdriverIO picks up tests ending with `.test.ts`.
Contents
--------
* [Set Up](https://stenciljs.com/docs/v4.34/testing/webdriverio/overview#set-up)
* [Integration with Stencil](https://stenciljs.com/docs/v4.34/testing/webdriverio/overview#integration-with-stencil)
* * *
[Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.34/testing/webdriverio/01-overview.md)
---
# Vitest | Stencil
[Skip to main content](https://stenciljs.com/docs/testing/vitest#__docusaurus_skipToContent_fallback)
[An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none)
Version: v4.35
On this page
[Vitest](https://vitest.dev/)
is a popular and modern test framework for unit testing. You can use Vitest to test Stencil components in the browser using its [browser mode feature](https://vitest.dev/guide/browser.html)
.
caution
Vitest browser mode is an experimental feature and in early development. As such, it may not yet be fully optimized, and there may be some bugs or issues that have not yet been ironed out.
Set Up[](https://stenciljs.com/docs/testing/vitest#set-up "Direct link to Set Up")
------------------------------------------------------------------------------------
To get started with Vitest, all you need to install it via:
* npm
* Yarn
* pnpm
npm install vitest @vitest/browser unplugin-stencil webdriverio
yarn add vitest @vitest/browser unplugin-stencil webdriverio
pnpm add vitest @vitest/browser unplugin-stencil webdriverio
This command installs:
* `vitest`: the core test framework
* `@vitest/browser`: enables testing in browser environments
* `unplugin-stencil`: integrates Stencil's compiler with Vitest for seamless testing
* `webdriverio`: facilitates browser management for tests
Next, we create a Vitest configuration as following:
vitest.config.ts
import stencil from 'unplugin-stencil/vite'import { defineConfig } from 'vitest/config'export default defineConfig({ test: { browser: { enabled: true, headless: true, name: 'chrome' }, }, plugins: [stencil()]})
This configuration enables tests to run in a headless Chrome browser.
Writing Tests[](https://stenciljs.com/docs/testing/vitest#writing-tests "Direct link to Writing Tests")
---------------------------------------------------------------------------------------------------------
Once you've setup Vitest you can start write your first test. In order to render a Stencil component into the browser, all you need to do is import the component and initiate an instance of the component on the page:
src/components/my-component/my-component.test.ts
import { expect, test } from 'vitest'import '../src/components/my-component/my-component.js'test('should render component correctly', async () => { const cmp = document.createElement('my-component') cmp.setAttribute('first', 'Stencil') cmp.setAttribute('last', `'Don't call me a framework' JS`) document.body.appendChild(cmp) await new Promise((resolve) => requestIdleCallback(resolve)) expect(cmp.shadowRoot?.querySelector('div')?.innerText) .toBe(`Hello, World! I'm Stencil 'Don't call me a framework' JS`)})
Lastly, let's add a Vitest script to our `package.json`:
{ "scripts": { "test": "vitest --run" },}
Execute the tests using:
* npm
* Yarn
* pnpm
npm test
yarn test
pnpm test
Expected output:
❯ npm test> [email protected] test> vitest --runThe CJS build of Vite's Node API is deprecated. See https://vitejs.dev/guide/troubleshooting.html#vite-cjs-node-api-deprecated for more details. RUN v1.5.0 /private/tmp/vitest Browser runner started at http://localhost:5173/[19:39.9] build, vitest, prod mode, started ...[19:39.9] transpile started ...[19:40.0] transpile finished in 72 ms[19:40.0] generate custom elements + source maps started ...[19:40.1] generate custom elements + source maps finished in 137 ms[19:40.1] build finished in 227 ms ✓ src/components/my-component/my-component.test.ts (1) ✓ should render component correctly Test Files 1 passed (1) Tests 1 passed (1) Start at 14:19:36 Duration 3.19s (transform 0ms, setup 0ms, collect 721ms, tests 22ms, environment 0ms, prepare 0ms)
### Use JSX[](https://stenciljs.com/docs/testing/vitest#use-jsx "Direct link to Use JSX")
The example above creates the Stencil instance using basic DOM primitives. If you prefer to use JSX also for rendering Stencil components in your test, just create a `jsx.ts` utility file with the following content:
src/utils/jsx.ts
export const createElement = (tag, props, ...children) => { if (typeof tag === 'function') { return tag(props, ...children) } const element = document.createElement(tag) Object.entries(props || {}).forEach(([name, value]) => { if (name.startsWith('on') && name.toLowerCase() in window) { element.addEventListener(name.toLowerCase().substr(2), value) } else { element.setAttribute(name, value.toString()) } }) children.forEach((child) => { appendChild(element, child) }) return element}export const appendChild = (parent, child) => { if (Array.isArray(child)) { child.forEach((nestedChild) => appendChild(parent, nestedChild)) } else { parent.appendChild(child.nodeType ? child : document.createTextNode(child)) }}export const createFragment = (_, ...children) => { return children}
Now update your test, import the `createElement` method and tell the JSX engine to use that method for rendering the JSX snippet. Our test should look as follows:
src/components/my-component/my-component.test.tsx
/** @jsx createElement */import { expect, test } from 'vitest'import { createElement } from '../../utils/jsx'import './my-component.js'test('should render the component with jsx', async () => { const cmp = Click me ', }); // Test HTML structure with shadow DOM expect(root).toEqualHtml(` `); // Test specific elements and classes const button = root.shadowRoot.querySelector('button'); expect(button).toHaveClasses(['btn', 'btn--primary']); expect(button).toEqualText('Click me'); });});
### Using JSX Templates[](https://stenciljs.com/docs/v4.33/testing/jest#using-jsx-templates "Direct link to Using JSX Templates")
You can also use JSX templates instead of HTML strings:
import { h } from '@stencil/core';import { newSpecPage } from 'jest-stencil-runner';import { MyComponent } from './my-component';describe('my-component', () => { it('renders with JSX template', async () => { const { root } = await newSpecPage({ components: [MyComponent], template: () => `); });});
API Reference[](https://stenciljs.com/docs/v4.33/testing/jest#api-reference "Direct link to API Reference")
-------------------------------------------------------------------------------------------------------------
### `newSpecPage(options)`[](https://stenciljs.com/docs/v4.33/testing/jest#newspecpageoptions "Direct link to newspecpageoptions")
Creates a new spec page for unit testing Stencil components.
**Parameters:**
* `options.components` - Array of component classes to register
* `options.html` - Initial HTML content for the page
* `options.template` - Function that returns JSX template
* `options.includeAnnotations` - Whether to include Stencil annotations
**Returns:** `Promise`
**SpecPage Properties:**
* `root` - The root element of the component
* `doc` - The document object
* `win` - The window object
* `body` - The document body
**SpecPage Methods:**
* `setContent(html: string)` - Set the page HTML content
* `waitForChanges()` - Wait for component re-renders
Custom Jest Matchers[](https://stenciljs.com/docs/v4.33/testing/jest#custom-jest-matchers "Direct link to Custom Jest Matchers")
----------------------------------------------------------------------------------------------------------------------------------
The runner includes comprehensive Jest matchers for component testing:
### HTML Matchers[](https://stenciljs.com/docs/v4.33/testing/jest#html-matchers "Direct link to HTML Matchers")
#### `toEqualHtml(html)`[](https://stenciljs.com/docs/v4.33/testing/jest#toequalhtmlhtml "Direct link to toequalhtmlhtml")
Compares HTML content, including shadow DOM, with normalized whitespace:
expect(element).toEqualHtml(` `);
#### `toEqualLightHtml(html)`[](https://stenciljs.com/docs/v4.33/testing/jest#toequallighthtmlhtml "Direct link to toequallighthtmlhtml")
Compares only the light DOM (excluding shadow DOM):
expect(element).toEqualLightHtml(` Delete ', }); expect(root).toHaveAttribute('variant'); expect(root).toEqualAttribute('variant', 'danger'); const button = root.shadowRoot.querySelector('button'); expect(button).toHaveClasses(['btn', 'btn--danger', 'btn--large']); });});
### Testing Events[](https://stenciljs.com/docs/v4.33/testing/jest#testing-events "Direct link to Testing Events")
describe('my-button events', () => { it('emits click event with correct details', async () => { const { root, waitForChanges } = await newSpecPage({ components: [MyButton], html: 'Click me ', }); const events = []; root.addEventListener('buttonClick', (e) => { events.push(e); }); // Trigger click const button = root.shadowRoot.querySelector('button'); button.click(); await waitForChanges(); expect(events).toHaveLength(1); expect(events[0].detail).toEqual({ clicked: true, timestamp: expect.any(Number) }); });});
### Testing Dynamic Changes[](https://stenciljs.com/docs/v4.33/testing/jest#testing-dynamic-changes "Direct link to Testing Dynamic Changes")
describe('my-component dynamic behavior', () => { it('updates when properties change', async () => { const { root, waitForChanges } = await newSpecPage({ components: [MyComponent], html: ' `); });});
Running Tests[](https://stenciljs.com/docs/v4.33/testing/jest#running-tests "Direct link to Running Tests")
-------------------------------------------------------------------------------------------------------------
Add test scripts to your `package.json`:
{ "scripts": { "test": "jest", "test:watch": "jest --watch", "test:coverage": "jest --coverage" }}
Run tests with:
npm testnpm run test:watchnpm run test:coverage
Configuration Options[](https://stenciljs.com/docs/v4.33/testing/jest#configuration-options "Direct link to Configuration Options")
-------------------------------------------------------------------------------------------------------------------------------------
### Advanced Jest Configuration[](https://stenciljs.com/docs/v4.33/testing/jest#advanced-jest-configuration "Direct link to Advanced Jest Configuration")
const { createJestStencilPreset } = require('jest-stencil-runner/preset');module.exports = createJestStencilPreset({ rootDir: __dirname, // Coverage options collectCoverageFrom: [ 'src/**/*.{ts,tsx}', '!src/**/*.d.ts', '!src/**/*.stories.{ts,tsx}' ], coverageDirectory: 'coverage', coverageReporters: ['text', 'lcov', 'html'], // Test matching testMatch: [ '**/__tests__/**/*.(test|spec).(ts|tsx|js)', '**/*.(test|spec).(ts|tsx|js)' ], // Module configuration moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json'], // Additional Jest options verbose: true, setupFilesAfterEnv: ['/src/test-setup.ts']});
Troubleshooting[](https://stenciljs.com/docs/v4.33/testing/jest#troubleshooting "Direct link to Troubleshooting")
-------------------------------------------------------------------------------------------------------------------
### Common Issues[](https://stenciljs.com/docs/v4.33/testing/jest#common-issues "Direct link to Common Issues")
1. **Module resolution errors**: Ensure your `tsconfig.json` has proper module resolution settings
2. **Component not rendering**: Make sure components are properly registered in the `components` array
3. **Async issues**: Always use `await page.waitForChanges()` after making changes
4. **Shadow DOM access**: Use `root.shadowRoot.querySelector()` to access shadow DOM elements
### Debug Mode[](https://stenciljs.com/docs/v4.33/testing/jest#debug-mode "Direct link to Debug Mode")
Enable debug logging by setting the `DEBUG` environment variable:
DEBUG=jest-stencil-runner npm test
Migration from Stencil Test Runner[](https://stenciljs.com/docs/v4.33/testing/jest#migration-from-stencil-test-runner "Direct link to Migration from Stencil Test Runner")
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
If migrating from the Stencil Test Runner to Jest Runner, the main differences are:
1. **Configuration**: Use `createJestStencilPreset()` instead of Stencil's built-in Jest configuration
2. **Import**: Import `newSpecPage` from `jest-stencil-runner` instead of `@stencil/core/testing`
3. **Matchers**: Access to additional custom matchers for more comprehensive testing
4. **Jest Version**: Requires Jest v30+ (use Stencil Test Runner for Jest v29 and earlier)
The API for `newSpecPage()` remains largely the same, making migration straightforward.
Contents
--------
* [Features](https://stenciljs.com/docs/v4.33/testing/jest#features)
* [Installation](https://stenciljs.com/docs/v4.33/testing/jest#installation)
* [Configuration](https://stenciljs.com/docs/v4.33/testing/jest#configuration)
* [TypeScript Configuration](https://stenciljs.com/docs/v4.33/testing/jest#typescript-configuration)
* [Basic Usage](https://stenciljs.com/docs/v4.33/testing/jest#basic-usage)
* [Testing Components](https://stenciljs.com/docs/v4.33/testing/jest#testing-components)
* [Using JSX Templates](https://stenciljs.com/docs/v4.33/testing/jest#using-jsx-templates)
* [API Reference](https://stenciljs.com/docs/v4.33/testing/jest#api-reference)
* [`newSpecPage(options)`](https://stenciljs.com/docs/v4.33/testing/jest#newspecpageoptions)
* [Custom Jest Matchers](https://stenciljs.com/docs/v4.33/testing/jest#custom-jest-matchers)
* [HTML Matchers](https://stenciljs.com/docs/v4.33/testing/jest#html-matchers)
* [Text Matchers](https://stenciljs.com/docs/v4.33/testing/jest#text-matchers)
* [Attribute Matchers](https://stenciljs.com/docs/v4.33/testing/jest#attribute-matchers)
* [Class Matchers](https://stenciljs.com/docs/v4.33/testing/jest#class-matchers)
* [Event Matchers](https://stenciljs.com/docs/v4.33/testing/jest#event-matchers)
* [Advanced Examples](https://stenciljs.com/docs/v4.33/testing/jest#advanced-examples)
* [Testing Component Properties](https://stenciljs.com/docs/v4.33/testing/jest#testing-component-properties)
* [Testing Events](https://stenciljs.com/docs/v4.33/testing/jest#testing-events)
* [Testing Dynamic Changes](https://stenciljs.com/docs/v4.33/testing/jest#testing-dynamic-changes)
* [Snapshot Testing](https://stenciljs.com/docs/v4.33/testing/jest#snapshot-testing)
* [Running Tests](https://stenciljs.com/docs/v4.33/testing/jest#running-tests)
* [Configuration Options](https://stenciljs.com/docs/v4.33/testing/jest#configuration-options)
* [Advanced Jest Configuration](https://stenciljs.com/docs/v4.33/testing/jest#advanced-jest-configuration)
* [Troubleshooting](https://stenciljs.com/docs/v4.33/testing/jest#troubleshooting)
* [Common Issues](https://stenciljs.com/docs/v4.33/testing/jest#common-issues)
* [Debug Mode](https://stenciljs.com/docs/v4.33/testing/jest#debug-mode)
* [Migration from Stencil Test Runner](https://stenciljs.com/docs/v4.33/testing/jest#migration-from-stencil-test-runner)
* * *
[Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.33/testing/04-jest.md)
---
# Support Policy | Stencil
[Skip to main content](https://stenciljs.com/docs/support-policy#__docusaurus_skipToContent_fallback)
[An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none)
Version: v4.35
On this page
Community Maintenance[](https://stenciljs.com/docs/support-policy#community-maintenance "Direct link to Community Maintenance")
---------------------------------------------------------------------------------------------------------------------------------
Stencil is a 100% open source (MIT) project. Developers can ensure Stencil is the right choice for building web components through Ionic’s community maintenance strategy. The Stencil team regularly ships new releases, bug fixes, and is welcoming to community pull requests.
Stencil Maintenance and Support Status[](https://stenciljs.com/docs/support-policy#stencil-maintenance-and-support-status "Direct link to Stencil Maintenance and Support Status")
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Given the reality of time and resource constraints as well as the desire to keep innovating in the frontend development space, over time it becomes necessary for the Stencil team to shift focus to newer versions of the library. However, the Stencil team will do everything it can to make the transition to newer versions as smooth as possible. The Stencil team recommends updating to the newest version of the Stencil for the latest features, improvements and stability updates.
The current status of each Stencil version is:
| Version | Status | Released | Maintenance Ends | Ext. Support Ends |
| --- | --- | --- | --- | --- |
| V4 | **Active** | Jun 26, 2023 | TBD | TBD |
| V3 | Extended Support | Jan 25, 2023 | Dec 26, 2023 | Jun 26, 2024 |
| V2 | End of Support | Aug 08, 2020 | Jul 25, 2023 | Jan 25, 2024 |
| V1 | End of Support | Jun 03, 2019 | Aug 08, 2020 | Aug 08, 2020 |
**Maintenance Period**: Only critical bug and security fixes. No major feature improvements.
**Extended Support Period**: Available to Stencil Enterprise customers.
### Stencil Support Details[](https://stenciljs.com/docs/support-policy#stencil-support-details "Direct link to Stencil Support Details")
Starting with Stencil v2, the Stencil team is adopting a newly revised maintenance policy. When a new major version of Stencil is released, the previous major version release will enter maintenance mode. While a version of Stencil is in maintenance mode, only critical bug & security fixes will be applied to that version, and no major feature improvements will be added. The maintenance period shall last six months from the release of the new major version.
Once the maintenance period has ended for a version of Stencil, that version enters the extended support period. During the extended support period, only critical bug and security fixes will be applied for teams and organizations using Stencil's Enterprise offerings. The extended support period lasts for twelve months from the release of the new major version.
The table below describes a theoretical timeline of releases:
| Version | Status | Released | Maintenance Ends | Ext. Support Ends |
| --- | --- | --- | --- | --- |
| D | Active | Jan 01, 2022 | TBD | TBD |
| C | Maintenance | Jul 07, 2021 | Jul 01, 2022 | Jan 01, 2023 |
| B | Extended Support Only | Jan 01, 2021 | Jan 07, 2022 | Jul 07, 2022 |
| A | End of Support | Jul 07, 2020 | Jul 01, 2021 | Jan 01, 2021 |
In the example above, when Version D is released, Version C enters maintenance mode. Version D was released on January 1st, 2022. Version C shall be in maintenance mode until July 1st, 2022, three months after the release of Version D. After July 1st 2022, Version C will be in extended support until Jun 1st, 2023, twelve months after the release of Version D.
Browser Support[](https://stenciljs.com/docs/support-policy#browser-support "Direct link to Browser Support")
---------------------------------------------------------------------------------------------------------------
Stencil builds Web Components that run natively in all widely used desktop and mobile browsers. Custom Elements are natively supported in Chrome, Edge, Firefox, and Safari (including iOS)!
Stencil supports the following browsers:
| Stencil Version | Chrome | Edge | Firefox | Safari | Internet Explorer | Pre-Chromium Edge |
| --- | --- | --- | --- | --- | --- | --- |
| V4 | v79+ | v79+ | v70+ | v14+ | ❌ | ❌ |
| V3 | v79+ | v79+ | v70+ | v14+ | ✅ | ✅ |
| V2 | v60+ | v79+ | v63+ | v10.1+ | ✅ | ✅ |
TypeScript Support[](https://stenciljs.com/docs/support-policy#typescript-support "Direct link to TypeScript Support")
------------------------------------------------------------------------------------------------------------------------
Stencil acts as a compiler for a project's web components, and works closely with the TypeScript compiler to transform TSX to vanilla JavaScript. To ensure compatibility between the two, Stencil takes an opinionated stance on which version of the TypeScript compiler must be used.
Stencil includes a recent copy of the TypeScript compiler in its distributable\* to guarantee this compatibility. The Stencil team is committed to keeping its version of TypeScript up to date and, as of Stencil v2.10.0, attempts to be within one minor version of the latest TypeScript release.
The table below describes recent versions of Stencil and the version of TypeScript each version shipped with.
| Stencil Version | TypeScript Version |
| --- | --- |
| v4.20.0 | v5.5.3 |
| v4.16.0 | v5.4.5 |
| v4.15.0 | v5.4.4 |
| v4.14.0 | v5.4.3 |
| v4.13.0 | v5.4.2 |
| v4.10.0 | v5.3.0 |
| v4.4.0 | v5.2.2 |
| v4.2.0 | v5.1.6 |
| v3.3.0 | v5.0.4 |
| v3.0.0 | v4.9.4 |
| v2.21.0 | v4.9.3 |
| v2.20.0 | v4.8.4 |
| v2.18.0 | v4.7.4 |
| v2.14.0 | v4.5.4 |
| v2.10.0 | v4.3.5 |
| v2.5.0 | v4.2.3 |
| v2.4.0 | v4.1.3 |
| v2.2.0 | v4.0.5 |
The TypeScript team releases a new minor version of the TypeScript compiler approximately once every three months. To accomplish its goal of staying within one minor version of the latest release, Stencil will update its version of TypeScript once every three months as well. Updates to the version of TypeScript will often, but not always, occur in a [minor version release](https://stenciljs.com/docs/versioning#minor-release)
of Stencil.
The Stencil team acknowledges that TypeScript minor version releases may contain breaking changes. The Stencil team will do everything in its power to avoid propagating breaking changes to its user base.
\* The TypeScript compiler is never included in the output of your Stencil project, and is only used for compilation and type checking purposes.
Compatibility Recommendations[](https://stenciljs.com/docs/support-policy#compatibility-recommendations "Direct link to Compatibility Recommendations")
---------------------------------------------------------------------------------------------------------------------------------------------------------
Stencil is in many regards an opinionated library, and includes much of the software necessary to get users building web components as quickly as possible. There are a few pieces of software that Stencil allows users to choose to best fit their team, organizational structure, and existing technical stack. The Stencil team has compiled a series of compatibility tables to describe the interoperability requirements of these pieces of software and Stencil.
### JavaScript Runtime[](https://stenciljs.com/docs/support-policy#javascript-runtime "Direct link to JavaScript Runtime")
| Stencil Version | Node v10 | Node v12 | Node v14 | Node v16 | Node v18 | Node v20 | Node v22 |
| --- | --- | --- | --- | --- | --- | --- | --- |
| V4 | ❌ | ❌ | ❌ | ✅ | ✅ | ✅ | ✅ |
| V3 | ❌ | ❌ | ✅ | ✅ | ✅ | ✅ | ❌ |
| V2 | ❌ | ✅ | ✅ | ✅ | ⚠ | ❌ | ❌ |
| V1 | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
### Testing Libraries[](https://stenciljs.com/docs/support-policy#testing-libraries "Direct link to Testing Libraries")
#### Jest with [Jest Stencil Runner](https://github.com/stenciljs/jest-stencil-runner)
[](https://stenciljs.com/docs/support-policy#jest-with-jest-stencil-runner "Direct link to jest-with-jest-stencil-runner")
| Stencil Version | Jest v30 \* |
| --- | --- |
| V4 | ✅ |
#### Jest[](https://stenciljs.com/docs/support-policy#jest "Direct link to Jest")
| Stencil Version | Jest v24-26 | Jest v27 | Jest v28 \* | Jest v29 \* | Jest v30 \* |
| --- | --- | --- | --- | --- | --- |
| V4 | ✅ | ✅ | ✅ | ✅ | ❌ |
| V3 | ✅ | ✅ | ❌ | ❌ | ❌ |
| V2 | ✅ | ✅ | ❌ | ❌ | ❌ |
| V1 | ✅ | ❌ | ❌ | ❌ | ❌ |
\* Support for Jest 28 & 29 has been included since Stencil v4.7.0.
#### Puppeteer[](https://stenciljs.com/docs/support-policy#puppeteer "Direct link to Puppeteer")
| Stencil Version | Puppeteer v5-9 | Puppeteer v10 | Puppeteer v11-21 | Puppeteer v22-24 |
| --- | --- | --- | --- | --- |
| V4 | ❌ | ✅ | ✅ | ✅ |
| V3 | ❌ | ✅ | ✅ | ❌ |
| V2 | ✅ | ✅ | ❌ | ❌ |
| V1 | ✅ | ❌ | ❌ | ❌ |
Contents
--------
* [Community Maintenance](https://stenciljs.com/docs/support-policy#community-maintenance)
* [Stencil Maintenance and Support Status](https://stenciljs.com/docs/support-policy#stencil-maintenance-and-support-status)
* [Stencil Support Details](https://stenciljs.com/docs/support-policy#stencil-support-details)
* [Browser Support](https://stenciljs.com/docs/support-policy#browser-support)
* [TypeScript Support](https://stenciljs.com/docs/support-policy#typescript-support)
* [Compatibility Recommendations](https://stenciljs.com/docs/support-policy#compatibility-recommendations)
* [JavaScript Runtime](https://stenciljs.com/docs/support-policy#javascript-runtime)
* [Testing Libraries](https://stenciljs.com/docs/support-policy#testing-libraries)
* * *
[Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.35/reference/support-policy.md)
---
# Versioning | Stencil
[Skip to main content](https://stenciljs.com/docs/versioning#__docusaurus_skipToContent_fallback)
[An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none)
Version: v4.35
On this page
Stencil follows the [Semantic Versioning (SemVer)](https://semver.org/)
convention: `major.minor.patch.` Incompatible API changes increment the `major` version, adding backwards-compatible functionality increments the `minor` version, and backwards-compatible bug fixes increment the `patch` version.
Release Schedule[](https://stenciljs.com/docs/versioning#release-schedule "Direct link to Release Schedule")
--------------------------------------------------------------------------------------------------------------
### Major Release[](https://stenciljs.com/docs/versioning#major-release "Direct link to Major Release")
A major release will be published when there is a breaking change introduced in the API. Release candidates will be published prior to a major release in order to get feedback before the final release. An outline of what is changing and why will be included with the release candidates.
### Minor Release[](https://stenciljs.com/docs/versioning#minor-release "Direct link to Minor Release")
A minor release will be published when a new feature is added or API changes that are non-breaking are introduced. We will heavily test any changes so that we are confident with the release, but with new code comes the potential for new issues\*. Minor releases are scheduled to occur at least **once a month**, although this cadence may vary according to team priorities.
\* This statement applies to the Stencil team upgrading its version of TypeScript as well. For more information, please see the team's [support policy regarding TypeScript](https://stenciljs.com/docs/support-policy#typescript-support)
### Patch Release[](https://stenciljs.com/docs/versioning#patch-release "Direct link to Patch Release")
A patch release will be published when bug fixes were included, but the API has not changed and no breaking changes were introduced. Patch releases are scheduled to occur at least **once a month**, although this cadence may vary according to team priorities. There may be times where patch releases need to released more often than scheduled.
Changelog[](https://stenciljs.com/docs/versioning#changelog "Direct link to Changelog")
-----------------------------------------------------------------------------------------
To see a list of all notable changes to Stencil, please refer to the [releases page](https://github.com/ionic-team/stencil/releases)
. This contains an ordered list of all bug fixes and new features under each release.
Contents
--------
* [Release Schedule](https://stenciljs.com/docs/versioning#release-schedule)
* [Major Release](https://stenciljs.com/docs/versioning#major-release)
* [Minor Release](https://stenciljs.com/docs/versioning#minor-release)
* [Patch Release](https://stenciljs.com/docs/versioning#patch-release)
* [Changelog](https://stenciljs.com/docs/versioning#changelog)
* * *
[Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.35/reference/versioning.md)
---
# Upgrading to Stencil v4.0.0 | Stencil
[Skip to main content](https://stenciljs.com/docs/v4.34/introduction/upgrading-to-stencil-four#__docusaurus_skipToContent_fallback)
[An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none)
This is documentation for Stencil **v4.34**, which is no longer actively maintained.
For up-to-date documentation, see the **[latest version](https://stenciljs.com/docs/introduction/upgrading-to-stencil-four)
** (v4.35).
Version: v4.34
On this page
Getting Started[](https://stenciljs.com/docs/v4.34/introduction/upgrading-to-stencil-four#getting-started "Direct link to 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:
* [Stencil v3 Breaking Changes](https://github.com/ionic-team/stencil/blob/main/BREAKING_CHANGES.md#stencil-v300)
* [Stencil v2 Breaking Changes](https://github.com/ionic-team/stencil/blob/main/BREAKING_CHANGES.md#stencil-two)
* [Stencil v1 Breaking Changes](https://github.com/ionic-team/stencil/blob/main/BREAKING_CHANGES.md#stencil-one)
For projects that are on Stencil v3, install the latest version of Stencil v4: `npm install @stencil/core@4`
Updating Your Code[](https://stenciljs.com/docs/v4.34/introduction/upgrading-to-stencil-four#updating-your-code "Direct link to Updating Your Code")
------------------------------------------------------------------------------------------------------------------------------------------------------
### New Configuration Defaults[](https://stenciljs.com/docs/v4.34/introduction/upgrading-to-stencil-four#new-configuration-defaults "Direct link to 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`[](https://stenciljs.com/docs/v4.34/introduction/upgrading-to-stencil-four#transformaliasedimportpaths "Direct link to transformaliasedimportpaths")
TypeScript projects have the ability to specify a path aliases via the [`paths` configuration in their `tsconfig.json`](https://www.typescriptlang.org/docs/handbook/module-resolution.html#path-mapping)
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](https://github.com/ionic-team/stencil/releases/tag/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](https://github.com/ionic-team/stencil/issues/new?assignees=&labels=&projects=&template=bug_report.yml&title=bug%3A+)
. 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](https://stenciljs.com/docs/v4.34/config#transformaliasedimportpaths)
#### `transformAliasedImportPathsInCollection`[](https://stenciljs.com/docs/v4.34/introduction/upgrading-to-stencil-four#transformaliasedimportpathsincollection "Direct link to transformaliasedimportpathsincollection")
Introduced in [Stencil v2.18.0](https://github.com/ionic-team/stencil/releases/tag/v2.18.0)
, `transformAliasedImportPathsInCollection` is a configuration flag on the [`dist` output target](https://stenciljs.com/docs/v4.34/distribution#transformaliasedimportpathsincollection)
. `transformAliasedImportPathsInCollection` transforms import paths, similar to [`transformAliasedImportPaths`](https://stenciljs.com/docs/v4.34/introduction/upgrading-to-stencil-four#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).
For users that run into issues with this new default, we encourage you to file a [new issue on the Stencil GitHub repo](https://github.com/ionic-team/stencil/issues/new?assignees=&labels=&projects=&template=bug_report.yml&title=bug%3A+)
. As a workaround, this flag can be set to `false` to disable the default functionality.
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](https://stenciljs.com/docs/v4.34/distribution#transformaliasedimportpathsincollection)
.
### In Browser Compilation Support Removed[](https://stenciljs.com/docs/v4.34/introduction/upgrading-to-stencil-four#in-browser-compilation-support-removed "Direct link to 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](https://github.com/ionic-team/stencil/discussions/4134)
on the Stencil GitHub Discussions page.
### Legacy Context and Connect APIs Removed[](https://stenciljs.com/docs/v4.34/introduction/upgrading-to-stencil-four#legacy-context-and-connect-apis-removed "Direct link to 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;
To migrate away from usages of `context`, please see [the original deprecation announcement](https://github.com/ionic-team/stencil/blob/main/BREAKING_CHANGES.md#propcontext)
. To migrate away from usages of `connect`, please see [the original deprecation announcement](https://github.com/ionic-team/stencil/blob/main/BREAKING_CHANGES.md#propconnect)
.
### Legacy Browser Support Removed[](https://stenciljs.com/docs/v4.34/introduction/upgrading-to-stencil-four#legacy-browser-support-removed "Direct link to Legacy Browser Support Removed")
In Stencil v3.0.0, we announced [the deprecation of IE 11, pre-Chromium Edge, and Safari 10 support](https://github.com/ionic-team/stencil/blob/1a8ff39073a88d1372beaa98434dbe2247f68a85/BREAKING_CHANGES.md?plain=1#L78)
. 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](https://stenciljs.com/docs/v4.34/support-policy#browser-support)
).
By dropping these browsers, a few configuration options are no longer valid in a Stencil configuration file:
#### `__deprecated__cssVarsShim`[](https://stenciljs.com/docs/v4.34/introduction/upgrading-to-stencil-four#__deprecated__cssvarsshim "Direct link to __deprecated__cssvarsshim")
The `extras.__deprecated__cssVarsShim` option caused Stencil to include a polyfill for [CSS variables](https://developer.mozilla.org/en-US/docs/Web/CSS/--*)
. This field should be removed from a project's Stencil configuration file (`stencil.config.ts`).
#### `__deprecated__dynamicImportShim`[](https://stenciljs.com/docs/v4.34/introduction/upgrading-to-stencil-four#__deprecated__dynamicimportshim "Direct link to __deprecated__dynamicimportshim")
The `extras.__deprecated__dynamicImportShim` option caused Stencil to include a polyfill for the [dynamic `import()` function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import)
for use at runtime. This field should be removed from a project's Stencil configuration file (`stencil.config.ts`).
#### `__deprecated__safari10`[](https://stenciljs.com/docs/v4.34/introduction/upgrading-to-stencil-four#__deprecated__safari10 "Direct link to __deprecated__safari10")
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`).
#### `__deprecated__shadowDomShim`[](https://stenciljs.com/docs/v4.34/introduction/upgrading-to-stencil-four#__deprecated__shadowdomshim "Direct link to __deprecated__shadowdomshim")
The `extras.__deprecated__shadowDomShim` option would check whether a shim for [shadow DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_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[](https://stenciljs.com/docs/v4.34/introduction/upgrading-to-stencil-four#legacy-cache-stats-config-flag-removed "Direct link to 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[](https://stenciljs.com/docs/v4.34/introduction/upgrading-to-stencil-four#drop-node-14-support "Direct link to 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](https://stenciljs.com/docs/v4.34/support-policy#javascript-runtime)
.
Information Included in `docs-json` Expanded[](https://stenciljs.com/docs/v4.34/introduction/upgrading-to-stencil-four#information-included-in-docs-json-expanded "Direct link to 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`](https://stenciljs.com/docs/v4.34/docs-json#supplementalpublictypes)
option for the JSON documentation output target.
### `JsonDocsEvent`[](https://stenciljs.com/docs/v4.34/introduction/upgrading-to-stencil-four#jsondocsevent "Direct link to 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](https://github.com/ionic-team/ionic-framework/blob/1f0c8049a339e3a77c468ddba243041d08ead0be/core/src/components/modal/modal.tsx#L289-L292)
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`[](https://stenciljs.com/docs/v4.34/introduction/upgrading-to-stencil-four#jsondocsmethod "Direct link to 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](https://github.com/ionic-team/ionic-framework/blob/1f0c8049a339e3a77c468ddba243041d08ead0be/core/src/components/select/select.tsx#L261-L313)
on the `Select` component in Ionic Framework:
{ "complexType": { "signature": "(event?: UIEvent) => Promise", "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" }}
Additional Packages[](https://stenciljs.com/docs/v4.34/introduction/upgrading-to-stencil-four#additional-packages "Direct link to 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](https://github.com/ionic-team/stencil-ds-output-targets/releases/tag/%40stencil%2Fangular-output-target%400.7.1) | [GitHub](https://github.com/ionic-team/stencil-ds-output-targets) | [Stencil Doc Site](https://stenciljs.com/docs/v4.34/angular) |
| `@stencil/sass` | [3.0.4](https://github.com/ionic-team/stencil-sass/releases/tag/v3.0.4) | [GitHub](https://github.com/ionic-team/stencil-sass) | [GitHub README](https://github.com/ionic-team/stencil-sass) |
| `@stencil/store` | [2.0.8](https://github.com/ionic-team/stencil-store/releases/tag/v2.0.8) | [GitHub](https://github.com/ionic-team/stencil-store) | [Stencil Doc Site](https://stenciljs.com/docs/v4.34/stencil-store) |
| `@stencil/react-output-target` | [0.5.1](https://github.com/ionic-team/stencil-ds-output-targets/releases/tag/%40stencil%2Freact-output-target%400.5.1) | [GitHub](https://github.com/ionic-team/stencil-ds-output-targets) | [Stencil Doc Site](https://stenciljs.com/docs/v4.34/react) |
| `@stencil/vue-output-target` | [0.8.6](https://github.com/ionic-team/stencil-ds-output-targets/releases/tag/%40stencil%2Fvue-output-target%400.8.6) | [GitHub](https://github.com/ionic-team/stencil-ds-output-targets) | [Stencil Doc Site](https://stenciljs.com/docs/v4.34/vue) |
Need Help Upgrading?[](https://stenciljs.com/docs/v4.34/introduction/upgrading-to-stencil-four#need-help-upgrading "Direct link to Need Help Upgrading?")
-----------------------------------------------------------------------------------------------------------------------------------------------------------
Be sure to look at the Stencil [v4.0.0 Breaking Changes Guide](https://github.com/ionic-team/stencil/blob/main/BREAKING_CHANGES.md#stencil-v400)
.
If you need help upgrading, please post a thread on the [Stencil Discord](https://chat.stenciljs.com/)
.
Contents
--------
* [Getting Started](https://stenciljs.com/docs/v4.34/introduction/upgrading-to-stencil-four#getting-started)
* [Updating Your Code](https://stenciljs.com/docs/v4.34/introduction/upgrading-to-stencil-four#updating-your-code)
* [New Configuration Defaults](https://stenciljs.com/docs/v4.34/introduction/upgrading-to-stencil-four#new-configuration-defaults)
* [In Browser Compilation Support Removed](https://stenciljs.com/docs/v4.34/introduction/upgrading-to-stencil-four#in-browser-compilation-support-removed)
* [Legacy Context and Connect APIs Removed](https://stenciljs.com/docs/v4.34/introduction/upgrading-to-stencil-four#legacy-context-and-connect-apis-removed)
* [Legacy Browser Support Removed](https://stenciljs.com/docs/v4.34/introduction/upgrading-to-stencil-four#legacy-browser-support-removed)
* [Legacy Cache Stats Config Flag Removed](https://stenciljs.com/docs/v4.34/introduction/upgrading-to-stencil-four#legacy-cache-stats-config-flag-removed)
* [Drop Node 14 Support](https://stenciljs.com/docs/v4.34/introduction/upgrading-to-stencil-four#drop-node-14-support)
* [Information Included in `docs-json` Expanded](https://stenciljs.com/docs/v4.34/introduction/upgrading-to-stencil-four#information-included-in-docs-json-expanded)
* [`JsonDocsEvent`](https://stenciljs.com/docs/v4.34/introduction/upgrading-to-stencil-four#jsondocsevent)
* [`JsonDocsMethod`](https://stenciljs.com/docs/v4.34/introduction/upgrading-to-stencil-four#jsondocsmethod)
* [Additional Packages](https://stenciljs.com/docs/v4.34/introduction/upgrading-to-stencil-four#additional-packages)
* [Need Help Upgrading?](https://stenciljs.com/docs/v4.34/introduction/upgrading-to-stencil-four#need-help-upgrading)
* * *
[Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.34/introduction/upgrading-to-stencil-four.md)
---
# VS Code Documentation | Stencil
[Skip to main content](https://stenciljs.com/docs/docs-vscode#__docusaurus_skipToContent_fallback)
[An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none)
Version: v4.35
On this page
One of the core features of web components is the ability to create [custom elements](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements)
, which allow developers to reuse custom functionality defined in their components. When Stencil compiles a project, it generates a custom element for each component in the project. Each of these [custom elements has an associated `tag` name](https://stenciljs.com/docs/component#component-options)
that allows the custom element to be used in HTML files.
By default, integrated development environments (IDEs) like VS Code are not aware of a project's custom elements when authoring HTML. In order to enable more intelligent features in VS Code, such as auto-completion, hover tooltips, etc., developers need to inform it of their project's custom elements.
The `docs-vscode` output target tells Stencil to generate a JSON file containing this information.
This is an opt-in feature and will save a JSON file containing [custom data](https://github.com/microsoft/vscode-custom-data)
in a directory specified by the output target. Once the feature is enabled and VS Code is informed of the JSON file's location, HTML files can gain code editing features similar to TSX files.
Enabling[](https://stenciljs.com/docs/docs-vscode#enabling "Direct link to Enabling")
---------------------------------------------------------------------------------------
To generate custom element information for VS Code, add the `docs-vscode` output target to your `stencil.config.ts`:
import { Config } from '@stencil/core';export const config: Config = { outputTargets: [ { type: 'docs-vscode', file: 'vscode-data.json', } ]};
where `file` is the name & location of the file to be generated. By default, Stencil assumes that the file will be generated in the project's root directory.
To generate the JSON file, have Stencil build your project.
Configuring VS Code[](https://stenciljs.com/docs/docs-vscode#configuring-vs-code "Direct link to Configuring VS Code")
------------------------------------------------------------------------------------------------------------------------
Once the `docs-vscode` output target has been enabled and the JSON file generated, VS Code needs to be informed of it.
Recent versions of VS Code have a settings option named `html.customData`, which resolves to a list of JSON files to use when augmenting the default list of HTML elements. Add the path to the generated JSON file for your project's types to be added:
{ "html.customData": [ "./vscode-data.json" ]}
Contents
--------
* [Enabling](https://stenciljs.com/docs/docs-vscode#enabling)
* [Configuring VS Code](https://stenciljs.com/docs/docs-vscode#configuring-vs-code)
* * *
[Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.35/documentation-generation/docs-vscode.md)
---
- Item 1
- Item 2
- Item 3
... more html content ...
]);}
Alternatively you can use the `Fragment` functional component, in which case you won't need to add commas:
import { Fragment } from '@stencil/core';...render() { return (- Item 1
- Item 2
- Item 3
... more html content ...
Text
; return ( - {sharedNode}- {sharedNode}+
); }}
Alternatively, creating a factory function to return a common JSX node could be used instead since the returned value would be a unique instance. For example:
@Component({ tag: 'my-cmp',})export class MyCmp { getText() { return Text
+ Text
Text
; } render() { return ( {this.getText()} {this.getText()}
); }}
Other Resources[](https://stenciljs.com/docs/templating-jsx#other-resources "Direct link to Other Resources")
---------------------------------------------------------------------------------------------------------------
* [Understanding JSX for StencilJS Applications](https://www.joshmorony.com/understanding-jsx-for-stencil-js-applications/)
Contents
--------
* [Basics](https://stenciljs.com/docs/templating-jsx#basics)
* [Host Element](https://stenciljs.com/docs/templating-jsx#host-element)
* [Data Binding](https://stenciljs.com/docs/templating-jsx#data-binding)
* [Conditionals](https://stenciljs.com/docs/templating-jsx#conditionals)
* [Slots](https://stenciljs.com/docs/templating-jsx#slots)
* [Slots Outside Shadow DOM](https://stenciljs.com/docs/templating-jsx#slots-outside-shadow-dom)
* [Dealing with Children](https://stenciljs.com/docs/templating-jsx#dealing-with-children)
* [Automatic Key Insertion](https://stenciljs.com/docs/templating-jsx#automatic-key-insertion)
* [Handling User Input](https://stenciljs.com/docs/templating-jsx#handling-user-input)
* [Complex Template Content](https://stenciljs.com/docs/templating-jsx#complex-template-content)
* [Getting a reference to a DOM element](https://stenciljs.com/docs/templating-jsx#getting-a-reference-to-a-dom-element)
* [Avoid Shared JSX Nodes](https://stenciljs.com/docs/templating-jsx#avoid-shared-jsx-nodes)
* [Other Resources](https://stenciljs.com/docs/templating-jsx#other-resources)
* * *
[Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.35/components/templating-and-jsx.md)
---
# Framework Integration | Stencil
[Skip to main content](https://stenciljs.com/docs/overview#__docusaurus_skipToContent_fallback)
[An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none)
Version: v4.35
Stencil's primary goal is to remove the need for components to be written using a specific framework's API. It accomplishes this by using standardized web platform APIs that work across all modern browsers. Using the low-level component model that is provided by the browser (which all frameworks are built on) allows Stencil components to work inside a framework or without one.
The experience of integrating web components directly into existing applications can be tricky at times, as frameworks have varying support for vanilla web components. In order to accommodate the various issues the Stencil team has created Framework Wrappers to make the process simpler.
The Framework Wrappers are configured like output targets, and emit a native library, just like if your components were originally written using any of these frameworks:
* [Angular](https://stenciljs.com/docs/angular)
* [React](https://stenciljs.com/docs/react)
* [Vue](https://stenciljs.com/docs/vue)
* [Ember (Community)](https://stenciljs.com/docs/ember)
By using Stencil bindings, you can build your components once, and have Stencil emit Angular/React/Vue libraries. This way, the consumers of your components can enjoy all the features of their framework of choice.
---
# Static Site Generation | Stencil
[Skip to main content](https://stenciljs.com/docs/static-site-generation#__docusaurus_skipToContent_fallback)
[An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none)
Version: v4.35
On this page
One of the best ways to build fast, interactive web sites and web apps is to utilize Static Site Generation instead of Server Side Rendering (known as SSR) or Client Side Rendering (known as Single Page Apps, or SPAs).
Static Site Generation (SSG) means building and rendering components and routes at build time (aka prerendering) rather than server request time (SSR) or at client run-time (SPA). Because a route is already prerendered, all of the content for the route is available to search engines and clients _immediately_, so SEO and performance are maximized.
Static Site Generation doesn't mean your pages have to be and/or _stay_ static! Stencil utilizes hydration to efficiently load client-side components at runtime to get the best of both worlds.
Since Static Site Generation prerenders components, there are some tradeoffs and things to keep in mind, but most components can be easily prerendered without much modification.
Stencil makes SSG easy, so read on to see how to incorporate it into your apps.
Benefits of Static Site Generation[](https://stenciljs.com/docs/static-site-generation#benefits-of-static-site-generation "Direct link to Benefits of Static Site Generation")
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
* Great [Lighthouse](https://developers.google.com/web/tools/lighthouse/)
scores
* Faster time to [Largest Contentful Paint (LCP)](https://web.dev/lcp/)
* Better [Search Engine Optimization (SEO)](https://support.google.com/webmasters/answer/7451184)
* Provides functionality for users with JavaScript disabled
How Static Site Generation and Prerendering Works[](https://stenciljs.com/docs/static-site-generation#how-static-site-generation-and-prerendering-works "Direct link to How Static Site Generation and Prerendering Works")
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
**Build Hydrate App**: The first step in prerendering is for the compiler to generate a "hydrate" app, which is a single directory to be used by Node.js. The "hydrate" app is automatically generated when the `--prerender` CLI flag is provided and by default the app is saved to `dist/hydrate`. Prerendering uses the hydrate app internally, however it can be used directly at a lower-level. [Learn more about the Hydrate App](https://stenciljs.com/docs/hydrate-app)
**Fork Prerender Tasks to Available CPUs**: Stencil can efficiently divide out the prerendering to each of the current machine's CPUs using [Node.js' Child Process API](https://nodejs.org/api/child_process.html)
. By tasking each CPU on the machine, the compiler can drastically speed up prerendering times.
**Prerender Index**: After the compiler has completed the build and created child processes on each available CPU, it will then kick off the prerendering by starting at the single base URL, or the configured entry URLs. Once the page has finished prerendering it'll be written to the configured `www` directory as an `index.html` file.
**Crawl App**: During each page prerender, Stencil also collects the anchor elements and URLs used within the page. With this information, it's able to inform the main thread of which pages should be prerendered next. The main thread is in charge of orchestrating all of the URLs, and the job is finished once all of the pages have been crawled and prerendered.
**Deploy Static Files to Production**: Now that all of the pages have been prerendered and written as static HTML files, the `www` directory can now be deployed to a server. A significant difference from prerendering and Server-side Rendering (SSR), is that the HTTP server is just serving up static HTML files rather than dynamically generating the HTML on the server.
**Static HTML Response**: With the static HTML files deploy to a server, visitors of each prerendered page first receive the HTML with inline styles, and no blocking JS or CSS. Additionally, the compiler is already aware of the exact modules the visitor will need for this page, and will asynchronously preload the modules using [link `modulepreload`](https://html.spec.whatwg.org/multipage/links.html#link-type-modulepreload)
.
**Client-side Hydration**: After the HTML and inlined styles have rendered the first paint, the next step is for the same nodes within the DOM to be hydrated by the client-side JavaScript. Each component within the page will asynchronously hydrate using the initial order they were found in the DOM structure. Next, as each component lazily hydrates they're able to reuse the existing nodes found in the DOM.
Tooling[](https://stenciljs.com/docs/static-site-generation#tooling "Direct link to Tooling")
-----------------------------------------------------------------------------------------------
To be clear, Stencil does _not_ use `Puppeteer` or `jsdom` for prerendering. Puppeteer is great for End-to-End testing, but for performance reasons it's not ideal to quickly generate a large website with hundreds or thousands of pages. Additionally, `jsdom` is often used for unit testing, but in our experience it's difficult to use with async components and its global environment nature.
Instead, Stencil uses its own internal DOM APIs which strictly follow the web standards, but optimized for prerendering, Static Site Generation and Server-side Rendering. By doing so, developers can still use all the same APIs they're already familiar with, but they'll seamlessly work within a NodeJS environment too. This means developers often do not have to write code differently in how they're building components, but rather they focus only on writing one type of component, and coding it using the standards they already know. To reiterate, developers do not have to learn a new API for prerendering. It's just the same web APIs your components are already using.
Every component, machine and environment will perform differently, so it's difficult to provide a consistent benchmark. However, what we do know is that [Ionic's Documentation site](https://ionicframework.com/docs)
has hundreds of pages and Stencil is able to prerender the entire site in a few seconds.
Contents
--------
* [Benefits of Static Site Generation](https://stenciljs.com/docs/static-site-generation#benefits-of-static-site-generation)
* [How Static Site Generation and Prerendering Works](https://stenciljs.com/docs/static-site-generation#how-static-site-generation-and-prerendering-works)
* [Tooling](https://stenciljs.com/docs/static-site-generation#tooling)
* * *
[Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.35/static-site-generation/01-overview.md)
---
# Config | Stencil
[Skip to main content](https://stenciljs.com/docs/config#__docusaurus_skipToContent_fallback)
[An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none)
Version: v4.35
On this page
In most cases, the `stencil.config.ts` file does not require any customization since Stencil comes with great default values out-of-the-box. In general, it's preferred to keep the config as minimal as possible. In fact, you could even delete the `stencil.config.ts` file entirely and an app would compile just fine. But at the same time, the compiler can be configured at the lowest levels using this config. Below are the many _optional_ config properties.
Example `stencil.config.ts`:
import { Config } from '@stencil/core';export const config: Config = { namespace: 'MyApp', srcDir: 'src'};
buildDist[](https://stenciljs.com/docs/config#builddist "Direct link to buildDist")
-------------------------------------------------------------------------------------
_default: true (prod), false (dev)_
Sets whether or not Stencil will execute output targets and write output to `dist/` when `stencil build` is called. Defaults to `false` when building for development and `true` when building for production. If set to `true` then Stencil will always build all output targets, regardless of whether the build is in dev or prod mode or using watch mode.
buildDist: true
buildEs5[](https://stenciljs.com/docs/config#buildes5 "Direct link to buildEs5")
----------------------------------------------------------------------------------
Sets if the ES5 build should be generated or not. It defaults to `false`. Setting `buildEs5` to `true` will also create ES5 builds for both dev and prod modes. Setting `buildEs5` to `prod` will only build ES5 in prod mode.
buildEs5: boolean | 'prod'
bundles[](https://stenciljs.com/docs/config#bundles "Direct link to bundles")
-------------------------------------------------------------------------------
By default, Stencil will statically analyze the application and generate a component graph of how all the components are interconnected. From the component graph it is able to best decide how components should be grouped depending on their usage with one another within the app. By doing so it's able to bundle components together in order to reduce network requests. However, bundles can be manually generated using the `bundles` config.
The `bundles` config is an array of objects that represent how components are grouped together in lazy-loaded bundles. This config is rarely needed as Stencil handles this automatically behind the scenes.
bundles: [ { components: ['ion-button'] }, { components: ['ion-card', 'ion-card-header'] }]
cacheDir[](https://stenciljs.com/docs/config#cachedir "Direct link to cacheDir")
----------------------------------------------------------------------------------
_default: '.stencil'_
The directory where sub-directories will be created for caching when [`enableCache`](https://stenciljs.com/docs/config#enablecache)
is set `true` or if using [Stencil's Screenshot Connector](https://stenciljs.com/docs/screenshot-connector)
.
A Stencil config like the following:
stencil.config.ts
import { Config } from '@stencil/core';export const config: Config = { ..., enableCache: true, cacheDir: '.cache', testing: { screenshotConnector: 'connector.js' }}
Will result in the following file structure:
stencil-project-root└── .cache ├── .build <-- Where build related file caching is written | └── screenshot-cache.json <-- Where screenshot caching is written
devServer[](https://stenciljs.com/docs/config#devserver "Direct link to devServer")
-------------------------------------------------------------------------------------
Please see the [Dev-Server docs](https://stenciljs.com/docs/dev-server)
.
docs[](https://stenciljs.com/docs/config#docs "Direct link to docs")
----------------------------------------------------------------------
Please see the [docs config](https://stenciljs.com/docs/docs-config)
.
enableCache[](https://stenciljs.com/docs/config#enablecache "Direct link to enableCache")
-------------------------------------------------------------------------------------------
_default: `true`_
Stencil will cache build results in order to speed up rebuilds. To disable this feature, set `enableCache` to `false`.
enableCache: true
extras[](https://stenciljs.com/docs/config#extras "Direct link to extras")
----------------------------------------------------------------------------
Please see the [Extras docs](https://stenciljs.com/docs/config-extras)
.
env[](https://stenciljs.com/docs/config#env "Direct link to env")
-------------------------------------------------------------------
_default: `{}`_
An object that can hold environment variables for your components to import and use. These variables can hold data objects depending on the environment you compile the components for. For example, let's say we want to provide an URL to our API based on a specific environment, we could provide it as such:
stencil.config.ts
import { Config } from '@stencil/core';export const config: Config = { ..., env: { API_BASE_URL: process.env.API_BASE_URL }}
Now when you build your components with this environment variable set, you can import it in your component as follows:
import { Component, h, Env, Host } from '@stencil/core';@Component({ tag: 'api-component',})export class APIComponent { async connectedCallback () { const res = await fetch(Env.API_BASE_URL) // ... }}
generateExportMaps[](https://stenciljs.com/docs/config#generateexportmaps "Direct link to generateExportMaps")
----------------------------------------------------------------------------------------------------------------
_default: `false`_
Stencil will generate [export maps](https://nodejs.org/api/packages.html#packages_exports)
that correspond with various output target outputs. This includes the root entry point based on the [primary output target](https://stenciljs.com/docs/output-targets#primary-package-output-target-validation)
(or first eligible output target if not specified), the entry point for the lazy-loader (if using the `dist` output target), and entry points for each component (if using `dist-custom-elements`).
globalScript[](https://stenciljs.com/docs/config#globalscript "Direct link to globalScript")
----------------------------------------------------------------------------------------------
The global script config option takes a file path as a string.
The global script runs once before your library/app loads, so you can do things like setting up a connection to an external service or configuring a library you are using.
The code to be executed should be placed within a default function that is exported by the global script. Ensure all of the code in the global script is wrapped in the function that is exported:
export default function() { // or export default async function() initServerConnection();}
note
The exported function can also be `async` but be aware that this can have implications on the performance of your application as all rendering operations will be deferred until after the global script finishes.
Imported methods from Stencil, such as `setMode`, `BUILD` and others, can only be accessed within the function exported by the script. They will not be available in the global scope outside of this function.
import { setMode, BUILD } from '@stencil/core';// ❌ This won't work as Stencil primitives are not initialized at this point// console.log('Build mode:', BUILD.isDev);export default function() { // ✅ This works - Stencil methods are available within the exported function if (BUILD.isDev) { console.log('Development mode detected'); setMode((elm) => elm.getAttribute('mode') || 'dev'); } else { console.log('Production mode'); setMode((elm) => elm.getAttribute('mode') || 'prod'); }}
globalStyle[](https://stenciljs.com/docs/config#globalstyle "Direct link to globalStyle")
-------------------------------------------------------------------------------------------
Stencil is traditionally used to compile many components into an app, and each component comes with its own compartmentalized styles. However, it's still common to have styles which should be "global" across all components and the website. A global CSS file is often useful to set [CSS Variables](https://stenciljs.com/docs/styling)
.
Additionally, the `globalStyle` config can be used to precompile styles with Sass, PostCSS, etc.
Below is an example folder structure containing a webapp's global css file, named `app.css`.
src/ components/ global/ app.css
The global style config takes a file path as a string. The output from this build will go to the `buildDir`. In this example it would be saved to `www/build/app.css`. Additionally, these global styles are automatically applied to all components with shadow roots via constructable stylesheets, allowing you to style shadow DOM components directly.
globalStyle: 'src/global/app.css'
Check out the [styling docs](https://stenciljs.com/docs/styling#global-styles)
of how to use global styles in your app.
hashedFileNameLength[](https://stenciljs.com/docs/config#hashedfilenamelength "Direct link to hashedFileNameLength")
----------------------------------------------------------------------------------------------------------------------
_default: `8`_
When the `hashFileNames` config is set to `true`, and it is a production build, the `hashedFileNameLength` config is used to determine how many characters the file name's hash should be.
hashedFileNameLength: 8
hashFileNames[](https://stenciljs.com/docs/config#hashfilenames "Direct link to hashFileNames")
-------------------------------------------------------------------------------------------------
_default: `true`_
During production builds, the content of each generated file is hashed to represent the content, and the hashed value is used as the filename. If the content isn't updated between builds, then it receives the same filename. When the content is updated, then the filename is different. By doing this, deployed apps can "forever-cache" the build directory and take full advantage of content delivery networks (CDNs) and heavily caching files for faster apps.
hashFileNames: true
hydratedFlag[](https://stenciljs.com/docs/config#hydratedflag "Direct link to hydratedFlag")
----------------------------------------------------------------------------------------------
When using the [lazy build](https://stenciljs.com/docs/distribution)
Stencil has support for automatically applying a class or attribute to a component and all of its child components when they have finished hydrating. This can be used to prevent a [flash of unstyled content (FOUC)](https://en.wikipedia.org/wiki/Flash_of_unstyled_content)
, a typically-undesired 'flicker' of unstyled HTML that might otherwise occur during component rendering while various components are asynchronously downloaded and rendered.
By default, Stencil will add the `hydrated` CSS class to elements to indicate hydration. The `hydratedFlag` config field allows this behavior to be customized, by changing the name of the applied CSS class, setting it to use an attribute to indicate hydration, or changing which type of CSS properties and values are assigned before and after hydrating. This config can also be used to turn off this behavior by setting it to `null`.
If a Stencil configuration does not supply a value for `hydratedFlag` then Stencil will automatically generate the following default configuration:
const defaultHydratedFlag: HydratedFlag = { hydratedValue: 'inherit', initialValue: 'hidden', name: 'hydrated', property: 'visibility', selector: 'class',};
If `hydratedFlag` is explicitly set to `null`, Stencil will not set a default configuration and the behavior of marking hydration with a class or attribute will be disabled.
hydratedFlag: null | { name?: string, selector?: 'class' | 'attribute', property?: string, initialValue?: string, hydratedValue?: string}
The supported options are as follows:
### name[](https://stenciljs.com/docs/config#name "Direct link to name")
_default: 'hydrated'_
The name which Stencil will use for the attribute or class that it sets on elements to indicate that they are hydrated.
name: string
### selector[](https://stenciljs.com/docs/config#selector "Direct link to selector")
_default: 'class'_
The way that Stencil will indicate that a component has been hydrated. When `'class'`, Stencil will set the `name` option on the element as a class, and when `'attribute'`, Stencil will similarly set the `name` option as an attribute.
selector: 'class' | 'attribute'
### property[](https://stenciljs.com/docs/config#property "Direct link to property")
_default: 'visibility'_
The CSS property used to show and hide components. This defaults to the CSS `visibility` property. Other possible CSS properties might include `display` with the `initialValue` setting as `none`, or `opacity` with the `initialValue` as `0`. Defaults to `visibility`.
property: string
### initialValue[](https://stenciljs.com/docs/config#initialvalue "Direct link to initialValue")
_default: 'hidden'_
This is the value which should be set for the property specified by `property` on all components before hydration.
initialValue: string
### hydratedValue[](https://stenciljs.com/docs/config#hydratedvalue "Direct link to hydratedValue")
_default: 'inherit'_
This is the value which should be set for the property specified by `property` on all components once they've completed hydration.
hydratedValue: string
invisiblePrehydration[](https://stenciljs.com/docs/config#invisibleprehydration "Direct link to invisiblePrehydration")
-------------------------------------------------------------------------------------------------------------------------
_default: `true`_
When `true`, `invisiblePrehydration` will visually hide components before they are hydrated by adding an automatically injected style tag to the document's head. Setting `invisiblePrehydration` to `false` will not inject the style tag into the head, allowing you to style your web components pre-hydration.
note
Setting `invisiblePrehydration` to `false` will cause everything to be visible when your page is loaded, causing a more prominent Flash of Unstyled Content (FOUC). However, you can style your web component's fallback content to your preference.
invisiblePrehydration: true
minifyCss[](https://stenciljs.com/docs/config#minifycss "Direct link to minifyCss")
-------------------------------------------------------------------------------------
_default: `true` in production_
When `true`, the browser CSS file will be minified.
minifyJs[](https://stenciljs.com/docs/config#minifyjs "Direct link to minifyJs")
----------------------------------------------------------------------------------
_default: `true` in production_
When `true`, the browser JS files will be minified. Stencil uses [Terser](https://terser.org/)
under-the-hood for file minification.
namespace[](https://stenciljs.com/docs/config#namespace "Direct link to namespace")
-------------------------------------------------------------------------------------
_default: `App`_
The `namespace` config is a `string` representing a namespace for the app. For apps that are not meant to be a library of reusable components, the default of `App` is just fine. However, if the app is meant to be consumed as a third-party library, such as `Ionic`, a unique namespace is required.
namespace: "Ionic"
outputTargets[](https://stenciljs.com/docs/config#outputtargets "Direct link to outputTargets")
-------------------------------------------------------------------------------------------------
Please see the [Output Target docs](https://stenciljs.com/docs/output-targets)
.
plugins[](https://stenciljs.com/docs/config#plugins "Direct link to plugins")
-------------------------------------------------------------------------------
Please see the [Plugin docs](https://stenciljs.com/docs/plugins)
.
preamble[](https://stenciljs.com/docs/config#preamble "Direct link to preamble")
----------------------------------------------------------------------------------
_default: `undefined`_
Used to help to persist a banner or add relevant information about the resulting build, the `preamble` configuration field is a `string` that will be converted into a pinned comment and placed at the top of all emitted JavaScript files, with the exception of any emitted polyfills. Escaped newlines may be placed in the provided value for this field and will be honored by Stencil.
Example:
preamble: 'Built with Stencil\nCopyright (c) SomeCompanyInc.'
Will generate the following comment:
/*! * Built with Stencil * Copyright (c) SomeCompanyInc. */
sourceMap[](https://stenciljs.com/docs/config#sourcemap "Direct link to sourceMap")
-------------------------------------------------------------------------------------
_default: `true`_
When omitted or set to `true`, sourcemaps will be generated for a project. When set to `false`, sourcemaps will not be generated.
sourceMap: true | false
Sourcemaps create a translation between Stencil components that are written in TypeScript/JSX and the resulting JavaScript that is output by Stencil. Enabling source maps in your project allows for an improved debugging experience for Stencil components. For example, they allow external tools (such as an Integrated Development Environment) to add breakpoints directly in the original source code, which allows you to 'step through' your code line-by-line, to inspect the values held in variables, to observe logic flow, and more.
Please note: Stencil will always attempt to minify a component's source code as much as possible during compilation. When `sourceMap` is enabled, it is possible that a slightly different minified result will be produced by Stencil when compared to the minified result produced when `sourceMap` is not enabled.
Developers are responsible for determining whether or not they choose to serve sourcemaps in each environment their components are served and implementing their decision accordingly.
srcDir[](https://stenciljs.com/docs/config#srcdir "Direct link to srcDir")
----------------------------------------------------------------------------
_default: `src`_
The `srcDir` config specifies the directory which should contain the source typescript files for each component. The standard for Stencil apps is to use `src`, which is the default.
srcDir: 'src'
taskQueue[](https://stenciljs.com/docs/config#taskqueue "Direct link to taskQueue")
-------------------------------------------------------------------------------------
_default: `async`_
Sets the task queue used by stencil's runtime. The task queue schedules DOM read and writes across the frames to efficiently render and reduce layout thrashing. By default, the `async` is used. It's recommended to also try each setting to decide which works best for your use-case. In all cases, if your app has many CPU intensive tasks causing the main thread to periodically lock-up, it's always recommended to try [Web Workers](https://stenciljs.com/docs/web-workers)
for those tasks.
* `congestionAsync`: DOM reads and writes are scheduled in the next frame to prevent layout thrashing. When the app is heavily tasked and the queue becomes congested it will then split the work across multiple frames to prevent blocking the main thread. However, it can also introduce unnecessary reflows in some cases, especially during startup. `congestionAsync` is ideal for apps running animations while also simultaneously executing intensive tasks which may lock-up the main thread.
* `async`: DOM read and writes are scheduled in the next frame to prevent layout thrashing. During intensive CPU tasks it will not reschedule rendering to happen in the next frame. `async` is ideal for most apps, and if the app has many intensive tasks causing the main thread to lock-up, it's recommended to try [Web Workers](https://stenciljs.com/docs/web-workers)
rather than the congestion async queue.
* `immediate`: Makes writeTask() and readTask() callbacks to be executed synchronously. Tasks are not scheduled to run in the next frame, but do note there is at least one microtask. The `immediate` setting is ideal for apps that do not provide long-running and smooth animations. Like the async setting, if the app has intensive tasks causing the main thread to lock-up, it's recommended to try [Web Workers](https://stenciljs.com/docs/web-workers)
.
taskQueue: 'async'
testing[](https://stenciljs.com/docs/config#testing "Direct link to testing")
-------------------------------------------------------------------------------
Please see the [testing config docs](https://stenciljs.com/docs/testing-config)
.
transformAliasedImportPaths[](https://stenciljs.com/docs/config#transformaliasedimportpaths "Direct link to transformAliasedImportPaths")
-------------------------------------------------------------------------------------------------------------------------------------------
_default: `true`_
This sets whether or not Stencil should transform [path aliases](https://www.typescriptlang.org/docs/handbook/module-resolution.html#path-mapping)
set in a project's `tsconfig.json` from the assigned module aliases to resolved relative paths. This will not transform external imports (like `@stencil/core`) or relative imports (like `'../utils'`).
This option applies globally and will affect all code processed by Stencil, including `.d.ts` files and spec tests.
An example of path transformation could look something like the following.
First, a set of `paths` aliases in `tsconfig.json`:
tsconfig.json
{ "compilerOptions": { "paths": { "@utils": [ "../path/to/utils" ] } }}
Then with the following input:
src/my-module.ts
import { utilFunc, UtilInterface } from '@utils'export function util(arg: UtilInterface) { utilFunc(arg)}
Stencil will produce the following output:
dist/my-module.js
import { utilFunc } from '../path/to/utils';export function util(arg) { utilFunc(arg);}
dist/my-module.d.ts
import { UtilInterface } from '../path/to/utils';export declare function util(arg: UtilInterface): void;
validatePrimaryPackageOutputTarget[](https://stenciljs.com/docs/config#validateprimarypackageoutputtarget "Direct link to validatePrimaryPackageOutputTarget")
----------------------------------------------------------------------------------------------------------------------------------------------------------------
_default: `false`_
When `true`, validation for common `package.json` fields will occur based on setting an output target's `isPrimaryPackageOutputTarget` flag. For more information on package validation, please see the [output target docs](https://stenciljs.com/docs/output-targets#primary-package-output-target-validation)
.
rollupConfig[](https://stenciljs.com/docs/config#rollupconfig "Direct link to rollupConfig")
----------------------------------------------------------------------------------------------
Passes custom configuration down to rollup itself. The following options can be overwritten:
* `inputOptions`: [`context`](https://rollupjs.org/configuration-options/#context)
, [`external`](https://rollupjs.org/configuration-options/#external)
, [`moduleContext`](https://rollupjs.org/configuration-options/#modulecontext)
[`treeshake`](https://rollupjs.org/configuration-options/#treeshake)
* `outputOptions`: [`globals`](https://rollupjs.org/configuration-options/#output-globals)
_default: `{}`_
watchIgnoredRegex[](https://stenciljs.com/docs/config#watchignoredregex "Direct link to watchIgnoredRegex")
-------------------------------------------------------------------------------------------------------------
_default: `[]`_
_type: `RegExp | RegExp[]`_
A regular expression (or array of regular expressions) that can be used to omit files from triggering a rebuild in watch mode. During compile-time, each file in the Stencil project will be tested against each regular expression to determine if changes to the file (or directory) should trigger a project rebuild.
note
If you want to ignore TS files such as `.ts`/`.js` or `.tsx`/`.jsx` extensions, these files will also need to be specified in your project's tsconfig's [`watchOptions`](https://www.typescriptlang.org/docs/handbook/configuring-watch.html#configuring-file-watching-using-a-tsconfigjson)
_in addition_ to the `watchIgnoredRegex` option. For instance, if we wanted to ignore the `my-component.tsx` file, we'd specify:
tsconfig.json
{ ..., "watchOptions": { "excludeFiles": ["src/components/my-component/my-component.tsx"] }}
Contents
--------
* [buildDist](https://stenciljs.com/docs/config#builddist)
* [buildEs5](https://stenciljs.com/docs/config#buildes5)
* [bundles](https://stenciljs.com/docs/config#bundles)
* [cacheDir](https://stenciljs.com/docs/config#cachedir)
* [devServer](https://stenciljs.com/docs/config#devserver)
* [docs](https://stenciljs.com/docs/config#docs)
* [enableCache](https://stenciljs.com/docs/config#enablecache)
* [extras](https://stenciljs.com/docs/config#extras)
* [env](https://stenciljs.com/docs/config#env)
* [generateExportMaps](https://stenciljs.com/docs/config#generateexportmaps)
* [globalScript](https://stenciljs.com/docs/config#globalscript)
* [globalStyle](https://stenciljs.com/docs/config#globalstyle)
* [hashedFileNameLength](https://stenciljs.com/docs/config#hashedfilenamelength)
* [hashFileNames](https://stenciljs.com/docs/config#hashfilenames)
* [hydratedFlag](https://stenciljs.com/docs/config#hydratedflag)
* [name](https://stenciljs.com/docs/config#name)
* [selector](https://stenciljs.com/docs/config#selector)
* [property](https://stenciljs.com/docs/config#property)
* [initialValue](https://stenciljs.com/docs/config#initialvalue)
* [hydratedValue](https://stenciljs.com/docs/config#hydratedvalue)
* [invisiblePrehydration](https://stenciljs.com/docs/config#invisibleprehydration)
* [minifyCss](https://stenciljs.com/docs/config#minifycss)
* [minifyJs](https://stenciljs.com/docs/config#minifyjs)
* [namespace](https://stenciljs.com/docs/config#namespace)
* [outputTargets](https://stenciljs.com/docs/config#outputtargets)
* [plugins](https://stenciljs.com/docs/config#plugins)
* [preamble](https://stenciljs.com/docs/config#preamble)
* [sourceMap](https://stenciljs.com/docs/config#sourcemap)
* [srcDir](https://stenciljs.com/docs/config#srcdir)
* [taskQueue](https://stenciljs.com/docs/config#taskqueue)
* [testing](https://stenciljs.com/docs/config#testing)
* [transformAliasedImportPaths](https://stenciljs.com/docs/config#transformaliasedimportpaths)
* [validatePrimaryPackageOutputTarget](https://stenciljs.com/docs/config#validateprimarypackageoutputtarget)
* [rollupConfig](https://stenciljs.com/docs/config#rollupconfig)
* [watchIgnoredRegex](https://stenciljs.com/docs/config#watchignoredregex)
* * *
[Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.35/config/01-overview.md)
---
# Stencil Core Dev Server API | Stencil
[Skip to main content](https://stenciljs.com/docs/dev-server-api#__docusaurus_skipToContent_fallback)
[An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none)
Version: v4.35
On this page
The CLI API can be found at `@stencil/core/dev-server`.
start()[](https://stenciljs.com/docs/dev-server-api#start "Direct link to start()")
-------------------------------------------------------------------------------------
start(stencilDevServerConfig: StencilDevServerConfig, logger: Logger, watcher?: CompilerWatcher): Promise * * Hello, World! I'm Stencil 'Don't call me a framework' JS *
* * * * * Hello, World! I'm Stencil 'Don't call me a framework' JS *
* * * * * Hello, World! I'm Stencil 'Don't call me a framework' JS *
* * * Hello, World! I'm Stencil 'Don't call me a framework' JS *
* * * * * Hello, World! I'm Stencil 'Don't call me a framework' JS *
* * * * * Hello, World! I'm Stencil 'Don't call me a framework' JS *
* Hello, {props.name}!
; When the JSX transpiler encounters such a component, it will take its attributes, pass them into the function as the `props` object, and replace the component with the JSX that is returned by the function.Hello, {props.name}
, children]; The JSX transpiler passes all child elements of the component as an array into the function's `children` argument.I'm a child element.
Hello, {name}!
); Working with children[](https://stenciljs.com/docs/v4.34/functional-components#working-with-children "Direct link to Working with children") ---------------------------------------------------------------------------------------------------------------------------------------------- The second argument of a functional component receives the passed children, but in order to work with them, `FunctionalComponent` provides a utils object that exposes a `map()` method to transform the children, and a `forEach()` method to read them. Reading the `children` array is not recommended since the stencil compiler can rename the vNode properties in prod mode. export interface FunctionalUtilities { forEach: (children: VNode[], cb: (vnode: ChildNode, index: number, array: ChildNode[]) => void) => void; map: (children: VNode[], cb: (vnode: ChildNode, index: number, array: ChildNode[]) => ChildNode) => VNode[];}export interface ChildNode { vtag?: string | number | Function; vkey?: string | number; vtext?: string; vchildren?: VNode[]; vattrs?: any; vname?: string;} **Example:** export const AddClass: FunctionalComponent = (_, children, utils) => ( utils.map(children, child => ({ ...child, vattrs: { ...child.vattrs, class: `${child.vattrs.class} add-class` } } ))); note When using a functional component in JSX, its name must start with a capital letter. Therefore it makes sense to export it as such. Disclaimer[](https://stenciljs.com/docs/v4.34/functional-components#disclaimer "Direct link to Disclaimer") ------------------------------------------------------------------------------------------------------------- There are a few major differences between functional components and class components. Since functional components are just syntactic sugar within JSX, they... * aren't compiled into web components, * don't create a DOM node, * don't have a Shadow DOM or scoped styles, * don't have lifecycle hooks, * are stateless. When deciding whether to use functional components, one concept to keep in mind is that often the UI of your application can be a function of its state, i. e., given the same state, it always renders the same UI. If a component has to hold state, deal with events, etc, it should probably be a class component. If a component's purpose is to simply encapsulate some markup so it can be reused across your app, it can probably be a functional component (especially if you're using a component library and thus don't need to style it). caution Stencil does not support re-exporting a functional component from a "barrel file" and dynamically rendering it in another component. This is a [known limitation](https://github.com/ionic-team/stencil/issues/5246) within Stencil. Instead, either use class components and remove the import or import the functional component directly. Contents -------- * [Working with children](https://stenciljs.com/docs/v4.34/functional-components#working-with-children) * [Disclaimer](https://stenciljs.com/docs/v4.34/functional-components#disclaimer) * * * [Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.34/components/functional-components.md) --- # Stencil Output Targets | Stencil [Skip to main content](https://stenciljs.com/docs/output-targets#__docusaurus_skipToContent_fallback) [An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none) Version: v4.35 On this page One of the more powerful features of the compiler is its ability to generate various builds depending on _"how"_ the components are going to be used. Stencil is able to take an app's source and compile it to numerous targets, such as a webapp to be deployed on an http server, as a third-party component lazy-loaded library to be distributed on [npm](https://www.npmjs.com/) , or a vanilla custom elements bundle. By default, Stencil apps have an output target type of `www`, which is best suited for a webapp. Output Target Types:[](https://stenciljs.com/docs/output-targets#output-target-types "Direct link to Output Target Types:") ----------------------------------------------------------------------------------------------------------------------------- * [`dist`: Distribution](https://stenciljs.com/docs/distribution) * [`www`: Website](https://stenciljs.com/docs/www) * [`dist-custom-elements`: Custom Elements](https://stenciljs.com/docs/custom-elements) Example:[](https://stenciljs.com/docs/output-targets#example "Direct link to Example:") ----------------------------------------------------------------------------------------- import { Config } from '@stencil/core';export const config: Config = { outputTargets: [ { type: 'dist' }, { type: 'www' } ]}; Primary Package Output Target Validation[](https://stenciljs.com/docs/output-targets#primary-package-output-target-validation "Direct link to Primary Package Output Target Validation") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ If `validatePrimaryPackageOutputTarget: true` is set in your project's [Stencil config](https://stenciljs.com/docs/config#validateprimarypackageoutputtarget) Stencil will attempt to validate certain fields in your `package.json` that correspond with the generated distribution code. Because Stencil can output many different formats from a single project, it can only validate that the `package.json` has field values that align with one of the specified output targets in your project's config. So, Stencil allows you to designate which output target should be used for this validation and thus which will be the default distribution when bundling your project. This behavior only affects a small subset of output targets so a flag exists on the following targets that are eligible for this level of validation: `dist`, `dist-types`, `dist-collection`, and `dist-custom-elements`. For any of these output targets, you can configure the target to be validated as follows: stencil.config.ts import { Config } from '@stencil/core';export const config: Config = { ..., outputTargets: [ { type: 'dist', // This flag is what tells Stencil to use this target for validation isPrimaryPackageOutputTarget: true, ... }, ... ], // If this is not set, Stencil will not validate any targets validatePrimaryPackageOutputTarget: true,}; note Stencil can only validate one of these output targets for your build. If multiple output targets are marked for validation, Stencil will use the first designated target in the array and ignore all others. Contents -------- * [Output Target Types:](https://stenciljs.com/docs/output-targets#output-target-types) * [Example:](https://stenciljs.com/docs/output-targets#example) * [Primary Package Output Target Validation](https://stenciljs.com/docs/output-targets#primary-package-output-target-validation) * * * [Edit this page](https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.35/output-targets/01-overview.md) --- # Upgrading to Stencil v4.0.0 | Stencil [Skip to main content](https://stenciljs.com/docs/introduction/upgrading-to-stencil-four#__docusaurus_skipToContent_fallback) [An **OutSystems** Company →](https://www.outsystems.com/?utm_source=ionic&utm_medium=referral&utm_campaign=ionic-referral&utm_term=none&utm_content=other&utm_campaignteam=digital-mktg&utm_partner=none) Version: v4.35 On this page Getting Started[](https://stenciljs.com/docs/introduction/upgrading-to-stencil-four#getting-started "Direct link to 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: * [Stencil v3 Breaking Changes](https://github.com/ionic-team/stencil/blob/main/BREAKING_CHANGES.md#stencil-v300) * [Stencil v2 Breaking Changes](https://github.com/ionic-team/stencil/blob/main/BREAKING_CHANGES.md#stencil-two) * [Stencil v1 Breaking Changes](https://github.com/ionic-team/stencil/blob/main/BREAKING_CHANGES.md#stencil-one) For projects that are on Stencil v3, install the latest version of Stencil v4: `npm install @stencil/core@4` Updating Your Code[](https://stenciljs.com/docs/introduction/upgrading-to-stencil-four#updating-your-code "Direct link to Updating Your Code") ------------------------------------------------------------------------------------------------------------------------------------------------ ### New Configuration Defaults[](https://stenciljs.com/docs/introduction/upgrading-to-stencil-four#new-configuration-defaults "Direct link to 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`[](https://stenciljs.com/docs/introduction/upgrading-to-stencil-four#transformaliasedimportpaths "Direct link to transformaliasedimportpaths") TypeScript projects have the ability to specify a path aliases via the [`paths` configuration in their `tsconfig.json`](https://www.typescriptlang.org/docs/handbook/module-resolution.html#path-mapping) 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](https://github.com/ionic-team/stencil/releases/tag/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](https://github.com/ionic-team/stencil/issues/new?assignees=&labels=&projects=&template=bug_report.yml&title=bug%3A+) . 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](https://stenciljs.com/docs/config#transformaliasedimportpaths) #### `transformAliasedImportPathsInCollection`[](https://stenciljs.com/docs/introduction/upgrading-to-stencil-four#transformaliasedimportpathsincollection "Direct link to transformaliasedimportpathsincollection") Introduced in [Stencil v2.18.0](https://github.com/ionic-team/stencil/releases/tag/v2.18.0) , `transformAliasedImportPathsInCollection` is a configuration flag on the [`dist` output target](https://stenciljs.com/docs/distribution#transformaliasedimportpathsincollection) . `transformAliasedImportPathsInCollection` transforms import paths, similar to [`transformAliasedImportPaths`](https://stenciljs.com/docs/introduction/upgrading-to-stencil-four#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). For users that run into issues with this new default, we encourage you to file a [new issue on the Stencil GitHub repo](https://github.com/ionic-team/stencil/issues/new?assignees=&labels=&projects=&template=bug_report.yml&title=bug%3A+) . As a workaround, this flag can be set to `false` to disable the default functionality. 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](https://stenciljs.com/docs/distribution#transformaliasedimportpathsincollection) . ### In Browser Compilation Support Removed[](https://stenciljs.com/docs/introduction/upgrading-to-stencil-four#in-browser-compilation-support-removed "Direct link to 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](https://github.com/ionic-team/stencil/discussions/4134) on the Stencil GitHub Discussions page. ### Legacy Context and Connect APIs Removed[](https://stenciljs.com/docs/introduction/upgrading-to-stencil-four#legacy-context-and-connect-apis-removed "Direct link to 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 Hello, World! I'm John Doe
Content
Hello, World! I'm Inline Test