Stencil

https://stenciljs.com/docs
Admin
Stencil is a compiler that generates standards-compliant Web Components using TypeScript, JSX, and...
Tokens:112,721
Snippets:1,496
Trust Score:9.8
Update:3 months ago
Show doc for...
Tokens:
Raw
### Vitest Setup File

Source: https://stenciljs.com/docs/testing-vitest-configuration

Example setup file to load Stencil components before tests execute.

```typescript
// Load Stencil components.
// Adjust according to your build output of choice
await import('./dist/test-components/test-components.esm.js');

export {};
```

--------------------------------

### start()

Source: https://stenciljs.com/docs/dev-server-api

Initializes and starts the Stencil development server with the provided configuration, logger, and optional watcher.

```APIDOC
## start()

### Description
Starts the Stencil development server instance.

### Signature
`start(stencilDevServerConfig: StencilDevServerConfig, logger: Logger, watcher?: CompilerWatcher): Promise<DevServer>`

### Parameters
- **stencilDevServerConfig** (StencilDevServerConfig) - Required - Configuration object for the dev server.
- **logger** (Logger) - Required - Logger instance for output.
- **watcher** (CompilerWatcher) - Optional - Compiler watcher instance.
```

--------------------------------

### Install @stencil/store

Source: https://stenciljs.com/docs/stencil-store

Commands to install the library using various package managers.

```bash
npm install @stencil/store --save-dev
```

```bash
yarn add @stencil/store --dev
```

```bash
pnpm add @stencil/store --save-dev
```

--------------------------------

### Run browser tests in CI/CD

Source: https://stenciljs.com/docs/testing-vitest-cli

Example GitHub Actions workflow step for installing browser dependencies and running tests in a CI environment.

```yaml
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: npx playwright install --with-deps chromium
      - run: npm run test -- --project browser
```

--------------------------------

### Bootstrap the project dependencies

Source: https://stenciljs.com/docs/getting-started

Navigate to the project directory and install dependencies to begin development.

```bash
cd my-first-stencil-project
npm install
npm start
```

```bash
cd my-first-stencil-project
yarn install
yarn start
```

```bash
cd my-first-stencil-project
pnpm install
pnpm start
```

--------------------------------

### Register components in setup file

Source: https://stenciljs.com/docs/testing-vitest-migration

Load components via the setup file instead of passing them to the render function.

```typescript
// vitest-setup.ts
await import('./dist/test-components/test-components.esm.js');
```

--------------------------------

### Example Project Structure

Source: https://stenciljs.com/docs/react

Recommended monorepo layout for managing Stencil and React libraries.

```text
top-most-directory/
└── packages/
    ├── stencil-library/
    │   ├── stencil.config.js
    │   └── src/components/
    └── react-library/
        └── src/
            ├── components/
            └── index.ts
```

--------------------------------

### Install library dependencies

Source: https://stenciljs.com/docs/custom-elements

Commands to install a published component library using various package managers.

```bash
npm install my-library
```

```bash
yarn add my-library
```

```bash
pnpm add my-library
```

--------------------------------

### Install @stencil/vitest dependencies

Source: https://stenciljs.com/docs/testing-vitest

Install the core testing package and Vitest using your preferred package manager.

```bash
npm install --save-dev @stencil/vitest vitest
```

```bash
yarn add --dev @stencil/vitest vitest
```

```bash
pnpm add --save-dev @stencil/vitest vitest
```

--------------------------------

### Install browser testing dependencies

Source: https://stenciljs.com/docs/testing-vitest-migration

Install Playwright support for browser-based testing.

```bash
npm install --save-dev @vitest/browser-playwright
```

```bash
yarn add --dev @vitest/browser-playwright
```

```bash
pnpm add --save-dev @vitest/browser-playwright
```

--------------------------------

### Create a starter React application

Source: https://stenciljs.com/docs/react

Commands to scaffold a new React application using Vite and install dependencies.

```bash
# Create the React app
npm create vite@latest my-app -- --template react-ts
# of if using yarn
yarn create vite my-app --template react-ts

cd ./my-app

# install dependencies
npm install
# or if using yarn
yarn install
```

--------------------------------

### Initialize Monorepo Workspace

Source: https://stenciljs.com/docs/angular

Commands to initialize a Lerna workspace and install necessary dependencies.

```bash
# From your top-most-directory/, initialize a workspace
lerna init

# install dependencies
npm install

# install typescript and node types
npm install typescript @types/node --save-dev
```

```bash
# From your top-most-directory/, initialize a workspace
lerna init

# install dependencies
yarn install

# install typescript and node types
yarn add typescript @types/node --dev
```

```bash
# From your top-most-directory/, initialize a workspace
lerna init

# install dependencies
pnpm install

# install typescript and node types
pnpm add typescript @types/node --save-dev
```

--------------------------------

### Install DOM Environment Dependencies

Source: https://stenciljs.com/docs/testing-vitest-configuration

Commands to install required packages for jsdom or happy-dom.

```bash
npm install --save-dev jsdom
# or
npm install --save-dev happy-dom
```

```bash
yarn add --dev jsdom
# or
yarn add --dev happy-dom
```

