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)

Install

$
npm install @knapsack/renderer-web-components

Configure

Minimal Setup

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

1
// knapsack.config.js
2
const { KnapsackWebComponentRenderer } = require('@knapsack/renderer-web-components');
3
4
module.exports = configureKnapsack({
5
  templateRenderers: [
6
    new KnapsackWebComponentRenderer({
7
      codeSrcs: [{ path: './src/components/**/*.js' }],
8
    }),
9
  ],
10
});

Full Configuration Example

Here’s a comprehensive example showing all available options:

1
const { KnapsackWebComponentRenderer } = require('@knapsack/renderer-web-components');
2
3
module.exports = configureKnapsack({
4
  templateRenderers: [
5
    new KnapsackWebComponentRenderer({
6
      // Code discovery paths
7
      codeSrcs: [
8
        { path: './src/components/**/*.js' },
9
        { path: '@my-design-system/web-components' },
10
      ],
11
12
      // Custom element manifest for enhanced spec inference
13
      customElementManifestSchemaPath: './dist/custom-elements.json',
14
    }),
15
  ],
16
});

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.

1
// knapsack.config.js
2
const { KnapsackWebComponentRenderer } = require('@knapsack/renderer-web-components');
3
4
module.exports = configureKnapsack({
5
  templateRenderers: [
6
    new KnapsackWebComponentRenderer({
7
      customElementManifestSchemaPath: './path/to/your/custom-elements.json',
8
    }),
9
  ],
10
};

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

1
codeSrcs: [
2
  // Specific directory
3
  { path: './src/components/**/*.js' },
4
5
  // Multiple file extensions
6
  { path: './src/ui/**/*.{js,ts}' },
7
8
  // Specific component types
9
  { path: './src/components/atoms/*.js' },
10
  { path: './src/components/molecules/*.js' },
11
];

External Libraries

1
codeSrcs: [
2
  // Entire package
3
  { path: '@my-org/design-system' },
4
5
  // Package sub-paths
6
  { path: '@my-org/design-system/components/*' },
7
];

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 to generate custom element manifests. See the @custom-elements-manifest/analyzer documentation for installation and usage instructions.

$
# 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:

1
{
2
  "scripts": {
3
    "build:manifest": "custom-elements-manifest analyze --globs './src/**/*.ts' --outdir ./dist/"
4
  }
5
}

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.

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:

1
// knapsack.asset-sets.json
2
{
3
  "src": "./path/to/your/web-components.js",
4
  "includedRenderers": ["web-components"],
5
  "attributes": {
6
    "type": "module"
7
  }
8
}

Rebuild

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