Handlebars | Knapsack Documentation

Knapsack for Handlebars works by scanning your specified Handlebars 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

Handlebars templates - Templates must be in .hbs or .handlebars format
JavaScript/TypeScript exports - For template data and helpers

Install

$ npm install @knapsack/renderer-hbs

Configure

Minimal Setup The simplest configuration requires just specifying where your Handlebars components are located:

1 // knapsack.config.js
2 const { KnapsackHbsRenderer } = require('@knapsack/renderer-hbs');
3 
4 module.exports = configureKnapsack({
5   templateRenderers: [
6     new KnapsackHbsRenderer({
7       codeSrcs: [
8         { path: '@my-design-system/handlebars/*' },
9       ],
10     }),
11   ],
12 };

Full Configuration Example Here’s a comprehensive example showing all available options:

1 // knapsack.config.js
2 const path = require('path');
3 const fs = require('fs');
4 const { KnapsackHbsRenderer } = require('@knapsack/renderer-handlebars');
5 
6 module.exports = configureKnapsack({
7   templateRenderers: [
8     new KnapsackHbsRenderer({
9       // Discover your Handlebars templates/partials
10       codeSrcs: [
11         // Local templates
12         { path: './src/templates/**/*.hbs' },
13         { path: './src/partials/**/*.hbs' },
14 
15         // Example: pull templates from a package
16         { path: '@my-design-system/handlebars/*' },
17       ],
18 
19       // Add custom helpers/partials programmatically
20       alterHandlebars(handlebars) {
21         // Helpers
22         handlebars.registerHelper('uppercase', (str) =>
23           String(str ?? '').toUpperCase(),
24         );
25         handlebars.registerHelper('eq', (a, b) => a === b);
26 
27         // Partials (inline or from files)
28         handlebars.registerPartial('badge', '<span class="badge">{{text}}</span>');
29 
30         const buttonPartialPath = path.resolve(
31           __dirname,
32           'src/partials/button.hbs',
33         );
34         if (fs.existsSync(buttonPartialPath)) {
35           handlebars.registerPartial(
36             'button',
37             fs.readFileSync(buttonPartialPath, 'utf8'),
38           );
39         }
40       },
41     }),
42   ],
43 });

Code Sources

The codeSrcs array tells Knapsack where to find your Handlebars components and how to process them. The renderer will scan these paths, find Handlebars component exports, and make them available in the Knapsack UI for documentation and demos.

Local Components

Paths are relative to knapsack.config.js

1 codeSrcs: [
2   // Specific directory
3   { path: './src/components/**/*.hbs' },
4 
5   // Multiple file extensions (Handlebars + helpers/partials in JS/TS)
6   { path: './src/ui/**/*.{hbs,js,ts}' },
7 
8   // Specific component types
9   { path: './src/components/atoms/*.hbs' },
10   { path: './src/components/molecules/*.hbs' },
11 ];

External Libraries

Ensure that any external library is included in your package dependencies

1 codeSrcs: [
2   // Entire package (Handlebars templates)
3   { path: '@my-org/handlebars-design-system' },
4   { path: '@my-org/hbs-theme' },
5 
6   // Package sub-paths
7   { path: '@my-org/handlebars-design-system/components/*' },
8   { path: '@my-org/design-system/templates/*' },
9 ];

Smart Filtering

Use filters to control exactly which components are discovered:

1 codeSrcs: [
2   {
3     path: './src/**/*.hbs',
4     filter: (filePath) => {
5       // Only include template components, exclude utilities and tests
6       return (
7         filePath.includes('/components/') &&
8         !filePath.includes('.test.') &&
9         !filePath.includes('.stories.')
10       );
11     },
12   },
13   {
14     path: '@my-org/handlebars-library/*',
15     filter: (filePath) => {
16       // Exclude non-template or internal files from the package
17       const excludedPaths = [
18         '@my-org/handlebars-library/index',
19         '@my-org/handlebars-library/internal',
20         '@my-org/handlebars-library/utils',
21       ];
22       return !excludedPaths.some((excluded) => filePath.includes(excluded));
23     },
24   },
25 ];

Alter Handlebars

This enables you to register custom partials, helpers, and other modifications to the Handlebars environment, enhancing the flexibility and power of your templates. In addition to registering partials, you can use the alterHandleBars function to register helpers, set custom delimiters, or perform other runtime customizations. Refer to the Handlebars Runtime API documentation for more details on the available methods and their usage.

By leveraging these customization capabilities, you can tailor the Handlebars runtime to meet the specific needs of your project, ensuring a powerful and flexible templating environment within Knapsack.

Example Configuration

The following example demonstrates how to configure Knapsack with a custom Handlebars renderer and register a partial named foo. In this example, the alterHandleBars function registers a partial named badge with the template <span class="badge">{{text}}</span>. This partial can then be used in other Handlebars templates within your Knapsack project.

1 module.exports = configureKnapsack({
2   templateRenderers: [
3     new KnapsackHbsRenderer({
4       alterHandleBars: (handlebars) => {
5         handlebars.registerPartial('badge', '<span class="badge">{{text}}</span>');
6       }
7     })
8   ]
9 })

Using Registered Partials

Once a partial is registered, you can use it in your templates by referencing its name with the partial syntax {{> partialName}}. For example, to use the badge partial:

1 {{> badge text="Hello, world!" }}