```bash
pnpm add --save-dev jsdom
# or
pnpm add --save-dev happy-dom
```

--------------------------------

### Esbuild Warning Example

Source: https://stenciljs.com/docs/angular

Example of a known esbuild warning that may appear during the build process.

```text
▲ [WARNING] The glob pattern import("./**/.entry.js") did not match any files [empty-glob]

node_modules/@stencil/core/internal/client/index.js:3808:2:
  3808 │   `./${bundleId}.entry.js${BUILD.hotModuleReplacement && hmrVers...
       ╵   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
```

--------------------------------

### Run Full Build in NodeJS

Source: https://stenciljs.com/docs/compiler-api

Example of setting up a logger, system, and configuration to execute a full build process.

```typescript
import { createNodeLogger, createNodeSys } from '@stencil/core/sys/node';
import { createCompiler, loadConfig } from '@stencil/core/compiler';

const logger = createNodeLogger(process);
const sys = createNodeSys(process);
const validated = await loadConfig({
  logger,
  sys,
  config: {
    /* user config */
  },
});
const compiler = await createCompiler(validated.config);
const results = await compiler.build();
```

--------------------------------

### Launch Storybook

Source: https://stenciljs.com/docs/storybook

Command to start the Storybook development server after building the Stencil project.

```bash
npm run storybook
```

--------------------------------

### Install React Output Target Runtime Dependency

Source: https://stenciljs.com/docs/react

Install the package as a standard dependency in your React component library.

```bash
# Install dependency
npm install @stencil/react-output-target --save
```

```bash
# Install dependency
yarn add @stencil/react-output-target
```

```bash
# Install dependency
pnpm add @stencil/react-output-target
```

--------------------------------

### Install Lerna Globally

Source: https://stenciljs.com/docs/angular

Commands to install Lerna using different package managers.

```bash
npm install --global lerna
```

```bash
yarn global add lerna
```

```bash
pnpm add --global lerna
```

--------------------------------

### Install build dependencies

Source: https://stenciljs.com/docs/vue

Install rollup and rimraf as development dependencies using your preferred package manager.

```bash
npm i -D rollup rimraf
```

```bash
yarn add --dev rollup rimraf
```

```bash
pnpm add -D rollup rimraf
```

--------------------------------

### Define component usage example

Source: https://stenciljs.com/docs/docs-readme

Create a markdown file in the component's usage directory to demonstrate component implementation.

```html
<my-component first="Stencil"></my-component>
<my-component first="Stencil" last="JS"></my-component>
```

--------------------------------

### Install Storybook Dependencies

Source: https://stenciljs.com/docs/storybook

Install the required dev dependencies for Storybook 8 and the Stencil plugin.

```bash
npm install --save-dev storybook@8 @storybook/addon-essentials@8 @storybook/addon-links@8 @storybook/addon-interactions@8 @stencil/core@latest @stencil/storybook-plugin
```

--------------------------------

### Example Snapshot Output

Source: https://stenciljs.com/docs/testing-vitest-writing-tests

Represents the serialized output of a component containing a shadow root.

```html
<my-component>
  <mock:shadow-root>
    <button class="primary">
      <slot />
    </button>
  </mock:shadow-root>
  Click me
</my-component>
```

--------------------------------

### Install Stencil SSR package

Source: https://stenciljs.com/docs/server-side-rendering

Install the required dependency for server-side serialization of Stencil components.

```bash
npm install --save-dev @stencil/ssr
```

--------------------------------

### Install Vue Output Target Dependency

Source: https://stenciljs.com/docs/vue

Install the required development dependency for the Stencil component library.

```bash
# Install dependency (from `packages/stencil-library`)
npm install @stencil/vue-output-target --save-dev
```

```bash
# Install dependency (from `packages/stencil-library`)
yarn add @stencil/vue-output-target --dev
```

```bash
# Install dependency (from `packages/stencil-library`)
pnpm add @stencil/vue-output-target --save-dev
```

--------------------------------

### Start the Stencil Dev Server

Source: https://stenciljs.com/docs/dev-server-api

Initializes the development server using the provided configuration, logger, and optional compiler watcher.

```typescript
start(stencilDevServerConfig: StencilDevServerConfig, logger: Logger, watcher?: CompilerWatcher): Promise<DevServer>
```

--------------------------------

### Initialize React Library Package

Source: https://stenciljs.com/docs/react

Commands to create a new package and install necessary dependencies for React and Stencil output targets.

```bash
# Create a project
lerna create react-library # fill out the prompts accordingly
cd packages/react-library

# Install core dependencies
npm install react react-dom typescript @types/react --save-dev

# Install output target runtime dependency
npm install @stencil/react-output-target --save
```

```bash
# Create a project
lerna create react-library # fill out the prompts accordingly
cd packages/react-library

# Install core dependencies
yarn add react react-dom typescript @types/react --dev

# Install output target runtime dependency
yarn add @stencil/react-output-target
```

```bash
# Create a project
lerna create react-library # fill out the prompts accordingly
cd packages/react-library

# Install core dependencies
pnpm add react react-dom typescript @types/react --save-dev

# Install output target runtime dependency
pnpm add @stencil/react-output-target
```

--------------------------------

### Install browser testing providers

Source: https://stenciljs.com/docs/testing-vitest

Add a browser provider to enable integration and visual regression testing.

```bash
npm install --save-dev @vitest/browser-playwright
# or
npm install --save-dev @vitest/browser-webdriverio
```

```bash
yarn add --dev @vitest/browser-playwright
# or
yarn add --dev @vitest/browser-webdriverio
```

```bash
pnpm add --save-dev @vitest/browser-playwright
# or
pnpm add --save-dev @vitest/browser-webdriverio
```

--------------------------------

### Install rollup-plugin-node-polyfills

Source: https://stenciljs.com/docs/module-bundling

Commands to install the polyfill plugin as a development dependency using various package managers.

```bash
npm install rollup-plugin-node-polyfills --save-dev
```

```bash
yarn add rollup-plugin-node-polyfills --dev
```

```bash
pnpm add rollup-plugin-node-polyfills --save-dev
```

--------------------------------

### Generated Import Path Example

Source: https://stenciljs.com/docs/angular

The resulting import path structure based on the componentCorePackage configuration.

```typescript
import { MyComponent } from 'my-component-lib/components/my-component.js';
```

--------------------------------

### Define and Use Store

Source: https://stenciljs.com/docs/stencil-store

Example of creating a store and consuming it within a Stencil component.

```typescript
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;
```

```typescript
import { Component, h } from '@stencil/core';
import state from '../store';

@Component({
  tag: 'app-profile',
})
export class AppProfile {

  componentWillLoad() {
    setInterval(() => state.seconds++, 1000);
  }

  render() {
    return (
      <div>
        <p>
          <MyGlobalCounter />
          <p>
            Seconds: {state.seconds}
            <br />
            Squared Clicks: {state.squaredClicks}
          </p>
        </p>
      </div>
    );
  }
}

const MyGlobalCounter = () => {
  return (
    <button onClick={() => state.clicks++}>
      {state.clicks}
    </button>
  );
};
```

--------------------------------

### Export Helper Methods

Source: https://stenciljs.com/docs/publishing

Example of the default index.js file content exporting client helper methods.

```javascript
export { setAssetPath, setPlatformOptions } from '@stencil/core/internal/client';
```

--------------------------------

### Define component directory structure

Source: https://stenciljs.com/docs/component

Example directory layout for a component and its associated CSS files.

```text
src/
└── components/
    ├── todo-list-1.css
    ├── todo-list-2.css
    └── todo-list.tsx
```

--------------------------------

### Install React Output Target Dependency in Stencil Library

Source: https://stenciljs.com/docs/react

Install the package as a development dependency in your Stencil component library.

```bash
# Install dependency
npm install @stencil/react-output-target --save-dev
```

```bash
# Install dependency
yarn add @stencil/react-output-target --dev
```

```bash
# Install dependency
pnpm add @stencil/react-output-target --save-dev
```

--------------------------------

### Install Playwright browser binaries

Source: https://stenciljs.com/docs/testing/playwright/overview

Download the necessary browser binaries required for running Playwright tests.

```bash
npx playwright install
```

--------------------------------

### Importing build output in test setup

Source: https://stenciljs.com/docs/testing-vitest-migration

Verify that the import path correctly points to your project's generated ESM build output.

```javascript
// Check that the path matches your actual build output
await import('./dist/test-components/test-components.esm.js');
```

--------------------------------

### Host element rendering output

Source: https://stenciljs.com/docs/host-element

Example output for the Host component based on the open property state.

```html
<todo-list class="todo-list is-open" aria-hidden="false"></todo-list>
```

```html
<todo-list class="todo-list" aria-hidden="true"></todo-list>
```

--------------------------------

### Example Directory Structure for Assets

Source: https://stenciljs.com/docs/assets

A representation of a typical build directory structure where assets are located relative to the base path.

```text
www/
├── build/
│   ├── assets/
│   │   ├── logo.png
│   │   └── scenery/
│   │       ├── beach.png
│   │       └── sunset.png
│   └── other-assets/
│       └── font.tiff
└── ...
```

--------------------------------

### Install Legacy Ember CLI Stencil Addon

Source: https://stenciljs.com/docs/ember

Command to install the legacy addon for automatic Stencil component discovery.

```shell
ember install ember-cli-stencil
```

--------------------------------

### CSS Tag Transformation Examples

Source: https://stenciljs.com/docs/tag-transformation

Shows the transformation of CSS selectors for runtime usage.

```css
:host my-element {}

my-element::before {}

my-element.active:hover {}
```

```css
`:host ${transformTag('my-element')} {}

${transformTag('my-element')}::before {}

${transformTag('my-element')}.active:hover {}`
```

--------------------------------

### Component Directory Structure

Source: https://stenciljs.com/docs/style-guide

Example of a recommended directory structure for Stencil components, showing co-location of implementation files and platform-specific styles.

```text
├── 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
```

--------------------------------

### Install Playwright dependencies

Source: https://stenciljs.com/docs/testing/playwright/overview

Install the required Stencil Playwright adapter and Playwright test packages using your preferred package manager.

```bash
npm i @stencil/playwright @playwright/test --save-dev
```

```bash
yarn add @stencil/playwright @playwright/test --dev
```

```bash
pnpm add @stencil/playwright @playwright/test --save-dev
```

--------------------------------

### Test Project Configurations

Source: https://stenciljs.com/docs/testing-vitest-configuration

Examples for defining unit, spec, and browser test projects within the Vitest configuration.

```typescript
{
  test: {
    name: 'unit',
    include: ['src/**/*.unit.{ts,tsx}'],
    environment: 'node',
  },
}
```

```typescript
{
  test: {
    name: 'spec',
    include: ['src/**/*.spec.{ts,tsx}'],
    environment: 'stencil',
    setupFiles: ['./vitest-setup.ts'],
  },
}
```

```typescript
{
  test: {
    name: 'browser',
    include: ['src/**/*.test.{ts,tsx}'],
    setupFiles: ['./vitest-setup.ts'],
    browser: {
      enabled: true,
      provider: playwright(),
      headless: true,
      instances: [{ browser: 'chromium' }],
    },
  },
}
```

--------------------------------

### Use Component Wrappers

Source: https://stenciljs.com/docs/vue

Example of using a component wrapper within a Vue template.

```html
<template>
  <my-component first="Your" last="Name"></my-component>
</template>
```

--------------------------------

### Create Vue Library Package

Source: https://stenciljs.com/docs/vue

Commands to generate a Vue library package using Lerna and install Vue 3.

```bash
# From your top-most-directory/
lerna create vue-library
# Follow the prompts and confirm
cd packages/vue-library
# Install Vue dependency
npm install vue@3 --save-dev
```

```bash
# From your top-most-directory/
lerna create vue-library
# Follow the prompts and confirm
cd packages/vue-library
# Install Vue dependency
yarn add vue@3 --dev
```

```bash
# From your top-most-directory/
lerna create vue-library
# Follow the prompts and confirm
cd packages/vue-library
# Install Vue dependency
pnpm add vue@3 --save-dev
```

--------------------------------

### Import and use React wrapper components

Source: https://stenciljs.com/docs/react

Example of importing and using a component from the React library in a React application.

```typescript
import './App.css';
import { MyComponent } from 'react-library';

function App() {
  return (
    <div className="App">
      <MyComponent first="Your" last="Name" />
    </div>
  );
}

export default App;
```

--------------------------------

### Input Module with Aliased Imports

Source: https://stenciljs.com/docs/config

Example source file using an aliased import path.

```typescript
import { utilFunc, UtilInterface } from '@utils'

export function util(arg: UtilInterface) {
    utilFunc(arg)
}
```

--------------------------------

### Select a starter project

Source: https://stenciljs.com/docs/getting-started

The CLI provides a prompt to select a project type, such as a standalone component collection or an application.

```text
? Select a starter project.

Starters marked as [community] are developed by the Stencil
Community, 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
```

--------------------------------

### Use Component in Markup

Source: https://stenciljs.com/docs/component

Examples of consuming the defined custom element in HTML and TSX files.

```html
<!-- Here we use the component in an HTML file -->
<todo-list></todo-list>
```

```tsx
{/* Here we use the component in a TSX file */}
<todo-list></todo-list>
```

--------------------------------

### CLI initialization output

Source: https://stenciljs.com/docs/getting-started

The CLI confirms project creation and suggests the next steps for development.

```text
✔ 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! 🎈
```

--------------------------------

### Include Stencil Components via Script Tag

Source: https://stenciljs.com/docs/getting-started

Example of importing the ESM bundle and using a custom component in an HTML file.

```html
<!DOCTYPE html>
<html>
<head>
  <!-- Import your Stencil namespace -->
  <script type="module" src="path/to/dist/my-first-stencil-project/my-first-stencil-project.esm.js"></script>
</head>
<body>
  <!-- Now you can use your components -->
  <my-component first="Stencil" middle="'Don't call me a framework'" last="JS"></my-component>
</body>
</html>
```

--------------------------------

### Configure asset path in consumer application

Source: https://stenciljs.com/docs/assets

Example of importing and using setAssetPath within a consuming application.

```typescript
import { setAssetPath } from 'my-component-library';
setAssetPath(`${window.location.protocol}//assets.${window.location.host}/`);
```

--------------------------------

### initBuild(options)

Source: https://stenciljs.com/docs/screenshot-connector

Initializes the connector and prepares the environment for running tests, including setting up variables, filepaths, and folder structures.

```APIDOC
## initBuild(options)

### Description
This method is called to setup the connector and ready everything for running the tests. It is responsible for setting up the variables, filepaths and folder structures needed for running the screenshot tests.

### Parameters
- **options** (any) - Configuration options for the build initialization.
```

--------------------------------

### Component Class Structure Example

Source: https://stenciljs.com/docs/style-guide

Demonstrates the recommended order of class members in a Stencil component, including properties, decorators, lifecycle methods, and the render function.

```typescript
@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<boolean> {
    // ...
    return true;
  }

  @Method()
  async close(): Promise<void> {
    // ...
  }

  /**
   * 9. Local methods
   * Internal business logic. These methods cannot be
   * called from the host element.
   */
  prepareAnimation(): Promise<void> {
    // ...
  }

  updateState() {
    // ...
  }

  /**
   * 10. render() function
   * Always the last public method in the class.
   * If private methods present, they are below public methods.
   */
  render() {
    return (
      <Host
        attribute="navigation"
        side={this.isRightSide ? 'right' : 'left'}
        type={this.type}
        class={{
          'something-is-animating': this.isAnimating
        }}
      >
        <div class='menu-inner page-inner'>
          <slot></slot>
        </div>
      </Host>
    );
  }
}
```

--------------------------------

### Name the project

Source: https://stenciljs.com/docs/getting-started

After selecting a starter, provide a name for the new project directory.

```text
✔ Pick a starter › component
? Project name › my-first-stencil-project
```

--------------------------------

### Configure asset path via script tag

Source: https://stenciljs.com/docs/assets

Example of setting the asset path when importing components directly via a script tag.

```html
<html>
  <head>
    <script src="https://cdn.jsdelivr.net/npm/my-component-library/dist/my-component-library.js"></script>
    <script type="module">
      import { setAssetPath } from 'https://cdn.jsdelivr.net/npm/my-component-library/dist/my-component-library.js';
      setAssetPath(`${window.location.origin}/`);
    </script>
  </head>
  <body>
    <ion-toggle></ion-toggle>
  </body>
