handoff-app 1.1.1 → 1.1.2

package/Changelog.md

@@ -6,6 +6,53 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## \[1.1.2] - 2026-03-26
+
+This release improves integration with downstream platforms (for example HubSpot) by letting
+projects register their own Handlebars helpers during preview generation, instead of relying
+only on Handoff’s built-in `field` and `eq` helpers.
+
+### Feature
+
+**`hooks.registerHandlebarsHelpers`** — New optional hook in `handoff.config.js`. After Handoff
+registers its default preview helpers, your callback runs with the Handlebars runtime, the
+current `componentId`, the component `properties` (slot metadata), and a flag for inspect-mode
+renders (`injectFieldWrappers`). Use `handlebars.registerHelper` (and block helpers as needed)
+to add helpers that are only available while building component preview HTML—so templates can
+stay platform-specific without forking Handoff.
+
+Typical uses: block helpers that wrap regions meant for a host page’s header or footer, or a
+helper that serializes a value as JSON for inline scripts. Those behaviors are **not** shipped
+as core helpers; you define them in config so each project controls naming and semantics.
+
+See `docs/api.md` (Hooks → `registerHandlebarsHelpers`) for the full signature and README
+“Configuration hooks” for a quick pointer.
+
+### Example: JSON in templates
+
+If you register a `json` helper in `hooks.registerHandlebarsHelpers`, like this
+
+```
+  hooks: {
+    registerHandlebarsHelpers: ({ handlebars, componentId }) => {
+      // Register 'json' as a simple (non-block) helper
+      handlebars.registerHelper('json', (value, data) => {
+        return new handlebars.SafeString(JSON.stringify(value, null, 2));
+      });
+    }
+  }
+```
+
+Then your templates can do:
+
+```
+<script type="text/javascript">
+  window.barChartData = {{{json properties.data}}};
+</script>
+```
+
+with output shaped by your helper implementation (for example serialized JSON for chart data).
+
 ## \[1.1.1] - 2026-03-12
 
 This patch release focuses on Windows stabilization and consistency across environments.
@@ -1830,3 +1877,6 @@ package version was set to ^0.1.0 rather than ^0.2.0. This release fixes that.
 
 ```
 ```
+
+```
+```

package/README.md

