@adhocteam/component-library

Stencil Component Starter

Usage no npm install needed!

<script type="module">
  import adhocteamComponentLibrary from 'https://cdn.skypack.dev/@adhocteam/component-library';
</script>

README

Built With Stencil

Ad Hoc Component Library

This is a Web Component library with Storybook integration based on https://github.com/DesignByOnyx/stencil-storybook-starter.git

Features

  • automatic generation of stories for all components
  • automatic knobs generation for all @Props on your components
    • ability to customize which knobs are used for each prop (though the code does a good job of guessing for strings, numbers, booleans, objects, dates, and colors).
  • ability to define multiple states which are rendered on a single page, each with a title, description, and props to use for rendering. A copyable code snippet is also generated for each state (kind of a lightweight chapters implementation)
  • ability to define notes for each component (usually you want the generated readme)
  • live rebuild/reload of stencil components (it's still a little wonky - sometimes you have to refresh the browser)
  • also comes with the viewport add-on

Setup

To get this repo running locally so you can modify existing components or create new ones, install the dependencies:

npm install

To see your component in Stencil's local dev server, put it in src/index.html and start the server:

npm run start

To start storybook locally and browse through the stories:

npm run storybook

Stencil

Stencil is a compiler for building fast web apps using Web Components.

Stencil combines the best concepts of the most popular frontend frameworks into a compile-time rather than run-time tool. Stencil takes TypeScript, JSX, a tiny virtual DOM layer, efficient one-way data binding, an asynchronous rendering pipeline (similar to React Fiber), and lazy-loading out of the box, and generates 100% standards-based Web Components that run in any browser supporting the Custom Elements v1 spec.

Stencil components are just Web Components, so they work in any major framework or with no framework at all.

Creating/Modifying a Component

Components live in the src/components directory, and each component directory might have 6 files in it:

  • The component definition
  • The component CSS
  • The Story for the component
  • A generated readme
  • End-to-End tests (testing the component from a consumer perspective)
  • Unit tests (testing things within the component)

Stencil requires components to be written in TypeScript, so the definition file must end in .tsx.

It's a good idea to have some basic tests for your new component/feature.

You can also check out the Stencil docs on creating a component here.

Naming Components

When creating new component tags, we recommend not using stencil in the component name (ex: <stencil-datepicker>). This is because the generated component has little to nothing to do with Stencil; it's just a web component!

Instead, use a prefix that fits your company or any name for a group of related components. For example, all of the Ionic generated web components use the prefix ion.

Using a Component elsewhere

Publishing

This component library is meant to be able to be used on other sites. To do so, any changes to the components must be published:

npm run build
npm publish --public

Installing & Importing

First, the library must be installed:

npm install @adhocteam/component-library --save

Next, put the following code into your app's index.js file or equivalent:

import {defineCustomElements} from '@adhocteam/component-library/loader';

defineCustomelements(window);

Alternatively, you can add a <script> tag to your HTML:

<script src="https://unpkg.com/@adhocteam/component-library/dist/component-library.js"></script>

Using a component

If the library has been installed and imported correctly, you should be able to use one of the defined components anywhere in your HTML or JSX.