</html>
```

--------------------------------

### Transform aliased import paths

Source: https://stenciljs.com/docs/distribution

Example showing how path aliases in source code are transformed into relative paths in the generated output.

```javascript
// Source code
import * as utils from '@utils';

// Output code
import * as utils from '../path/to/utils';
```

--------------------------------

### Resolve asset paths with getAssetPath

Source: https://stenciljs.com/docs/assets

Examples showing how getAssetPath resolves various input strings relative to a configured base path of /build/.

```typescript
import { getAssetPath } from '@stencil/core';

// with an asset base path of "/build/":
// "/build/"
getAssetPath('');
// "/build/my-image.png"
getAssetPath('my-image.png');
// "/build/assets/my-image.png"
getAssetPath('assets/my-image.png');
// "/build/assets/my-image.png"
getAssetPath('./assets/my-image.png');
// "/assets/my-image.png"
getAssetPath('../assets/my-image.png');
// "/assets/my-image.png"
getAssetPath('/assets/my-image.png');
```

--------------------------------

### run(init: CliInitOptions): Promise<void>

Source: https://stenciljs.com/docs/cli-api

Executes the CLI with the provided initialization options.

```APIDOC
## run(init: CliInitOptions): Promise<void>

### Description
Runs the CLI with the given options. This is used by Stencil's default bin/stencil file, but can be used externally.

