Getting Started with Stencil.js

Before diving into the code, ensure you have Node.js installed on your machine. You can download it from Node.js official website. Once you have Node.js set up, you can create a new Stencil project using the following commands:

npm init stencil

You will be prompted to choose a project type. For this guide, select "component." This will set up a new Stencil project with the necessary configurations.

Project Structure

After creating your project, your directory structure will look similar to this:

my-component-library/
├── src/
│   ├── components/
│   ├── global/
│   ├── index.ts
│   └── ...
├── package.json
├── stencil.config.ts
└── ...
  • src/components/: This is where you will define your components.
  • src/global/: This folder is for global styles and utilities.

Creating Your First Component

Let’s create a simple button component. Navigate to the src/components/ directory and create a new folder called my-button. Inside this folder, create a file named my-button.tsx.

import { Component, Prop, h } from '@stencil/core';

@Component({
  tag: 'my-button',
  styleUrl: 'my-button.css',
  shadow: true,
})
export class MyButton {
  @Prop() label: string;

  render() {
    return (
      <button>
        {this.label}
      </button>
    );
  }
}

Adding Styles

Next, let's add some styles to our button. Create a file named my-button.css in the same directory:

button {
  background-color: #4CAF50; /* Green */
  border: none;
  color: white;
  padding: 15px 32px;
  text-align: center;
  text-decoration: none;
  display: inline-block;
  font-size: 16px;
  margin: 4px 2px;
  cursor: pointer;
  border-radius: 4px;
}

button:hover {
  background-color: #45a049;
}

Building and Testing Your Component

To build your component, run the following command in your project directory:

npm run build

To test your component, you can serve the project using:

npm start

This will open a local development server where you can see your button component in action.

Using Your Component in an Application

To use your newly created component in an application, you need to include it in the HTML file. Here’s an example of how to do that:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>My Component Library</title>
    <script type="module" src="/build/my-component-library.js"></script>
</head>
<body>
    <my-button label="Click Me!"></my-button>
</body>
</html>

Best Practices for Building Component Libraries

  1. Use Shadow DOM: By enabling shadow DOM in your components, you encapsulate styles and prevent them from leaking out. This is crucial for maintaining style integrity across different applications.
  1. Prop Validation: Always validate your props using TypeScript. This ensures that your components are used correctly and reduces runtime errors.
  1. Documentation: Document your components thoroughly. Consider using tools like Storybook to create a living style guide for your component library.
  1. Testing: Write unit tests for your components. Stencil supports Jest for testing, which makes it easy to ensure your components behave as expected.
  1. Versioning: Use semantic versioning (SemVer) for your component library. This helps consumers of your library understand the impact of changes.

Conclusion

Stencil.js provides a robust framework for building reusable web components that can be easily integrated into any project. By following the best practices outlined in this guide, you can create a component library that is not only functional but also maintainable and scalable.

Learn more with useful resources