Build a Stencil and Storybook Environment

Goes together like peanut butter and jelly.

I have been using Stencil.js and Storybook to build components for design systems and I have really been enjoying the workflow, one might even say they go together like peanut butter and jelly.

The tooling I have been using at work uses these two technologies with all the bells and whistles needed for interacting with various other tools. I’m pretty obsessed with it at the moment and decided that I wanted to build a stripped down version of this system to learn and teach these amazing technologies in isolation. I also wanted to share this process as a way to better understand it myself and to teach anyone who is curious how they can do it too.

If you want to just see or use the starter file, you can find it on my Github.

Getting Started

Create your Stencil.js application in your working directory:

We will be picking component as a starter:

Enter your project name and confirm:

Now lets change directories to our newly created Stencil app and install the dependencies:

Let’s go ahead and fire up Stencil and make sure that we got everything running fine so far:

If all goes well you should be directed to localhost:3333 in your browser and you should see the following demo web component:

Great, looking good so far! Let’s go ahead and terminate that process using ctrl + C .


Let’s add Storybook to our project. We will initialize storybook and configure it as an HTML project.

(Note: There is a method to setup the project explicitly for web components, but as of writing this, the add-on is in beta and requires additional setup. If you are interested in trying to set it up in this way, the web component add-on can be found here)

In the root directory run:

We’ll need to open up .storybook/preview.js and add the following to let Storybook know to load our web components:

Let’s do a little refactoring to the file structure. This step is not necessary, it is just how I like to organize my stories.

First we move the src/stories folder to the .storybook folder, this is where we will store our general stories, like introduction.stories.mdx and also to keep the example stories for reference.

Be sure you are still in the root directory of the project and run:

Now we need to open .storybook/main.js and add the following lines to module.exports so Storybook knows where to find these stories that we just moved:

We will keep stories for web components we build in the component directories themselves.

Let’s add a story file to the my-component component that Stencil built for us.

(This file will be blank initially and therefore we will not see it in storybook yet. Adding this here to suppress an error and we will build out the story later)

In the root directory of the project, run:

Now lets fire up Storybook and make sure that it is setup and running:

With everything going as planned, you will be taken to localhost: 6006 and should see the following page:

(Note that we have our introduction and sample stories in the sidebar)

Now that we know that is setup, let’s terminate that process using ctrl + C.

Flip the Script

Next we need to add a “” script to our package.json so that we can run a watcher for Stencil to detect any changes we make in our component:

We’ll need to add concurrently as a dev dependency, this will allow us to setup a script that can run multiple scripts in parallel:

Next we will add another script to package.json that will run both the “” and “storybook” scripts in parallel.

Insert the new “dev” script:

Now run:

You should see the same Storybook content as before at localhost: 6006. The difference is now we have Stencil also watching for changes to the component to trigger hot reloading of the component in Storybook.

Story Time

Okay, now we’ve got the environment up and running, let’s go ahead and build a story for my-component to test everything out.

Without getting too deep into how to build stories, what we are doing here is:

  • defining where we want our story displayed in the sidebar in title
  • defining which component we are pointing to in component
  • defining which argument types we want to pass in with argTypes along with control type and defaultValue
  • creating the arrow function MyComponent where we destructure our arguments and render the component in the return using a template literal.
  • passing in our arguments as props to my-component

Now we should see Example > Demo > My Component in the sidebar of our Storybook:

(If Storybook didn’t detect our new story, try to refresh your browser. If that doesn’t work then terminate the process and run npm run dev again)

All done!

So there we go, now you have your very own starter to build web components using Stencil and you can view and test those components live using Storybook.

I’ll be using this starter to put together tutorials for Stencil and Storybook and I’ll be experimenting with different tools and sharing my processes.

In the meantime if you want to jump in and learn more yourself go checkout the respective docs here and here to get started. See you next time!

A frontend developer with a passion for web components and design systems

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store