@aibots-public/web-components

Web Component Library

This repository contains a collection of framework-agnostic web components designed for reuse across multiple projects. This guide outlines the process for developing and adding new components to the library.

Getting Started

Before you begin, please ensure you have the following installed on your system:

• Node.js (v18 or later recommended)
• pnpm (or your preferred Node.js package manager like npm or yarn)

To install the project dependencies, run the following command from the root directory:

pnpm install

Project Structure

• /src: Contains the source code for each component (e.g., TypeScript/TSX, CSS files). Each component should reside in its own dedicated folder.
• /wcs: Contains manifest files (.wc) that define and register each web component. This is how our build system discovers and configures them.

Developing a New Web Component

Follow these steps to create a new, production-ready web component.

Step 1: Create the Component Source Files

First, create a new directory inside /src for your component. It's best practice to name the folder after the component itself.

For example, to create a new my-button component:

1. Create a new folder: src/my-button
2. Add your source files inside it, for example: src/my-button/my-button.tsx and src/my-button/my-button/module.css.

Step 2: Define the Component Manifest

Next, you need to create a manifest file in the /wcs directory to register your component with our build system.

1. Create a new file in the /wcs folder. The filename must follow the convention component-name.wc.

   • Example: wcs/my-button.wc

2. Add the following JSON content to the file, customizing it for your component:

{
  "tag": "my-button",
  "component": "src/my-button/my-button.tsx",
  "attrs": ["label", "variant", "disabled"]
}

Manifest Fields Explained:

• "tag": The custom HTML tag name for your component. By web component standards, this must contain a hyphen.
• "component": The path from the project root to your main component source file.
• "attrs": An array of attribute names that your component will observe. When these attributes change on the HTML tag, your component will be notified.

Step 3: Expose the Component in package.json

To make your component available for development tools like Storybook and for proper module resolution, you must add an entry to the exports field in the root package.json file.

1. Open package.json.

2. Add a new key-value pair to the exports object.

   ```json
   // package.json
   {
     // ... other package.json content
     "exports": {
       // ... other existing exports
       "./my-button": "./src/my-button/my-button.tsx"
     }
   }
   ```
   

   This creates a clean, predictable import path for your component's source code.

Step 4: View Your Component in Storybook

Storybook is integrated into this project to allow for isolated development and testing of components.

1. (Optional but Recommended) Create a story for your component. Add a new file in the <root>/apps/stories directory, such as stories/my-button.stories.ts.

Of course. Here is a rewritten version of that section, designed to be more informative, clear, and provide step-by-step guidance for any developer.

---

Publishing a New Version to NPM

This guide outlines the process for publishing a new version of the @aibots-public/web-components package to the public NPM registry.

Prerequisites

Before you can publish a new version, please ensure you have the following:

1. An NPM Account: You must have an active account on npmjs.com.
2. Required Permissions: Your NPM account must have write access to the @aibots-public organization.
3. NPM Authentication: You need to be logged into your NPM account on your local machine. If you are not logged in, run this command and follow the prompts:

   npm login

Step 1: Prepare the Release

This step kicks off an interactive command-line process that helps you select which component(s) to include in the release, choose the new version number (following SemVer conventions), and generate changelogs.

1. From the root folder of the project, run the prepare script:

   pnpm publish:prepare

2. Follow the on-screen prompts. You will be asked to select the specific web component(s) you intend to release and choose whether this is a patch, minor, or major version update.

This command will update the package.json version and stage the necessary files for the next step.

Step 2: Build and Publish

After the preparation step is complete, run the following command. This script will handle the final build process for the selected components and upload the new package version to the NPM registry.

pnpm publish:run

Wait for the script to complete. You should see a success message indicating that the package has been published.

Step 3: Verify the Release

Once the publish script finishes, it's important to verify that the new version is publicly available.

1. Check the NPM Registry: Visit the package's official page on NPM and confirm that the new version number is listed.

   • https://www.npmjs.com/settings/aibots-public/packages

2. Check the unpkg CDN: You can also verify that the distributable files are accessible via the unpkg CDN. Replace <version> with the version you just published (e.g., 3.1.0).

   https://unpkg.com/@aibots-public/web-components@<version>/dist/live-chat.widget.global.js
   

   For example, for version 3.1.0, the link would be:

   • https://unpkg.com/@aibots-public/web-components@3.1.0/dist/live-chat.widget.global.js

   If you can access this URL, your package has been successfully published and is available on the CDN.

Test your built web components

1. Modify the public/index.html file to include your latest web component
2. Run

pnpm start:test:server