### Parameters
- **init** (CliInitOptions) - Required - The initialization options for the CLI.
```

--------------------------------

### Create a Stencil component story

Source: https://stenciljs.com/docs/storybook

Example configuration for a Storybook story using Meta and StoryObj types with Stencil components.

```typescript
import type { Meta, StoryObj } from '@stencil/storybook-plugin';
import { h } from '@stencil/core';
import { MyComponent } from './my-component';

const meta: Meta<MyComponent> = {
  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<MyComponent>;

export const Primary: Story = {
  args: {
    first: 'John',
    last: 'Doe',
    middle: 'Michael',
  },
  render: (props) => <my-component {...props} />,
};

/**
 * Storybook story without custom render function
 */
export const Secondary: Story = {
  args: {
    first: 'Jane',
    last: 'Smith',
    middle: 'Marie',
  },
};
```

--------------------------------

### Define component styles with imports

Source: https://stenciljs.com/docs/server-side-rendering

Example of a CSS file using multiple imports, which can lead to document bloat during SSR.

```css
/* button.css */
@import "../css/base.css";
@import "../css/tokens.css";
@import "../css/animations.css";
@import "../css/utilities.css";

/* component-specific styles */
button {
    ...
}
```

--------------------------------

### Run Stencil Build with Prerendering

Source: https://stenciljs.com/docs/static-site-generation-basics

Execute the build command with the --prerender flag to enable static site generation.

```bash
stencil build --prerender
```

--------------------------------

### Example stats JSON structure

Source: https://stenciljs.com/docs/stats

The generated stats file contains comprehensive metadata about the library's components, bundles, and build options.

```json
{
  "timestamp": "2021-09-22T17:31:14",
  "compiler": {
    "name": "node",
    "version": "16.9.1"
  },
  "app": {
    "namespace": "ExampleStencilLibrary",
    "fsNamespace": "example-stencil-library",
    "components": 1,
    "entries": 1,
    "bundles": 30,
    "outputs": [
      {
        "name": "dist-collection",
        "files": 3,
        "generatedFiles": [
          "./dist/collection/components/my-component/my-component.js",
           // etc...
        ]
      },
      {
        "name": "dist-lazy",
        "files": 26,
        "generatedFiles": [
          "./dist/cjs/example-stencil-library.cjs.js",
           // etc...
        ]
      },
      {
        "name": "dist-types",
        "files": 1,
        "generatedFiles": [
          "./dist/types/stencil-public-runtime.d.ts"
        ]
      }
    ]
  },
  "options": {
    "minifyJs": true,
    "minifyCss": true,
    "hashFileNames": true,
    "hashedFileNameLength": 8,
    "buildEs5": true
  },
  "formats": {
    "esmBrowser": [
      {
        "key": "my-component.entry",
        "components": [
          "my-component"
        ],
        "bundleId": "p-12cc1edd",
        "fileName": "p-12cc1edd.entry.js",
        "imports": [
          "p-24af5948.js"
        ],
        "originalByteSize": 562
      }
    ],
    "esm": [
      // exact same model as the esmBrowser, but for esm files
    ],
    "es5": [
      // exact same model as the esmBrowser, but for es5 files
    ],
    "system": [
      // exact same model as the esmBrowser, but for system files
    ],
    "commonjs": [
      // exact same model as the esmBrowser, but for cjs files
    ]
  },
  "components": [
    {
      "tag": "my-component",
      "path": "./src/components/my-component/my-component.js",
      "source": "./src/components/my-component/my-component.tsx",
      "elementRef": null,
      "componentClassName": "MyComponent",
      "assetsDirs": [],
      "dependencies": [],
      "dependents": [],
      "directDependencies": [],
      "directDependents": [],
      "docs": {
        "tags": [],
        "text": ""
      },
      "encapsulation": "shadow",
      "excludeFromCollection": false,
      "events": [],
      "internal": false,
      "legacyConnect": [],
      "legacyContext": [],
      "listeners": [],
      "methods": [],
      "potentialCmpRefs": [],
      "properties": [
        {
          "name": "first",
          "type": "string",
          "attribute": "first",
          "reflect": false,
          "mutable": false,
          "required": false,
          "optional": false,
          "complexType": {
            "original": "string",
            "resolved": "string",
            "references": {}
          },
          "docs": {
            "tags": [],
            "text": "The first name"
          },
          "internal": false
        },
      ],
    },
  ],
  "entries": [
    {
      "cmps": [
       // Expanded component details are produced here
      ],
      "entryKey": "my-component.entry"
    }
  ],
  "componentGraph": {
    "sc-my-component": [
      "p-24af5948.js"
    ]
  },
  "sourceGraph": {
    "./src/components/my-component/my-component.tsx": [
      "./src/utils/utils"
    ],
    "./src/index.ts": [],
    "./src/utils/utils.ts": []
  },
  "collections": []
}
```

--------------------------------

### Initialize a new Stencil project

Source: https://stenciljs.com/docs/getting-started

Use the create-stencil CLI to scaffold a new project. Choose between npm, yarn, or pnpm based on your package manager preference.

```bash
 npm init stencil
```

```bash
 yarn create stencil
```

```bash
 pnpm create stencil
```

--------------------------------

### Run CLI

Source: https://stenciljs.com/docs/cli-api

Executes the CLI with the provided initialization options.

```typescript
run(init: CliInitOptions): Promise<void>
```

--------------------------------

### Install Angular Output Target Dependency

Source: https://stenciljs.com/docs/angular

Install the required output target package using your preferred package manager.

```bash
# Install dependency
npm install @stencil/angular-output-target --save-dev
```

```bash
# Install dependency
yarn add @stencil/angular-output-target --dev
```

```bash
# Install dependency
pnpm add @stencil/angular-output-target --save-dev
```

--------------------------------

### Type Mismatch Error Example

Source: https://stenciljs.com/docs/properties

Example of a JSX usage that fails to compile due to a type mismatch between the provided number and the inferred string type.

```tsx
{/* This fails to compile with the error "Type 'number' is not assignable to type 'string'" for the label prop. */}
<todo-list-item completeMsg={"true"} label={42} thingToDo={"Learn about any-typed props"}></todo-list-item>
```

--------------------------------

### getAssetPath(path)

Source: https://stenciljs.com/docs/api

Gets the path to local assets.

```APIDOC
## getAssetPath(path)

### Description
Gets the path to local assets.

### Type
(path: string) => string

### Example
```typescript
import { Component, Prop, getAssetPath, h } from '@stencil/core'
@Component({
  tag: 'cmp-asset',
})
export class CmpAsset {
  @Prop() icon: string;

  render() {
    return (
      <img src={getAssetPath(`assets/icons/${this.icon}.png`)} />
    );
  }
}
```
```

--------------------------------

### Get Compiler Version

Source: https://stenciljs.com/docs/compiler-api

Retrieve the current version of the @stencil/core package.

```typescript
version: string
```

--------------------------------

### newE2EPage(options)

Source: https://stenciljs.com/docs/end-to-end-testing

Initializes a new E2E testing page with optional configuration settings.

```APIDOC
## newE2EPage(options)

### Description
Initializes a new browser page for end-to-end testing within the Stencil environment.

### Parameters
- **html** (string) - Optional - A HTML template to be rendered in the browser.
- **url** (string) - Optional - A URL to open. Ignored if html is set.
- **failOnConsoleError** (boolean) - Optional - If true, throws an error if a console error occurs. Default: false.
- **failOnNetworkError** (boolean) - Optional - If true, throws an error if a network request fails. Default: false.
- **logFailingNetworkRequests** (boolean) - Optional - If true, logs failing network requests. Default: false.
```

--------------------------------

### Initialize Stencil Component Library

Source: https://stenciljs.com/docs/angular

Commands to initialize a new Stencil component library project using different package managers.

```bash
npm init stencil component my-component-lib
```

```bash
yarn create stencil component my-component-lib
```

```bash
pnpm create stencil component my-component-lib
```

--------------------------------

### Configure package.json for distribution

Source: https://stenciljs.com/docs/publishing

Define entry points in package.json to ensure the correct files are loaded by consumers.

```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",
}
```

--------------------------------

### Generate a Vue Application

Source: https://stenciljs.com/docs/vue

Commands to initialize a new Vue 3 project using different package managers.

```bash
npm init vue@3 my-app
```

```bash
yarn create vue@3 my-app
```

```bash
pnpm create vue@3 my-app
```

--------------------------------

### Initialize Git repository manually

Source: https://stenciljs.com/docs/getting-started

If using an older version of the CLI or if the repository was not automatically initialized, use these commands to set up version control.

```bash
$ git init
$ git add -A
$ git commit -m "initialize project using stencil cli" 
```

--------------------------------

### Link Stencil package from source directory

Source: https://stenciljs.com/docs/angular

Run this command in the Stencil project directory to prepare the package for linking.

```shell
# Link the working directory
npm link
```

```shell
# Link the working directory
yarn link
```

```shell
# Link the working directory
pnpm link
```

--------------------------------

### Build Stencil Library

Source: https://stenciljs.com/docs/angular

Generate the component wrappers by building the Stencil library.

```bash
# Build the library and wrappers
npm run build
```

```bash
# Build the library and wrappers
yarn build
```

```bash
# Build the library and wrappers
pnpm run build
```

--------------------------------

### Install TypeScript v5

Source: https://stenciljs.com/docs/react

Ensure the React library uses TypeScript version 5.0 or later.

```bash
# Install dependency
npm install typescript@5 --save-dev
```

```bash
# Install dependency
yarn add typescript@5 --dev
```

```bash
# Install dependency
pnpm add typescript@5 --save-dev
```

--------------------------------

### Define a component usage demo

Source: https://stenciljs.com/docs/docs-custom-elements-manifest

Create a markdown file in the component's usage/ directory to document component usage.

```markdown
# 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
<my-button>My Button!</my-button>
```
```

