Component Libraries with Stencil.js - Getting Started

This is the second in a series of posts about creating a web component library using Stencil.js - Check out the first post

Now that we've talked about the reasoning for choosing Stencil to build our web component library, let's jump right in. First things first, we need to get our base project structure set up. Thankfully, the Ionic team has handled this completely for us. Make sure you're running npm at version 6 or later, and run the following command:

$ npm init stencil

You should get a prompt similar to the following:

? Pick a starter › - Use arrow-keys. Return to submit.

   ionic-pwa     Everything you need to build fast, production ready PWAs
   app           Minimal starter for building a Stencil app or website
❯  component     Collection of web components that can be used anywhere

The Ionic team has provided a few starters for us. We're not interested in building an entire app or PWA using Stencil (although you definitely can!) so we're going to choose the component option. This will structure it so we can build a reusable component library for distribution.

You'll be asked to name your collection, so go ahead and name that however you'd like. The component library I'll be building is one I'm calling mountain-ui, because I live in Utah among the beautiful Wasatch mountain range.

Once the starter is created, you can cd into your newly created directory and run npm start. That'll open the project in your browser with a basic web component they put there as a start. We'll jump into writing a component in a minute, but let's first go over the project structure and figure out where things go.

Project Structure

You'll notice a few directories. The main one you'll want to concern yourself with is src. Other important directories to note are www, which is where your compiled components go when you're developing, and dist, which is where your actual distribution is after running a production build.

There are a few other important files to look at before we get to the components. If you've written TypeScript before you'll recognize the tsconfig.json which defines our TypeScript compiler options. The other important file is stencil.config.ts. This file defines your Stencil build and its various options. We'll change a couple of things there later on in this post. Finally there's src/components.d.ts which is a file you won't ever modify yourself. It's a file generated by stencil at build time that keeps all your library's TypeScript definitions up to date.

Components

The src/components directory is where you'll be spending most of your time. We're going to be keeping each component in its own separate folder. You'll notice a my-component directory in there by default, with three files inside. The main file is my-component.tsx. This is the TSX file that keeps the component class, its render method, and other methods and props associated with your component. There is also a corresponding my-component.spec.ts file that is used for testing your component. Finally there is my-component.css, which is where your styles live. By default you have CSS files, but you can use CSS preprocessors such as SASS.

Configuring our Library

There are a few things we'll want to do right at the beginning before moving on to building components. Let's start in the stencil.config.ts file. The first thing we'll change is the namespace value. By default it is set to mycomponent, but we're going to change this to the name of our library. In my case, I'll be changing the value to mountain-ui. Because we changed the namespace, let's also make sure that name is reflected correctly in the src/index.html file. Make sure you have the following script tags at the top of your file:

<script type="module" src="/build/mountain-ui.esm.js"></script>
<script nomodule src="/build/mountain-ui.js"></script>

The next thing to do is set up a CSS preprocessor. This is not required, many people will prefer to use plain CSS and that's great. The available plugins for Stencil are listed on the Plugins page. Personally I love using SASS, so I'm going to be setting that up for my project.

First we'll need to install the appropriate plugin. In my case I'll be running the following command (note that I'm using yarn, but you're welcome to use whatever you prefer):

$ yarn add --dev @stencil/sass

Once the plugin is installed, I'll be importing it in the config file, and passing it in to the plugins array in the config object. See the full file below:

import { Config } from '@stencil/core';
import { sass } from '@stencil/sass';

export const config: Config = {
  namespace: 'mountain-ui',
  outputTargets: [
    {
      type: 'dist',
      esmLoaderPath: '../loader'
    },
    {
      type: 'docs-readme'
    },
    {
      type: 'www',
      serviceWorker: null // disable service workers
    }
  ],
  plugins: [
    sass()
  ]
};

That's all you need to do to get your project set up for SASS. If you want to use one of the other preprocessors, simply install the appropriate plugin and follow the same steps above. The last thing I need to do is change my-component.css to my-component.scss, I'll change the styleUrl in my-component.tsx, and any new components I create from now on will have an scss file instead of a css file.

Next Steps

Now that we've fully configured our project, we're free to build our components without worrying about configuration or build. In the next post we'll start to go into a detailed build of our first component!

Simply want to see the end result repo? Check it out here