@@ -16,6 +16,7 @@ transform tokens into dev ready artifacts.
 * [How does it work](#how-does-it-work)
   * [Handoff is in Beta!](#handoff-is-in-beta)
 * [Requirements](#requirements)
+* [Configuration hooks](#configuration-hooks)
 * [Get Started](#get-started)
   * [Figma](#figma)
   * [Create a project](#create-a-project)
@@ -168,6 +169,12 @@ handoff-app start
 
 Once that runs, your browser should update with the new colors.
 
+## Configuration hooks
+
+Pipeline customization is done in `handoff.config.js` under `hooks` (camelCase names: `validateComponent`, `jsBuildConfig`, `registerHandlebarsHelpers`, etc.). For example, `registerHandlebarsHelpers` runs after Handoff registers the built-in `field` and `eq` helpers so you can call `handlebars.registerHelper` for your `.hbs` preview templates.
+
+See [docs/api.md](docs/api.md#hooks) for hook arguments and examples.
+
 ## Further Reading
 
 * [Configure your project](https://www.handoff.com/docs/customization)

package/dist/cli.js

@@ -19,7 +19,7 @@ class HandoffCliError extends Error {
  * Show the help message
  */
 const showVersion = () => {
-    return 'Handoff App - 1.1.1';
+    return 'Handoff App - 1.1.2';
 };
 /**
  * Define a CLI error

package/dist/index.d.ts

@@ -95,6 +95,6 @@ declare class Handoff {
     private readJsonFile;
 }
 export type { ComponentObject as Component } from './transformers/preview/types';
-export type { Config } from './types/config';
+export type { Config, RegisterHandlebarsHelpersContext } from './types/config';
 export { Transformers as CoreTransformers, TransformerUtils as CoreTransformerUtils, Types as CoreTypes } from 'handoff-core';
 export default Handoff;

package/dist/transformers/plugins/handlebars-previews.js

@@ -61,10 +61,11 @@ function processComponentInstances(componentData, documentationComponents) {
  * @param injectFieldWrappers - Whether to inject field wrappers for inspection
  * @returns Rendered HTML string
  */
-function renderHandlebarsTemplate(template, componentData, previewData, injectFieldWrappers) {
+function renderHandlebarsTemplate(template, componentData, previewData, injectFieldWrappers, handoff) {
     return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b;
         // Register Handlebars helpers with current injection state
-        (0, handlebars_2.registerHandlebarsHelpers)({ id: componentData.id, properties: componentData.properties || {} }, injectFieldWrappers);
+        (0, handlebars_2.registerHandlebarsHelpers)({ id: componentData.id, properties: componentData.properties || {} }, injectFieldWrappers, (_b = (_a = handoff.config) === null || _a === void 0 ? void 0 : _a.hooks) === null || _b === void 0 ? void 0 : _b.registerHandlebarsHelpers);
         const context = (0, handlebars_2.createHandlebarsContext)({
             id: componentData.id,
             properties: componentData.properties || {},
@@ -147,8 +148,8 @@ function handlebarsPreviewsPlugin(componentData, documentationComponents, handof
                     try {
                         const previewData = componentData.previews[previewKey];
                         // Render both normal and inspect modes
-                        const normalModeHtml = yield renderHandlebarsTemplate(templateContent, componentData, previewData, false);
-                        const inspectModeHtml = yield renderHandlebarsTemplate(templateContent, componentData, previewData, true);
+                        const normalModeHtml = yield renderHandlebarsTemplate(templateContent, componentData, previewData, false, handoff);
+                        const inspectModeHtml = yield renderHandlebarsTemplate(templateContent, componentData, previewData, true, handoff);
                         // Emit preview files
                         emitPreviewFiles(componentId, previewKey, normalModeHtml, inspectModeHtml, (file) => this.emitFile(file));
                         generatedPreviews[previewKey] = normalModeHtml;

package/dist/transformers/utils/handlebars.d.ts

@@ -1,16 +1,18 @@
+import { RegisterHandlebarsHelpersContext } from '../../types/config';
 import { SlotMetadata } from '../preview/component';
 import { HandlebarsContext } from '../types';
 /**
- * Registers common Handlebars helpers
+ * Registers common Handlebars helpers, then runs optional `hooks.registerHandlebarsHelpers`.
  * @param data - Component data containing properties
  * @param injectFieldWrappers - Whether to inject field wrappers for inspection
+ * @param extend - Optional callback from config to register additional helpers
  */
 export declare const registerHandlebarsHelpers: (data: {
     properties: {
         [key: string]: SlotMetadata;
     };
     id: string;
-}, injectFieldWrappers: boolean) => void;
+}, injectFieldWrappers: boolean, extend?: (context: RegisterHandlebarsHelpersContext) => void) => void;
 /**
  * Creates Handlebars template context
  * @param data - Component data

package/dist/transformers/utils/handlebars.js

@@ -7,16 +7,17 @@ exports.createHandlebarsContext = exports.registerHandlebarsHelpers = void 0;
 const handlebars_1 = __importDefault(require("handlebars"));
 const logger_1 = require("../../utils/logger");
 /**
- * Registers common Handlebars helpers
+ * Registers common Handlebars helpers, then runs optional `hooks.registerHandlebarsHelpers`.
  * @param data - Component data containing properties
  * @param injectFieldWrappers - Whether to inject field wrappers for inspection
+ * @param extend - Optional callback from config to register additional helpers
  */
-const registerHandlebarsHelpers = (data, injectFieldWrappers) => {
+const registerHandlebarsHelpers = (data, injectFieldWrappers, extend) => {
     // Field helper for property binding
     handlebars_1.default.registerHelper('field', function (field, options) {
         if (injectFieldWrappers) {
             if (!field) {
-                // This deebuging isn't helpful in the context of the component library
+                // This debugging isn't helpful in the context of the component library
                 // Logger.error(`Missing field declaration for ${data.id}`);
                 return options.fn(this);
             }
@@ -43,6 +44,19 @@ const registerHandlebarsHelpers = (data, injectFieldWrappers) => {
     handlebars_1.default.registerHelper('eq', function (a, b) {
         return a === b;
     });
+    if (extend) {
+        try {
+            extend({
+                handlebars: handlebars_1.default,
+                componentId: data.id,
+                properties: data.properties,
+                injectFieldWrappers,
+            });
+        }
+        catch (err) {
+            logger_1.Logger.error(`registerHandlebarsHelpers hook failed for ${data.id}`, err);
+        }
+    }
 };
 exports.registerHandlebarsHelpers = registerHandlebarsHelpers;
 /**
@@ -54,9 +68,7 @@ exports.registerHandlebarsHelpers = registerHandlebarsHelpers;
 const createHandlebarsContext = (data, previewData, options) => {
     var _a;
     const basePath = (_a = process.env.HANDOFF_APP_BASE_PATH) !== null && _a !== void 0 ? _a : '';
-    const sharedStylesLink = (options === null || options === void 0 ? void 0 : options.includeSharedStyles)
-        ? `<link rel="stylesheet" href="${basePath}/api/component/shared.css">`
-        : '';
+    const sharedStylesLink = (options === null || options === void 0 ? void 0 : options.includeSharedStyles) ? `<link rel="stylesheet" href="${basePath}/api/component/shared.css">` : '';
     return {
         style: `${sharedStylesLink}<link rel="stylesheet" href="${basePath}/api/component/main.css">` +
             `<link rel="stylesheet" href="${basePath}/api/component/${data.id}.css">\n` +

package/dist/types/config.d.ts

@@ -1,4 +1,5 @@
 import { BuildOptions } from 'esbuild';
+import type Handlebars from 'handlebars';
 import { Types as HandoffTypes } from 'handoff-core';
 import { InlineConfig } from 'vite';
 import { SlotMetadata } from '../transformers/preview/component';
@@ -51,6 +52,15 @@ export interface Breakpoints {
         name: string;
     };
 }
+/** Context passed to the `registerHandlebarsHelpers` config hook after built-in helpers (`field`, `eq`) are registered for a preview render. */
+export type RegisterHandlebarsHelpersContext = {
+    handlebars: typeof Handlebars;
+    componentId: string;
+    properties: {
+        [key: string]: SlotMetadata;
+    };
+    injectFieldWrappers: boolean;
+};
 export interface NextAppConfig {
     theme?: string;
     title: string;
@@ -238,6 +248,21 @@ export interface Config {
          * ```
          */
         htmlBuildConfig?: (config: InlineConfig) => InlineConfig;
+        /**
+         * Optional hook invoked after Handoff registers built-in Handlebars helpers for
+         * component preview HTML. Use `context.handlebars.registerHelper` to add or
+         * replace helpers. Called once per preview render (per variation and inspect mode).
+         *
+         * @param context - Handlebars runtime, component id/properties, and whether
+         *   inspect field wrappers are enabled for this render.
+         * @example
+         * ```typescript
+         * registerHandlebarsHelpers: ({ handlebars, componentId }) => {
+         *   handlebars.registerHelper('upperId', () => componentId.toUpperCase());
+         * }
+         * ```
+         */
+        registerHandlebarsHelpers?: (context: RegisterHandlebarsHelpersContext) => void;
     };
 }
 export type ClientConfig = Pick<Config, 'app' | 'exportsOutputDirectory' | 'sitesOutputDirectory' | 'assets_zip_links' | 'useVariables'>;

package/docs/api.md

@@ -78,70 +78,65 @@ to generate only the integration code.
 
 ## Hooks
 
-Hooks allow a typescript or javascript app to interact with the pipeline.
-This is especially useful for modifying or extending the output of the pipeline.
-To use a hook in your project, once you've instantiated the handoff object, you
-can call one of the hook methods and pass a function to the method. The hook
-function will be called at the appropriate point in the pipeline.
-
-For example if you want to alter the integration output, you can do this -
+Hooks let you extend the build and preview pipeline. Configure them in
+`handoff.config.js` (or `.cjs`) under the top-level `hooks` object. Hook names
+use camelCase (for example `validateComponent`, `jsBuildConfig`,
+`registerHandlebarsHelpers`). The Handoff CLI and Node API load this config when
+the `Handoff` instance is created.
 
 ```js
-import Handoff from 'handoff-app';
+// handoff.config.js
+module.exports = {
+  // …
+  hooks: {
+    registerHandlebarsHelpers: ({ handlebars, componentId }) => {
+      handlebars.registerHelper('upperId', () => componentId.toUpperCase());
+    },
+  },
+};
+```
 
-const handoff = new Handoff({
-  // You can customize the configuration here
-});
+### registerHandlebarsHelpers
 
-handoff.postIntegration((documentationObject: DocumentationObject, data: HookReturn[]) => {
-  const colors = documentationObject.design.color.map((color) => {
-    return {
-      name: color.name,
-      value: color.value,
-    };
-  });
-  data.push({
-    filename: 'colors.json',
-    data: JSON.stringify(colors, null, 2),
-  });
-  return data;
-});
+Called immediately after Handoff registers built-in Handlebars helpers (`field`
+and `eq`) while rendering **Handlebars** component previews (static HTML per
+variation). Use it to call `handlebars.registerHelper` for custom helpers used
+in your `.hbs` templates.
 
-handoff.fetch();
-```
+**Arguments (single context object)**
 
-### postIntegration
+* `handlebars` — The Handlebars runtime (same as importing `handlebars`); use
+  `registerHelper`, `SafeString`, etc.
+* `componentId` — The current component’s id string.
+* `properties` — The component’s slot metadata map from the schema (same shape
+  as used by the `field` helper).
+* `injectFieldWrappers` — `true` when generating inspect-mode previews (field
+  inspection markup), `false` for normal previews.
 
-The Post integration hook will allow you to add a function that will be executed
-after the integration build is complete. The function accepts two arguments -
+**Return**
 
-**arguments**
+* `void` — register helpers on `handlebars` directly.
 
-- `tokens: DocumentationObject` This is an instance of the exported
-  DocumentationObject containing all of the tokens.
-- `data: HookReturn[]` This an array of HookReturns, consisting of `filename`
-  and `data`. Each object in this array will be written out to
-  `exported/{integration}-tokens`
+**Notes**
 
-**return**
-The hook must return an array of `HookReturn` objects, or an empty array
+* This hook runs once per preview render (each variation × normal vs inspect).
+* Registering the same helper name again replaces any previous registration for
+  subsequent renders in the same process.
 
-#### Example
+**Example**
 
 ```js
-handoff.postIntegration((documentationObject: DocumentationObject, data: HookReturn[]) => {
-  const colors = documentationObject.design.color.map((color) => {
-    return {
-      name: color.name,
-      value: color.value,
-    };
-  });
-  data.push({
-    filename: 'colors.json',
-    data: JSON.stringify(colors, null, 2),
-  });
-  return data;
-});
+// handoff.config.js
+module.exports = {
+  hooks: {
+    registerHandlebarsHelpers: ({ handlebars, componentId, injectFieldWrappers }) => {
+      handlebars.registerHelper('debugPreview', function () {
+        return injectFieldWrappers ? '[inspect]' : '[preview]';
+      });
+      handlebars.registerHelper('componentLabel', () => componentId);
+    },
+  },
+};
 ```
 
 ### postBuild
@@ -150,7 +145,7 @@ This function is called after the app build is complete.
 
 **arguments**
 
-- `tokens: DocumentationObject` This is an instance of the exported
+* `tokens: DocumentationObject` This is an instance of the exported
   DocumentationObject containing all of the tokens.
 
 **returns**
@@ -163,14 +158,14 @@ application to alter the css generation in transit
 
 **arguments**
 
-- `tokens: DocumentationObject` This is an instance of the exported
+* `tokens: DocumentationObject` This is an instance of the exported
   DocumentationObject containing all of the tokens.
-- `css: CssTransformerOutput` This is an object containing all of the
+* `css: CssTransformerOutput` This is an object containing all of the
   tokens for components and foundations, formatted as CSS variables
 
 **returns**
 
-- `css: CssTransformerOutput` This is an object containing all of the
+* `css: CssTransformerOutput` This is an object containing all of the
   tokens for components and foundations, formatted as CSS variables.
   Any changes you return here will be written to the css files
 
@@ -182,14 +177,14 @@ the transformed output prior to being written to disk.
 
 **arguments**
 
-- `tokens: DocumentationObject` This is an instance of the exported
+* `tokens: DocumentationObject` This is an instance of the exported
   DocumentationObject containing all of the tokens.
-- `css: CssTransformerOutput` This is an object containing all of the
+* `css: CssTransformerOutput` This is an object containing all of the
   tokens for components and foundations, formatted as CSS variables
 
 **returns**
 
-- `css: CssTransformerOutput` This is an object containing all of the
+* `css: CssTransformerOutput` This is an object containing all of the
   tokens for components and foundations, formatted as CSS variables.
   Any changes you return here will be written to the css files.
 
@@ -201,14 +196,14 @@ the transformed output prior to being written to disk.
 
 **arguments**
 
-- `tokens: DocumentationObject` This is an instance of the exported
+* `tokens: DocumentationObject` This is an instance of the exported
   DocumentationObject containing all of the tokens.
-- `scss: CssTransformerOutput` This is an object containing all of the
+* `scss: CssTransformerOutput` This is an object containing all of the
   tokens for components and foundations, formatted as SCSS variables
 
 **returns**
 
-- `css: CssTransformerOutput` This is an object containing all of the
+* `css: CssTransformerOutput` This is an object containing all of the
   tokens for components and foundations, formatted as SCSS variables.
   Any changes you return here will be written to the scss files.
 
@@ -224,14 +219,14 @@ the transformed output prior to being written to disk.
 
 **arguments**
 
-- `tokens: DocumentationObject` This is an instance of the exported
+* `tokens: DocumentationObject` This is an instance of the exported
   DocumentationObject containing all of the tokens.
-- `scss: CssTransformerOutput` This is an object containing all of the
+* `scss: CssTransformerOutput` This is an object containing all of the
   type arrays for components and foundations, formatted as SCSS variables
 
 **returns**
 
-- `css: CssTransformerOutput` This is an object containing all of the
+* `css: CssTransformerOutput` This is an object containing all of the
   tokens for components and foundations, formatted as type variables.
   Any changes you return here will be written to the scss type files.
 
@@ -244,11 +239,11 @@ and allows you to alter and return that configuration.
 
 **arguments**
 
-- `webpackConfig: webpack.Configuration` This is a full webpack configuration.
+* `webpackConfig: webpack.Configuration` This is a full webpack configuration.
 
 **returns**
 
-- `webpackConfig: webpack.Configuration` Return the webpack configuration that
+* `webpackConfig: webpack.Configuration` Return the webpack configuration that
   you have altered to fit your needs.
 
 **Example**
@@ -265,15 +260,14 @@ export const modifyWebpackConfigForTailwind = (webpackConfig: webpack.Configurat
 
 This hook allows you to alter the exportable list. You could do this by ejecting
 the handoff configuration and modifying the list, but this hook allows you to
-alter the exportable list with just a couple of lines of code rather than 
+alter the exportable list with just a couple of lines of code rather than
 exporting the whole list
 
 **arguments**
 
-- `exportables: string[]` The current list of exportables
+* `exportables: string[]` The current list of exportables
 
 **returns**
 
-- `exportables: string[]` Return the list with whatever additions and subtractions
-you need for your application.
-
+* `exportables: string[]` Return the list with whatever additions and subtractions
+  you need for your application.

package/handoff.config.js

@@ -0,0 +1,90 @@
+/** @type {import('handoff-app').Config} */
+const path = require('path');
+module.exports = {
+  // Set your Figma project ID here or in the environment variable HANDOFF_FIGMA_PROJECT_ID
+  figma_project_id: null,
+  // Set the output directory for the exported components
+  exportsOutputDirectory: 'exported',
+  // Set the output directory for the sites
+  sitesOutputDirectory: 'out',
+  // These settings control the behavior of the application
+  app: {
+    // Set the theme for the application
+    theme: 'default',
+    // Set the title for the application
+    title: 'Handoff Design System',
+    // Set the client for the application, used in the footer
+    client: 'Handoff Technologies',
+    // Set the Google Tag Manager ID to add GTM scripts
+    google_tag_manager: null,
+    // Set the attribution for the application
+    attribution: true, // Should we remove this?
+    // Set the type copy for the typeography page
+    type_copy: 'Almost before we knew it, we had left the ground.',
+    // Set the type sort for the typeography page
+    type_sort: [
+      'Heading 1',
+      'Heading 2',
+      'Heading 3',
+      'Heading 4',
+      'Heading 5',
+      'Heading 6',
+      'Paragraph',
+      'Subheading',
+      'Blockquote',
+      'Input Labels',
+      'Link',
+    ],
+    // Set the color sort for the color page
+    color_sort: ['primary', 'secondary', 'extra', 'system'],
+    // Set the component sort for the component page
+    component_sort: ['primary', 'secondary', 'transparent'],
+    // Set the base path for the application
+    base_path: '',
+    // Set the breakpoints for the application
+    breakpoints: {
+      sm: { size: 576, name: 'Small' },
+      md: { size: 768, name: 'Medium' },
+      lg: { size: 992, name: 'Large' },
+      xl: { size: 1200, name: 'Extra Large' },
+    },
+    // Set the ports for the application
+    ports: { app: 3000, websocket: 3001 },
+  },
+  // These are the entry points used to compile the target application
+  entries: {
+    scss: './sass/main.scss',
+    js: './js/main.js',
+    bundle: './js/main.js',
+    components: ['./test_components'],
+    patterns: ['./test_patterns'],
+  },
+  // These are the asset zip file download links
+  assets_zip_links: {
+    icons: null,
+    logos: null,
+  },
+  // Hooks allow you to override the default behavior of the application
+  hooks: {
+    // Alter the vite css build config
+    cssBuildConfig: (config) => {
+      return config;
+    },
+    // Validate each component before it is exported
+    validateComponent: (component) => {
+      return {};
+    },
+    // Alter the vite client build config
+    clientBuildConfig: (config) => {
+      return config;
+    },
+    // Alter the vite html build config
+    htmlBuildConfig: (config) => {
+      return config;
+    },
+    // Alter the vite js build config
+    jsBuildConfig: (config) => {
+      return config;
+    },
+  },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "handoff-app",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "description": "Automated documentation toolchain for building client side documentation from figma",
   "author ": {
     "name": "Convertiv",

package/src/cli.ts

@@ -19,7 +19,7 @@ class HandoffCliError extends Error {
  * Show the help message
  */
 const showVersion = () => {
-  return 'Handoff App - 1.1.1';
+  return 'Handoff App - 1.1.2';
 };
 
 /**

package/src/index.ts

@@ -297,7 +297,7 @@ class Handoff {
 }
 
 export type { ComponentObject as Component } from './transformers/preview/types';
-export type { Config } from './types/config';
+export type { Config, RegisterHandlebarsHelpersContext } from './types/config';
 
 // Export transformers and types from handoff-core
 export { Transformers as CoreTransformers, TransformerUtils as CoreTransformerUtils, Types as CoreTypes } from 'handoff-core';

package/src/transformers/plugins/handlebars-previews.ts

@@ -69,12 +69,14 @@ async function renderHandlebarsTemplate(
   template: string,
   componentData: TransformComponentTokensResult,
   previewData: PreviewRenderData,
-  injectFieldWrappers: boolean
+  injectFieldWrappers: boolean,
+  handoff: Handoff
 ): Promise<string> {
   // Register Handlebars helpers with current injection state
   registerHandlebarsHelpers(
-    { id: componentData.id, properties: componentData.properties || {} }, 
-    injectFieldWrappers
+    { id: componentData.id, properties: componentData.properties || {} },
+    injectFieldWrappers,
+    handoff.config?.hooks?.registerHandlebarsHelpers
   );
 
   const context = createHandlebarsContext({ 
@@ -181,14 +183,16 @@ export function handlebarsPreviewsPlugin(
             templateContent,
             componentData,
             previewData,
-            false
+            false,
+            handoff
           );
 
           const inspectModeHtml = await renderHandlebarsTemplate(
             templateContent,
             componentData,
             previewData,
-            true
+            true,
+            handoff
           );
 
           // Emit preview files

package/src/transformers/utils/handlebars.ts

@@ -1,40 +1,43 @@
 import Handlebars from 'handlebars';
+import { RegisterHandlebarsHelpersContext } from '../../types/config';
 import { Logger } from '../../utils/logger';
 import { SlotMetadata } from '../preview/component';
 import { HandlebarsContext } from '../types';
 
 /**
- * Registers common Handlebars helpers
+ * Registers common Handlebars helpers, then runs optional `hooks.registerHandlebarsHelpers`.
  * @param data - Component data containing properties
  * @param injectFieldWrappers - Whether to inject field wrappers for inspection
+ * @param extend - Optional callback from config to register additional helpers
  */
 export const registerHandlebarsHelpers = (
   data: { properties: { [key: string]: SlotMetadata }; id: string },
-  injectFieldWrappers: boolean
+  injectFieldWrappers: boolean,
+  extend?: (context: RegisterHandlebarsHelpersContext) => void
 ): void => {
   // Field helper for property binding
   Handlebars.registerHelper('field', function (field: string, options: any) {
     if (injectFieldWrappers) {
       if (!field) {
-        // This deebuging isn't helpful in the context of the component library
+        // This debugging isn't helpful in the context of the component library
         // Logger.error(`Missing field declaration for ${data.id}`);
         return options.fn(this);
       }
-      
+
       let parts = field.split('.');
       let current: any = data.properties;
-      
+
       for (const part of parts) {
         if (current?.type === 'object') current = current.properties;
         else if (current?.type === 'array') current = current.items.properties;
         current = current?.[part];
       }
-      
+
       if (!current) {
         Logger.error(`Undefined field path for ${data.id}`);
         return options.fn(this);
       }
-      
+
       return new Handlebars.SafeString(
         `<span class="handoff-field handoff-field-${current?.type || 'unknown'}" data-handoff-field="${field}" data-handoff="${encodeURIComponent(JSON.stringify(current))}">${options.fn(this)}</span>`
       );
@@ -47,6 +50,19 @@ export const registerHandlebarsHelpers = (
   Handlebars.registerHelper('eq', function (a: any, b: any) {
     return a === b;
   });
+
+  if (extend) {
+    try {
+      extend({
+        handlebars: Handlebars,
+        componentId: data.id,
+        properties: data.properties,
+        injectFieldWrappers,
+      });
+    } catch (err) {
+      Logger.error(`registerHandlebarsHelpers hook failed for ${data.id}`, err);
+    }
+  }
 };
 
 /**
@@ -61,9 +77,7 @@ export const createHandlebarsContext = (
   options?: { includeSharedStyles?: boolean }
 ): HandlebarsContext => {
   const basePath = process.env.HANDOFF_APP_BASE_PATH ?? '';
-  const sharedStylesLink = options?.includeSharedStyles
-    ? `<link rel="stylesheet" href="${basePath}/api/component/shared.css">`
-    : '';
+  const sharedStylesLink = options?.includeSharedStyles ? `<link rel="stylesheet" href="${basePath}/api/component/shared.css">` : '';
 
   return {
     style:

package/src/types/config.ts

@@ -1,4 +1,5 @@
 import { BuildOptions } from 'esbuild';
+import type Handlebars from 'handlebars';
 import { Types as HandoffTypes } from 'handoff-core';
 import { InlineConfig } from 'vite';
 import { SlotMetadata } from '../transformers/preview/component';
@@ -47,6 +48,14 @@ export interface Breakpoints {
   desktop: { size: number; name: string };
 }
 
+/** Context passed to the `registerHandlebarsHelpers` config hook after built-in helpers (`field`, `eq`) are registered for a preview render. */
+export type RegisterHandlebarsHelpersContext = {
+  handlebars: typeof Handlebars;
+  componentId: string;
+  properties: { [key: string]: SlotMetadata };
+  injectFieldWrappers: boolean;
+};
+
 export interface NextAppConfig {
   theme?: string;
   title: string;
@@ -240,6 +249,22 @@ export interface Config {
      * ```
      */
     htmlBuildConfig?: (config: InlineConfig) => InlineConfig;
+
+    /**
+     * Optional hook invoked after Handoff registers built-in Handlebars helpers for
+     * component preview HTML. Use `context.handlebars.registerHelper` to add or
+     * replace helpers. Called once per preview render (per variation and inspect mode).
+     *
+     * @param context - Handlebars runtime, component id/properties, and whether
+     *   inspect field wrappers are enabled for this render.
+     * @example
+     * ```typescript
+     * registerHandlebarsHelpers: ({ handlebars, componentId }) => {
+     *   handlebars.registerHelper('upperId', () => componentId.toUpperCase());
+     * }
+     * ```
+     */
+    registerHandlebarsHelpers?: (context: RegisterHandlebarsHelpersContext) => void;
   };
 }
 

package/templates/default/handoff.config.js.tpl

@@ -183,5 +183,21 @@ module.exports = {
     //   // Add your custom HTML build configuration here
     //   return config;
     // },
+
+    /**
+     * Optional hook run after built-in Handlebars helpers (`field`, `eq`) for preview HTML.
+     * @param context.handlebars - Handlebars module (use registerHelper)
+     * @param context.componentId - Current component id
+     * @param context.properties - Slot metadata map from the schema
+     * @param context.injectFieldWrappers - True when generating inspect-mode previews
+     *
+     * @example
+     * registerHandlebarsHelpers: ({ handlebars, componentId }) => {
+     *   handlebars.registerHelper('upperId', () => componentId.toUpperCase());
+     * }
+     */
+    // registerHandlebarsHelpers: ({ handlebars, componentId, properties, injectFieldWrappers }) => {
+    //   // Add your custom Handlebars helpers here
+    // },
   },
 };

package/templates/default/handoff.config.with-examples.js.tpl

@@ -184,5 +184,21 @@ module.exports = {
     //   // Add your custom HTML build configuration here
     //   return config;
     // },
+
+    /**
+     * Optional hook run after built-in Handlebars helpers (`field`, `eq`) for preview HTML.
+     * @param context.handlebars - Handlebars module (use registerHelper)
+     * @param context.componentId - Current component id
+     * @param context.properties - Slot metadata map from the schema
+     * @param context.injectFieldWrappers - True when generating inspect-mode previews
+     *
+     * @example
+     * registerHandlebarsHelpers: ({ handlebars, componentId }) => {
+     *   handlebars.registerHelper('upperId', () => componentId.toUpperCase());
+     * }
+     */
+    // registerHandlebarsHelpers: ({ handlebars, componentId, properties, injectFieldWrappers }) => {
+    //   // Add your custom Handlebars helpers here
+    // },
   },
 };