> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.knapsack.cloud/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.knapsack.cloud/_mcp/server.

# Web Components

Knapsack for Web Components works by scanning your specified Web Components code locations and automatically discovering reusable components, making them instantly available in your design system.

**Why This Approach:**

* ⚡ **Zero Manual Work** - Knapsack finds and configures your components automatically
* 🔄 **Always Current** - Your documentation stays in sync with code changes
* 🎯 **Intelligent** - Understands different export patterns and component structures
* 🚀 **Scale Effortlessly** - Handle hundreds of components without individual setup

## Requirements

* **Custom Elements** - Components must use the Web Components API
* **Asset Sets** - Required for loading web components in Knapsack
* **Custom Element Manifest** - Optional, but enables automatic spec inference (props, slots, events)

**The Web Components renderer supports components created using Custom Elements and the Web Components API. You must install the underlying Web Components packages separately.**

***

## Install

```bash
npm install @knapsack/renderer-web-components
```

## Configure

**Minimal Setup**

The simplest configuration requires specifying where your web components are located:

```js
// knapsack.config.js
const { KnapsackWebComponentRenderer } = require('@knapsack/renderer-web-components');

module.exports = configureKnapsack({
  templateRenderers: [
    new KnapsackWebComponentRenderer({
      codeSrcs: [{ path: './src/components/**/*.js' }],
    }),
  ],
});
```

**Full Configuration Example**

Here's a comprehensive example showing all available options:

```js
const { KnapsackWebComponentRenderer } = require('@knapsack/renderer-web-components');

module.exports = configureKnapsack({
  templateRenderers: [
    new KnapsackWebComponentRenderer({
      // Code discovery paths
      codeSrcs: [
        { path: './src/components/**/*.js' },
        { path: '@my-design-system/web-components' },
      ],

      // Custom element manifest for enhanced spec inference
      customElementManifestSchemaPath: './dist/custom-elements.json',
    }),
  ],
});
```

To enable spec inference for web components, you must first generate a custom element manifest for your web components and then add the path to the `KnapsackWebComponentRenderer` config. This can be a package reference or a file path relative to the config file.

```js
// knapsack.config.js
const { KnapsackWebComponentRenderer } = require('@knapsack/renderer-web-components');

module.exports = configureKnapsack({
  templateRenderers: [
    new KnapsackWebComponentRenderer({
      customElementManifestSchemaPath: './path/to/your/custom-elements.json',
    }),
  ],
};
```

### Code Sources

The `codeSrcs` array tells Knapsack where to find your web components. The renderer will scan these paths and make them available in the Knapsack UI for documentation and demos.

##### Local Components

```js
codeSrcs: [
  // Specific directory
  { path: './src/components/**/*.js' },

  // Multiple file extensions
  { path: './src/ui/**/*.{js,ts}' },

  // Specific component types
  { path: './src/components/atoms/*.js' },
  { path: './src/components/molecules/*.js' },
];
```

##### External Libraries

```js
codeSrcs: [
  // Entire package
  { path: '@my-org/design-system' },

  // Package sub-paths
  { path: '@my-org/design-system/components/*' },
];
```

***

### Custom Element Manifest

To enable enhanced spec inference for web components, you can provide a custom element manifest. This is optional but provides better prop and slot information.

##### Generating the Manifest

Knapsack uses [@custom-elements-manifest/analyzer](https://www.npmjs.com/package/@custom-elements-manifest/analyzer) to generate custom element manifests. See the [@custom-elements-manifest/analyzer](https://custom-elements-manifest.open-wc.org/) documentation for installation and usage instructions.

```bash
# Generate the manifest
npx custom-elements-manifest analyze --globs './src/**/*.ts' --outdir ./dist/
```

You can also add this to your `package.json` scripts for automated builds:

```json
{
  "scripts": {
    "build:manifest": "custom-elements-manifest analyze --globs './src/**/*.ts' --outdir ./dist/"
  }
}
```

The custom element manifest file generation can be set up as part of your build process so that it runs automatically when you build your components or manually after adding or removing new props, slots, or other component features.

Learn more about [custom element manifests](https://github.com/webcomponents/custom-elements-manifest).

***

### Asset Sets

**Web components require asset sets to work properly in Knapsack**. Asset sets tell Knapsack how to load and render your web components.

##### Configure Asset Sets

Update the asset set configuration in `knapsack/data/knapsack.asset-sets.json` to include your custom elements:

```json
// knapsack.asset-sets.json
{
  "src": "./path/to/your/web-components.js",
  "includedRenderers": ["web-components"],
  "attributes": {
    "type": "module"
  }
}
```

##### Rebuild

After configuring your renderer and asset sets, rebuild your Knapsack configuration to ensure the web components are properly rendered.