--------------------------------

### Create Compiler Instance

Source: https://stenciljs.com/docs/compiler-api

Initialize a compiler instance using a validated Stencil configuration.

```typescript
createCompiler(config: Config): Promise<Compiler>
```

--------------------------------

### Define component properties

Source: https://stenciljs.com/docs/properties

Example of a component with multiple properties, showing default attribute mapping behavior.

```typescript
import { Component, Prop, h } from '@stencil/core';
// `MyHttpService` is an `Object` in this example
import { MyHttpService } from '../some/local/directory/MyHttpService';

@Component({
   tag: 'todo-list-item',
})
export class ToDoListItem {
   @Prop() isComplete: boolean;
   @Prop() thingToDo: string;
   @Prop() httpService: MyHttpService;
}
```

--------------------------------

### Invoke hydrateComponents in a Koa server

Source: https://stenciljs.com/docs/hydrate-app

Example of calling the hydration function within a Koa middleware context.

```typescript
import Koa from 'koa';

const app = new Koa();
app.use(async (ctx) => {
  const res = await hydrateComponents(`<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Document</title>
    <link rel="preconnect" href="https://some-url.com" />
    <style>
      // custom styles here
    </style>
  </head>
  <body>
    <app-root></app-root>
  </body>
</html>`)
  ctx.body = res
})
```

