{"id":25720,"library":"handoff-hubspot","title":"Handoff HubSpot Transformer CLI","description":"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.","status":"active","version":"0.2.1","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","typescript"],"install":[{"cmd":"npm install handoff-hubspot","lang":"bash","label":"npm"},{"cmd":"yarn add handoff-hubspot","lang":"bash","label":"yarn"},{"cmd":"pnpm add handoff-hubspot","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required to deploy generated modules to HubSpot CMS (not bundled).","package":"@hubspot/cli","optional":true}],"imports":[{"note":"ESM-only since v0.1.0.","wrong":"const { fetchComponent } = require('handoff-hubspot')","symbol":"fetchComponent","correct":"import { fetchComponent } from 'handoff-hubspot'"},{"note":"Named export, not default.","wrong":"import transpile from 'handoff-hubspot'","symbol":"transpile","correct":"import { transpile } from 'handoff-hubspot'"},{"note":"All exports are from the main entry point.","wrong":"import { validateModule } from 'handoff-hubspot/validate'","symbol":"validateModule","correct":"import { validateModule } from 'handoff-hubspot'"}],"quickstart":{"code":"import { fetchComponent, transpile, buildFields, buildMeta, writeModule } from 'handoff-hubspot';\n\nasync function main() {\n  const component = await fetchComponent('your-component-id', { apiKey: process.env.HANDOFF_API_KEY ?? '' });\n  const validation = validateModule(component);\n  if (validation.some(e => e.severity === 'error')) {\n    console.error('Validation errors:', validation);\n    process.exit(1);\n  }\n  const html = transpile(component.code, component.properties);\n  const fields = buildFields(component.properties);\n  const meta = buildMeta(component);\n  await writeModule('./output/my-component.module', { html, fields, meta, css: '', js: '' });\n  console.log('Module generated.');\n}\nmain().catch(console.error);","lang":"typescript","description":"Fetches a Handoff component, validates it, transpiles to HubL, generates fields/meta, writes a .module folder."},"warnings":[{"fix":"Use the new property-schema-aware transpilation (automatic). Remove manual {{#field}} blocks from Handlebars templates.","message":"The `field` block helper syntax ({{#field type}}) is deprecated and will be removed in v1.0.","severity":"deprecated","affected_versions":">=0.1.0"},{"fix":"Ensure HANDOFF_API_KEY env var is set. Use try/catch around fetchComponent and log the response status.","message":"Handoff API key is required but not validated until fetch time; invalid keys cause opaque 403 errors.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Update to writeModule('./path', { html, fields, meta, css, js }).","message":"In v0.1.0, writeModule accepted separate params; in v0.2.0 it was changed to a single options object.","severity":"breaking","affected_versions":">=0.1.0 <0.2.0"},{"fix":"Avoid using Handlebars partials or complex subexpressions. Stick to variables, conditionals, and each loops.","message":"Transpiler outputs HubL for HubSpot but does not handle all Handlebars constructs (e.g., partials, subexpressions).","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Regenerate fields.json with v0.2.0+. Existing modules may need field re-mapping.","message":"In v0.1.0, the 'button' type was mapped to a single field; v0.2.0 introduced split fields (_url.href, _text).","severity":"breaking","affected_versions":"<0.2.0"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Run `npm install handoff-hubspot` or `yarn add handoff-hubspot`.","cause":"Package not installed or not in node_modules.","error":"Error: Cannot find module 'handoff-hubspot'"},{"fix":"Change to `import { fetchComponent } from 'handoff-hubspot'`.","cause":"Default import used instead of named import.","error":"TypeError: fetchComponent is not a function"},{"fix":"Set the variable: `export HANDOFF_API_KEY=your_key` or pass via .env file.","cause":"Environment variable HANDOFF_API_KEY not set.","error":"Error: HANDOFF_API_KEY is required"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}