Component Libraries with Stencil.js - Getting Started
Tags: stencil, webcomponents, typescript
Published: 2018-09-16 18:20:22

---
title: Component Libraries with Stencil.js - Getting Started
published: true
description: The second in a series of posts about creating a component library using Stencil.js
series: Component Libraries with Stencil.js
tags: ["stencil", "webcomponents", "typescript"]
cover_image: https://thepracticaldev.s3.amazonaws.com/i/r3si3x5havh6dpkfvchk.jpg
canonical_url: https://johnbwoodruff.com/posts/stencil-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](https://dev.to/johnwoodruff91/component-libraries-with-stenciljs---about-stencil-10b7)*

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:

```shell
$ npm init stencil
```

You should get a prompt similar to the following:

```shell
? 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:

```html
<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](https://stenciljs.com/docs/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):

```shell
$ 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:

```typescript
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](https://dev.to/johnwoodruff91/component-libraries-with-stenciljs---your-first-component-3b7p) 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](https://github.com/johnbwoodruff/mountain-ui)*