--------------------------------

### Expose Server Entry Point in package.json

Source: https://stenciljs.com/docs/server-side-rendering

Define custom export paths in the React wrapper package to allow Next.js to resolve the server-optimized components.

```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"
    }
  }
}
```

--------------------------------

### createNodeSystem(process: any): CompilerSystem

Source: https://stenciljs.com/docs/cli-api

Creates a system based on Node.js APIs for file system operations and hashing.

```APIDOC
## createNodeSystem(process: any): CompilerSystem

### Description
Creates the "system", based off of NodeJS APIs, used by the compiler. This includes any and all file system reads and writes using NodeJS and crypto hashing.

### Parameters
- **process** (any) - Required - The NodeJS "process" object.
```

--------------------------------

### Synchronous property updates in Stencil

Source: https://stenciljs.com/docs/component-lifecycle

Example showing how multiple synchronous property mutations trigger componentShouldUpdate.

```typescript
component.somePropA = 42;
component.somePropB = 88;
```

--------------------------------

### JavaScript Tag Transformation Examples

Source: https://stenciljs.com/docs/tag-transformation

Demonstrates how static tag names in DOM methods are automatically wrapped with transformTag().

```javascript
document.createElement('my-element');
// becomes
document.createElement(transformTag('my-element'));

document.querySelectorAll('my-element');
// becomes
document.querySelectorAll(transformTag('my-element'));

document.createElement('my-element');
// becomes
document.createElement(transformTag('my-element'));
```

