Core Components
Package Management
This repo leverages Lerna, a tool for managing multiple packages within the same repo.
Lerna takes the place of typical npm
and yarn
commands. For a full breakdown of lerna
commands, see the lerna readme
Generating React components
The stencil config (stencil.config.js
) automatically generates React code for the components-react
package whenever stencil builds.
From root
:
# This will run the `build` script in any package that has it defined in its package.json
lerna run build
If you make changes to these web components be sure to build stencil and commit any changes to packages/components-react/src/generated
.
Publishing to NPM
Lerna provides a simple CLI interface for publishing to NPM. See the root readme for more info.
Getting Started
To start developing your Stencil project, run:
From root
:
lerna run start
To start developing your Stencil project in Storybook, run:
From root
:
lerna run storybook
Component Structure
Stencil components are plain ES6/TypeScript classes with some decorator metadata.
Create new components by creating files with a .tsx
extension, such as core-component.tsx
, and place them in src/components
.
import { Component, Prop, h } from "@stencil/core";
@Component({
tag: "core-component",
styleUrl: "core-component.css",
})
export class Component {
@Prop() first: string;
@Prop() last: string;
render() {
return (
<div>
Hello, my name is {this.first} {this.last}
</div>
);
}
}
To use this component, just use it like any other HTML element:
<core-component first="Stencil" last="JS"></core-component>
Naming Components
When creating new component tags, use the core-
prefix and kebab-case.
For example: core-button
, core-icon
, etc. Custom Elements must contain a dashed name so they do not collide with existing html element names.
API
The API for Stencil closely mirrors the API for Custom Elements v1.
Components
Decorator | Description |
---|---|
@Component() |
Indicate a class is a Stencil component. |
@Prop() |
Creates a property that will exist on the element and be data-bound to this component. |
@State() |
Creates a local state variable that will not be placed on the element. |
@Method() |
Expose specific methods to be publicly accessible. |
High Level Component Example
View high level component example here
Browser Support
Web Components, specifically Custom Elements, are natively supported in Chrome and Safari and are coming to both Edge and Firefox. A dynamic polyfill loader is already included in order to only load the polyfills for the browsers that are missing specific features.
- Chrome (and all Chromium based browsers)
- Safari
- Edge
- Firefox
- IE 11
Polyfills
Stencil includes a subset of the core-js
polyfills for old browsers like IE11, fetch
and conditionally downloads the Custom Elements v1 only when it's needed for modern browsers (EDGE and old versions of Firefox.)
Internet Explorer 11
View IE11 polyfill details here
In addition, the following set of polyfills are also included:
- Promise
- fetch()
- CSS variables: We implemented our own CSS variables polyfill that integrates into the Stencil runtime.
All browsers
Some modern browsers like Edge do not include native support for Web Components. In that case, we conditionally load the Custom Elements v1 polyfill.