Storybook and Stencil Starter Kit

This is a starter kit for using storybook to build web and html component using stencil.

Setp & Installation

Using locally

Requirements

• Make sure you are using at least node v12 ( lts is recommanded )
• Make sure to use yarn

Install

• run yarn install
• run yarn start

Using with lando

Requirements

• Make sure to use the latest version of lando. Older version of lando do not support node 12.
• Make sure docker is working and using a version compatible with lando

Install

• run lando start
• run lando yarn start

How does it works?

Storybook

Website: https://storybook.js.org/ Docs: https://storybook.js.org/docs/react/get-started/introduction

Storybook is a tool for UI development. It makes development faster and easier by isolating components. This allows you to work on one component at a time. You can develop entire UIs without needing to start up a complex dev stack, force certain data into your database, or navigate around your application.

Storybook helps you document components for reuse and automatically visually test your components to prevent bugs.

On start, Storybook scans the src folder for file ending in stories.mdx. When found, these are included and visible on the storybook instance.

Storybook supports live reload, so modifying your code inside a story will update the page.

Addons

The Storybook ecosystem has a lot of addons to chose from to helps us develop and test components. Make sure to familiarize yourself with them and understand how to works.

We are using the following addons:

• Docs
• Controls
• A11y
• Action
• Background
• Viewport
• Toolbars
• Jest

StencilJS

Website: https://stenciljs.com/ Docs: https://stenciljs.com/docs/getting-started

Stencil is a toolchain for building reusable, scalable Design Systems.

Stencil is a compiler that generates Web Components (more specifically, Custom Elements) and builds high performance web apps. Stencil combines the best concepts of the most popular frameworks into a simple build-time tool.

Since Stencil generates standards-compliant web components, they can work with many popular frameworks right out of the box, and can be used without a framework because they are just web components.

Typescript

TypeScript extends JavaScript by adding types.

By understanding JavaScript, TypeScript saves you time catching errors and providing fixes before you run code.

Check the handbook at TypesScript

Web Components

Docs: https://developer.mozilla.org/en-US/docs/Web/Web_Components

Web Components is a suite of different technologies allowing you to create reusable custom elements — with their functionality encapsulated away from the rest of your code — and utilize them in your web apps.

To understand how web component works, you check this tutorial on mdn https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements

TailwindCSS

Website: https://tailwindcss.com/ Docs: https://tailwindcss.com/docs/utility-first

Tailwind CSS is a highly customizable, low-level CSS framework that gives you all of the building blocks you need to build bespoke designs without any annoying opinionated styles you have to fight to override.

Workflow

Before building a component, it must be documented and approved for development. For internal OKAM components, this can be found on Notion Component Library page.

Creating a component

Stencil Component

You must first start by creating your components with stencil. You can use this command to speed up the process:

npx stencil generate

This will create the folder and starter file for the components

Story

After creating the base of the components, you can create a story In the component folder, create a file with component name followed by .stories.mdx

Look in ./src/components/examples/my-component for an example on how to create a stories. (Don't forget the update relative import path!)

After creating your story, you can go on the Storybook book instance to look at it.

Git Commit Guidelines

We have very precise rules over how our git commit messages can be formatted. This leads to more readable messages that are easy to follow when looking through the project history. But also, we use the git commit messages to generate the change log.

Commit Format

<type>(<scope>): <subject>

Revert

If the commit reverts a previous commit, it should begin with revert: , followed by the header of the reverted commit. In the body it should say: This reverts commit ., where the hash is the SHA of the commit being reverted.

Type

Must be one of the following:

• feat: A new feature
• fix: A bug fix
• docs: Documentation only changes
• style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
• refactor: A code change that neither fixes a bug nor adds a feature
• perf: A code change that improves performance
• test: Adding missing or correcting existing tests
• chore: Changes to the build process or auxiliary tools and libraries such as documentation generation

Scope

The scope could be anything specifying place of the commit change. For example $location, $browser, $compile, $rootScope, ngHref, ngClick, ngView, etc...

You can use * when the change affects more than a single scope.

Subject

The subject contains succinct description of the change:

use the imperative, present tense: "change" not "changed" nor "changes" don't capitalize first letter no dot (.) at the end

Deploy Storybook to Netlify

This project is already configured to allow deploy to netlify with .gitlab-ci.yml

To activate it, you must:

Step 1: Generate a Netlify Personal Access Token

• Go to https://app.netlify.com/user/applications/personal
• Gives your token a good name, e.g.: My Project Storybook
• Save the token in bitwarden. If you lose the token, you'll have to recreate a new one.

Step 2: Netlify Site API ID

• Create a netlify project and get the API ID from the Netlify Dashboard in /settings/general

Step 3: Add variables to the Gitlab CI/CD Settings

• In your gitlab repo, go to Setting => CI/CD => Expand Variables
• Add variable NETLIFY_AUTH_TOKEN with the token from step 1 as the value.
• Add NETLIFY_SITE_ID with the API ID from step 2 as the value.
• Add NETLIFY_SITE_URL which is the url of your Netlify Project.

Step 4: Publish!

When a new commit is added to master, a deploy will be automatically triggered.

Recommended tools

VS Code Plugins

• MDX Language Support
• Tailwind CSS IntelliSense
• ESLint
• GitLens