--------------------------------

### loadConfig(init?: LoadConfigInit)

Source: https://stenciljs.com/docs/compiler-api

Transforms raw configuration information into a usable config object.

```APIDOC
## loadConfig(init?: LoadConfigInit)

### Description
Processes raw configuration data into a format suitable for the compiler and dev-server.

### Parameters
- **init** (LoadConfigInit) - Optional - Initialization object containing system and logger instances.

### Returns
- **Promise<LoadConfigResults>** - A promise that resolves to the usable configuration results.
```

--------------------------------

### Node Polyfill Error Message

Source: https://stenciljs.com/docs/module-bundling

Example of the build-time error message indicating missing Node built-in modules.

```text
[ 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.
```

--------------------------------

### Use Stencil Components in Templates

Source: https://stenciljs.com/docs/ember

Example of using a Stencil-based web component inside an Ember GJS template.

```handlebars
<template>
  <ion-toggle></ion-toggle>
</template>
```

--------------------------------

### Build the React component library

Source: https://stenciljs.com/docs/react

Build the React component library before consuming the wrappers.

```bash
npm run build
```

```bash
yarn build
```

```bash
pnpm run build
```

--------------------------------

### Generate documentation via CLI

Source: https://stenciljs.com/docs/docs-readme

Commands to trigger documentation generation during build or as a standalone task.

