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
Top comments (0)