Registry / crm-productivity / handoff-hubspot

handoff-hubspot

library0.2.1jsnpmunverified

A CLI toolchain (v0.2.1, pre-1.0, no regular release cadence) that fetches Handoff design system component payloads (Handlebars templates, property schemas) and transpiles them into HubSpot CMS .module folders. Handles Handlebars-to-HubL conversion (variables, conditionals, loops), automatic type-specific rewrites (links, buttons, menus, images, etc.), field JSON generation, metadata assembly, and module validation. Differentiators: schema-aware transpilation reducing manual HubL coding; no active alternatives bridging Handoff and HubSpot natively. Only works with Handoff API access.

crm-productivity devops

npm install handoff-hubspot

package ↗

INSTALL

IMPORT

SIG · HANDOFF-HUBSPOT

handoff-hubspot

crm-productivityjavascriptv0.2.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

fetchComponent

✓ import { fetchComponent } from 'handoff-hubspot'

✗ const { fetchComponent } = require('handoff-hubspot')

ESM-only since v0.1.0.

transpile

✓ import { transpile } from 'handoff-hubspot'

✗ import transpile from 'handoff-hubspot'

Named export, not default.

validateModule

✓ import { validateModule } from 'handoff-hubspot'

✗ import { validateModule } from 'handoff-hubspot/validate'

All exports are from the main entry point.

Fetches a Handoff component, validates it, transpiles to HubL, generates fields/meta, writes a .module folder.

import { fetchComponent, transpile, buildFields, buildMeta, writeModule } from 'handoff-hubspot'; async function main() { const component = await fetchComponent('your-component-id', { apiKey: process.env.HANDOFF_API_KEY ?? '' }); const validation = validateModule(component); if (validation.some(e => e.severity === 'error')) { console.error('Validation errors:', validation); process.exit(1); } const html = transpile(component.code, component.properties); const fields = buildFields(component.properties); const meta = buildMeta(component); await writeModule('./output/my-component.module', { html, fields, meta, css: '', js: '' }); console.log('Module generated.'); } main().catch(console.error);

handoff-hubspot --version

Debug

Known issues

deprecatedThe `field` block helper syntax ({{#field type}}) is deprecated and will be removed in v1.0.

fix

Use the new property-schema-aware transpilation (automatic). Remove manual {{#field}} blocks from Handlebars templates.

affects: >=0.1.0

gotchaHandoff API key is required but not validated until fetch time; invalid keys cause opaque 403 errors.

fix

Ensure HANDOFF_API_KEY env var is set. Use try/catch around fetchComponent and log the response status.

affects: >=0.1.0

breakingIn v0.1.0, writeModule accepted separate params; in v0.2.0 it was changed to a single options object.

fix

Update to writeModule('./path', { html, fields, meta, css, js }).

affects: >=0.1.0 <0.2.0

gotchaTranspiler outputs HubL for HubSpot but does not handle all Handlebars constructs (e.g., partials, subexpressions).

fix

Avoid using Handlebars partials or complex subexpressions. Stick to variables, conditionals, and each loops.

affects: >=0.1.0

breakingIn v0.1.0, the 'button' type was mapped to a single field; v0.2.0 introduced split fields (_url.href, _text).

fix

Regenerate fields.json with v0.2.0+. Existing modules may need field re-mapping.

affects: <0.2.0

Errors

Common errors & fixes

Error: Cannot find module 'handoff-hubspot'

Package not installed or not in node_modules.

fix

Run `npm install handoff-hubspot` or `yarn add handoff-hubspot`.

TypeError: fetchComponent is not a function

Default import used instead of named import.

fix

Change to `import { fetchComponent } from 'handoff-hubspot'`.

Error: HANDOFF_API_KEY is required

Environment variable HANDOFF_API_KEY not set.

fix

Set the variable: `export HANDOFF_API_KEY=your_key` or pass via .env file.

Upgrade

Version history

0.2.1latest on npm

Audit

Dependencies

@hubspot/clioptionalRequired to deploy generated modules to HubSpot CMS (not bundled).

Agent activity

48 hits · last 30 days

node

OpenAI (training)

Resources

packagehttps://www.npmjs.com/package/handoff-hubspot ↗