```bash
npx stencil build
```

```bash
npm stencil build --watch
```

```bash
npx stencil build --docs
```

```bash
npx stencil docs
```

--------------------------------

### store.use(...subscriptions)

Source: https://stenciljs.com/docs/stencil-store

Applies external subscriptions to the store, which can define custom get, set, or reset logic.

```APIDOC
## store.use(...subscriptions)

### Description
Use the given subscriptions in the store. A subscription is an object that defines one or more of the properties `get`, `set` or `reset`.

### Parameters
- **subscriptions** (Object[]) - Required - One or more subscription objects.
```

--------------------------------

### Get current style mode

Source: https://stenciljs.com/docs/api

Retrieves the current style mode of the application. Requires importing getMode from @stencil/core.

```typescript
import { getMode } from '@stencil/core'

getMode(this);
```

--------------------------------

### Generate a new component

Source: https://stenciljs.com/docs/cli

Use this command to scaffold a new component in the src/components directory.

```bash
stencil generate my-new-component
```

```bash
stencil generate pages/page-home
```

--------------------------------

### Generate JSON documentation via CLI

Source: https://stenciljs.com/docs/docs-json

Use the --docs-json flag to generate documentation during a build process.

```bash
stencil build --docs-json path/to/docs.json
```

--------------------------------

### Configure Angular Postinstall Script

Source: https://stenciljs.com/docs/tag-transformation

Expose the patch-transform-selectors script in the Angular wrapper package.json.

```json
"bin": {
    "patch-transform-selectors": "./scripts/patch-transform-selectors.mjs"
  },
```

--------------------------------

### Example CEM JSON output

Source: https://stenciljs.com/docs/docs-custom-elements-manifest

The resulting JSON structure for documented CSS properties within the Custom Elements Manifest.

```json
[
  {
    "cssProperties": [
      {
        "name": "background",
        "description": "Background of the button"
      },
      {
        "name": "background-activated",
        "description": "Background of the button when activated"
      },
      {
        "name": "background-focused",
        "description": "Background of the button when focused"
      }
    ]
  }
]
```

--------------------------------

### Build Stencil Project

Source: https://stenciljs.com/docs/getting-started

Commands to compile the Stencil project into a distribution folder.

```bash
# First, build your Stencil project
cd my-first-stencil-project
npm run build
```

--------------------------------

### Import and Register Standalone Components

Source: https://stenciljs.com/docs/publishing

Demonstrates importing component classes and registration functions, or extending them for custom definitions.

```javascript
import { MyComponent, defineCustomElementMyComponent } from 'my-design-system'

// register to CustomElementRegistry
defineCustomElementMyComponent()

// or extend custom element via
class MyCustomComponent extends MyComponent {
  // ...
}
define('my-custom-component', MyCustomComponent)
```

--------------------------------

### Install Ionic Framework Dependencies

Source: https://stenciljs.com/docs/ember

Commands to add the Ionic core library to an Ember project using various package managers.

```shell
npm install @ionic/core
```

```shell
yarn add @ionic/core
```

```shell
pnpm add @ionic/core
```

--------------------------------

### Configure Package Exports

Source: https://stenciljs.com/docs/publishing

Defines entry points in package.json to map import paths to specific component files.

```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",
}
```

--------------------------------

### Create Node System

Source: https://stenciljs.com/docs/cli-api

Initializes a compiler system interface using NodeJS APIs for file system operations.

```typescript
createNodeSystem(process: any): CompilerSystem
```
Tokens:
Raw