WEB COMPONENTS GENERATOR WITH TYPESCRIPT

Project to create stand-alone web components with typescript.

Uses:

Getting started

Download this project for local development of web components:

Click the "Clone this template" button on the github page and then clone your new repo it in your local machine.

Use degit or any similar tool.

npm install -g degit #In case you don't have it installed
degit tx2z/wc-base-typescript

Once the project is on your computer, enter the folder and install all npm dependencies:

npm i

The components are stored in "src/components". Create a folder with the name you want to give to your component.

For a quick start, you can copy the content of the example components in the folder:

base-component create a web component with no dependencies or libraries.
lithtml-component create a web component using lit-html as template library.
noshadow-component create a custom element (not sure if it can be called a web component) without using the shadow DOM & with no dependencies or libraries.

Include your defined custom element in "public/index.html" so you can test it while developing.

To run a server in development mode run:

npm start

Your components will be compiled every time you save a file.

Tests

Karma & jasmine are used as testing environment and framework.

Inside the example components, there is a file ending with "spec.ts" where you can write your tests with typescript.

Launchers for chrome and firefox are already installed and configured but you can install and use any other karma-launcher.

To run your test use:

npm test

Using Storybook

You can optionally use storybook to develop, document and create a gallery for your web components. You can learn more about storybook in their documentation site.

Storybook for HTML is used and tuned so no further configuration is needed to use it for your components. The following storybook addons are included:

Knobs: Allows edit web components' props dynamically using the Storybook UI.
Viewport: Allows web components to be displayed in different sizes and layouts in Storybook. This helps build responsive web components inside of Storybook.
A11y: Helps to make your web components more accessible.
Docs: Allows to write notes or documentation for your web components.

This is a standard storybook installation. You can add other addons or configurations that suit your needs.

Create stories

There are two files inside the example components that are used by storybook.

@component.stories.ts: Is the file to create a story for your component. You can check storybook documentation about how to create stories starting here
README.md: It's used to add documentation for your component using the Docs storybook add-on.

Storybook will use these two files to generate the stories and the documentation. Once these two files are present run storybook with:

npm run storybook

To build a static storybook app ready to be deployed run:

npm run storybook-build

You can find your storybook builds in the "dist-storybook" folder.

Storybook is optional. If you're not using it you can remove (or not create) the @component.stories.ts file. Even you can remove all the storybook and webpack references in the package.json to completely remove storybook from your project.

Build the components

npm run build

You can find your builds in the "dist" folder.

Your components will be compiled in a js file (as ES module), to use them as modules in your application, and in a dist.js (as iife), to use them directly in browsers, with the same name you give to the folder in "src/components".

All modules include their respective Typescript declaration files.

The webcomponents polyfills are included as well in the "dist" folder, you can use them or load directly the code from a CDN such as unpkg: https://unpkg.com/@webcomponents/webcomponentsjs@^2/

Publish component to NPM

A README.md and a "package.json" are created as well in every component folder, so you can upload them separately to the NPM registry. You can change the content in the "package.json" file inside the example components.