Figma Code Connect API — Gotchas and Type Traps

Collected from writing .figma.tsx Code Connect files and iterating with the MCP. All of these fail silently or with opaque errors.

1. `findInstance()` Returns an `ErrorHandle` on Failure (Truthy!)

figma.currentPage.findInstance(...) returns an ErrorHandle object — not null — when no match is found. ErrorHandle is truthy, so if (node) always passes.

// BAD — ErrorHandle passes the truthy check
const node = figma.currentPage.findInstance({ ... })
if (node) {
  node.mainComponent  // TypeError: node.mainComponent is undefined
}

// GOOD — always check the type
if (node && node.type === 'INSTANCE') {
  // safe to use
}

2. `executeTemplate().example` Is `ResultSection[]`, Not a String

figma.codeConnect.executeTemplate(node, template) returns { example: ResultSection[] }. If you concatenate it directly into a string you get [object Object].

// BAD
const output = `<div>${result.example}</div>`  // → "<div>[object Object]</div>"

// GOOD — map sections to their text
const output = result.example.map(s => s.code ?? s.title ?? '').join('\n')

3. `hasCodeConnect()` Guard Before `executeTemplate()` Silently Drops Instances

figma.codeConnect.hasCodeConnect(node) returns false for components that have no Code Connect mapping in the current file. If you guard executeTemplate() behind hasCodeConnect(), you silently skip all non-connected instances instead of falling back to generated code.

// BAD — silently skips ~80% of instances
if (figma.codeConnect.hasCodeConnect(node)) {
  executeTemplate(node, ...)
}

// GOOD — call executeTemplate unconditionally; it handles missing mappings
const result = figma.codeConnect.executeTemplate(node, template)
// result.example will still contain generated fallback code

4. `getSlot()` vs `getInstanceSwap()` — Wrong Property Type

figma.codeConnect.getSlot(prop) only works for SLOT property type.
figma.codeConnect.getInstanceSwap(prop) is required for INSTANCE_SWAP properties.

Using getSlot() on an INSTANCE_SWAP property returns undefined silently.

// Check property type first
const propType = node.componentPropertyDefinitions[propName].type

if (propType === 'SLOT') {
  return figma.codeConnect.getSlot(prop)
} else if (propType === 'INSTANCE_SWAP') {
  return figma.codeConnect.getInstanceSwap(prop)
}

5. `findInstance()` Requires `{ traverseInstances: true }` for Nested Layers

By default, findInstance() does not traverse into nested instances. If the target node is inside another instance, pass traverseInstances: true:

const node = figma.currentPage.findInstance({
  name: 'ButtonIcon',
  traverseInstances: true,   // ← required for nested layers
})

6. `path` Disambiguation When Siblings Share a Layer Name

If multiple siblings have the same layer name (common in design systems), findInstance() returns the first match. Use path to specify the parent:

const node = figma.currentPage.findInstance({
  name: 'Icon',
  path: ['CardContainer'],   // ← parent layer name narrows the search
  traverseInstances: true,
})

7. VARIANT Enum Mapping Must Be Exhaustive

When mapping a Figma VARIANT property to a code prop via figma.widget.usePropertyMenu, every possible variant value must be listed. Missing values silently produce undefined, which is then injected into JSX — no error thrown, malformed output.

// BAD — "Outline" variant not listed → produces undefined
figma.codeConnect.VARIANT('ButtonVariant', {
  'Default': 'primary',
  'Ghost': 'ghost',
  // 'Outline' missing → node with Outline variant → prop = undefined
})

// GOOD — enumerate all values
figma.codeConnect.VARIANT('ButtonVariant', {
  'Default': 'primary',
  'Ghost': 'ghost',
  'Outline': 'outline',   // ← exhaustive
})

How to audit: list all possible values of the Figma property via node.componentPropertyDefinitions[propName].variantOptions and cross-check against the VARIANT mapping.

wiki/concepts/figma-code-connect-plan-requirements — MCP vs CLI plan requirements
wiki/concepts/figma-mcp-tools-reference — full tool reference
wiki/concepts/figma-skills-reference — which skill to invoke for Code Connect

4.6 KiB Raw Blame History

Figma Code Connect API — Gotchas and Type Traps

1. findInstance() Returns an ErrorHandle on Failure (Truthy!)

2. executeTemplate().example Is ResultSection[], Not a String

3. hasCodeConnect() Guard Before executeTemplate() Silently Drops Instances

4. getSlot() vs getInstanceSwap() — Wrong Property Type

5. findInstance() Requires { traverseInstances: true } for Nested Layers

6. path Disambiguation When Siblings Share a Layer Name