Code Connect v1.4.8

Author: figma-bot

CHANGELOG.md

@@ -1,7 +1,28 @@
-# Code Connect v1.4.7 (28 May 2026)
+# Code Connect v1.4.8 (8 June 2026)
+
+## Fixed
+
+### General
+
+- Fixed browser compatibility issues where importing `@figma/code-connect` in Storybook or webpack environments would fail with "Can't resolve 'child_process'" or "Console is not a constructor" errors. Node.js-only modules (`child_process`, `console`) are now imported dynamically only when needed by CLI commands, making the package safe to use in browser environments.
+
+### Template files
+
+- Fixed parserless template projects failing to publish or parse when Code Connect could not infer a React, HTML, Swift, or Compose parser. The CLI now proceeds without a parser and uses the default template-file globs.
+- Fixed a "`getInstanceSwap(...)?.executeTemplate is not a function`" error that could break a template when `getInstanceSwap('prop')` referenced an instance-swap property that isn't present on the selected node (for example a property that is conditionally hidden by a boolean). The missing property now renders an inline error, consistent with the other accessors, instead of failing the whole template.
+- Fixed migrated text-layer references (from the React/HTML `figma.textContent('...')` helper) producing a TypeScript error and silently rendering nothing when the layer was missing. Migration now preserves the original behavior — the text renders when the layer is found, and a clear error is shown when it isn't.
 
 ## Features
 
+### Template files
+
+- The `figma connect migrate` command now uses the same `--dir` and `--file` filtering behavior as `publish`, `parse`, and `unpublish`. The migrate-only positional glob argument has been removed.
+- The `figma connect migrate` command can now migrate compatible large source files into batch template files. Files with 10 or more Code Connect docs are attempted automatically, `--batch all` forces a batch attempt, and `--batch none` disables batch migration.
+
+# Code Connect v1.4.7 (28 May 2026)
+
+## Fixed
+
 ### General
 
 - The `--file` (`-f`) option on `figma connect publish`, `unpublish`, and `parse` now accepts multiple files, so you can target several Code Connect files in one command (e.g. `figma connect publish --file a.figma.ts b.figma.ts`). Previously only a single file path was accepted.

cli/figma-types.d.ts

@@ -103,7 +103,7 @@ declare module 'figma' {
       propName: string,
       options: O,
     ): EnumOptionsValues<O> | undefined
-    getInstanceSwap(propName: string): InstanceHandle | undefined
+    getInstanceSwap(propName: string): InstanceHandle | ErrorHandle | undefined
     getSlot(propName: string): ResultSection[] | undefined
     hasCodeConnect(): boolean
     getPropertyValue(name: string): string | boolean | ErrorHandle

cli/npm_catalog.toml

@@ -250,7 +250,7 @@
 "@zip.js/zip.js" = "2.8.19"
 "zod-to-json-schema" = "^3.23.5"
 "zod" = "3.25.58"
-"@anthropic-ai/claude-agent-sdk" = "0.2.69"
+"@anthropic-ai/claude-agent-sdk" = "0.3.168"
 "ai" = "4.1.62"
 "@ai-sdk/amazon-bedrock" = "2.1.4"
 "@ai-sdk/anthropic" = "1.2.5"

cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@figma/code-connect",
-  "version": "1.4.7",
+  "version": "1.4.8",
   "description": "A tool for connecting your design system components in code with your design system in Figma",
   "keywords": [],
   "author": "Figma",

cli/src/commands/__test__/parseRawFile.test.ts

@@ -1,4 +1,4 @@
-import { parseRawFile, isRawTemplate } from '../../connect/raw_templates'
+import { parseRawFile, isRawTemplate, CodePropertiesError } from '../../connect/raw_templates'
 import { CodeConnectConfig } from '../../connect/project'
 import { SyntaxHighlightLanguage } from '../../connect/label_language_mapping'
 import fs from 'fs'
@@ -418,4 +418,47 @@ export default figma.code\`<Button />\``
       'TypeScript template files only support importing from',
     )
   })
+
+  it('throws CodePropertiesError (skip) for a url-less file containing codeProperties', () => {
+    // No url + contains `codeProperties` => skip signal, as long as the file has
+    // no unsupported import (see the test below).
+    const fileContent = `// component=Button
+export const codeProperties = { value: 1 }`
+
+    fs.writeFileSync(tempFilePath, fileContent)
+
+    expect(() => parseRawFile(tempFilePath, undefined)).toThrow(CodePropertiesError)
+    expect(() => parseRawFile(tempFilePath, undefined)).not.toThrow(
+      'TypeScript template files only support importing from',
+    )
+  })
+
+  it('fails on a non-figma import even when the file contains codeProperties', () => {
+    // An unsupported import is always a hard error and takes precedence over the
+    // codeProperties skip, so an import mistake is never silently swallowed.
+    const fileContent = `// component=Button
+import { helper } from './helper'
+export const codeProperties = { value: helper() }`
+
+    fs.writeFileSync(tempFilePath, fileContent)
+
+    expect(() => parseRawFile(tempFilePath, undefined)).toThrow(
+      'TypeScript template files only support importing from',
+    )
+    expect(() => parseRawFile(tempFilePath, undefined)).not.toThrow(CodePropertiesError)
+  })
+
+  it('still surfaces the original import error for a url-less file WITHOUT codeProperties', () => {
+    // Unchanged behaviour: only `codeProperties` files are skipped; any other
+    // url-less file with a non-figma import fails on the import error as before.
+    const fileContent = `// component=Button
+import { helper } from './helper'
+export default helper`
+
+    fs.writeFileSync(tempFilePath, fileContent)
+
+    expect(() => parseRawFile(tempFilePath, undefined)).toThrow(
+      'TypeScript template files only support importing from',
+    )
+  })
 })

cli/src/commands/connect.ts

@@ -44,7 +44,11 @@ import {
   writeTemplateFile,
   writeVariantTemplateFile,
 } from '../connect/migration_helpers'
-import { isRawTemplate, parseRawFile } from '../connect/raw_templates'
+import {
+  getBatchMigrationGroups,
+  writeBatchTemplateFiles,
+} from '../connect/migration_batch_helpers'
+import { CodePropertiesError, isRawTemplate, parseRawFile } from '../connect/raw_templates'
 import { parseBatchFile } from '../connect/batch_templates'
 import { convertRemoteFileUrlToRelativePath } from '../connect/wizard/run_wizard'
 import { getGitRepoAbsolutePath } from '../connect/project'
@@ -63,8 +67,11 @@ export type BaseCommand = commander.Command & {
   exitOnUnreadableFiles: boolean
   apiUrl?: string
   includeProps?: boolean
+  batch?: BatchMigrationMode
 }
 
+type BatchMigrationMode = 'auto' | 'all' | 'none'
+
 function addBaseCommand(command: commander.Command, name: string, description: string) {
   return command
     .command(name)
@@ -167,9 +174,8 @@ export function addConnectCommandToProgram(program: commander.Command) {
   addBaseCommand(
     connectCommand,
     'migrate',
-    'Parse Code Connect files and migrate their templates into .figma.js files that can be published directly without parsing.',
+    'Parse Code Connect files and migrate their templates into .figma.ts or .figma.js files that can be published directly without parsing.',
   )
-    .argument('[pattern]', 'glob pattern to match files (optional, uses config if not provided)')
     .option(
       '--include-props',
       'preserve __props metadata blocks in migrated templates (removed by default). Use if your templates use the React .getProps() or .render() modifiers, or read executeTemplate().metadata.__props from the migrated components',
@@ -178,6 +184,14 @@ export function addConnectCommandToProgram(program: commander.Command) {
       '--javascript',
       'output migrated templates as JavaScript (.figma.js) instead of TypeScript (.figma.ts)',
     )
+    .addOption(
+      new commander.Option(
+        '--batch <mode>',
+        'batch migration mode: auto attempts files with 10 or more Code Connect docs; all attempts every source file; none disables batch migration',
+      )
+        .choices(['auto', 'all', 'none'])
+        .default('auto'),
+    )
     .action(withUpdateCheck(handleMigrate))
 
   addBaseCommand(
@@ -364,6 +378,15 @@ export async function getCodeConnectObjects(
         }
         rawTemplateDocs.push(doc)
       } catch (e) {
+        // A url-less file containing `codeProperties` is not Code Connect (e.g.
+        // Make's code component property definitions). Log and skip it instead
+        // of failing — never exit, not even with --exit-on-unreadable-files.
+        if (e instanceof CodePropertiesError) {
+          if (!silent || cmd.verbose) {
+            logger.info(e.message)
+          }
+          continue
+        }
         if (!silent || cmd.verbose) {
           logger.error(`❌ ${file}`)
           if (cmd.verbose) {
@@ -720,14 +743,11 @@ async function handleCreate(nodeUrl: string, cmd: BaseCommand) {
  * - Format as valid parserless file w/ url="" comment
  * - Name collisions are skipped, unless file is from migration (in which case add "_1")
  */
-async function handleMigrate(
-  pattern: string | undefined,
-  cmd: BaseCommand & { javascript?: boolean },
-) {
+async function handleMigrate(cmd: BaseCommand & { javascript?: boolean }) {
   setupHandler(cmd)
 
   const dir = cmd.dir ?? process.cwd()
-  let projectInfo = await getProjectInfo(dir, cmd.config)
+  let projectInfo = filterProjectInfoByFile(await getProjectInfo(dir, cmd.config), cmd.file)
   const documentUrlSubstitutions = projectInfo.config.documentUrlSubstitutions
 
   // Clear documentUrlSubstitutions so we preserve original URLs in migrated templates
@@ -739,44 +759,63 @@ async function handleMigrate(
     },
   }
 
-  // If a glob pattern is provided, override the project files
-  if (pattern) {
-    const { globSync } = require('glob')
-    const files = globSync(pattern, {
-      cwd: dir,
-      absolute: true,
-      nodir: true,
-    })
-
-    if (files.length === 0) {
-      exitWithError(`No files found matching pattern: ${pattern}`)
-    }
-
-    logger.info(`Found ${files.length} file(s) matching pattern: ${pattern}`)
-    projectInfo = {
-      ...projectInfo,
-      files,
-    }
-  }
-
   // Parse the files to get Code Connect objects
   const allCodeConnectObjects = await getCodeConnectObjects(cmd, projectInfo, false, true)
 
-  const codeConnectObjectsByFigmaUrl = groupCodeConnectObjectsByFigmaUrl(allCodeConnectObjects)
-
-  const groupCount = Object.keys(codeConnectObjectsByFigmaUrl).length
+  const allCodeConnectObjectsByFigmaUrl = groupCodeConnectObjectsByFigmaUrl(allCodeConnectObjects)
+  const groupCount = Object.keys(allCodeConnectObjectsByFigmaUrl).length
   if (groupCount === 0) {
     exitWithError('No Code Connect objects found to migrate')
   }
 
   logger.info(`Found ${groupCount} component(s) to migrate`)
   let migratedCount = 0
+  let batchMigratedCount = 0
   let skippedCount = 0
   const errors: string[] = []
+  const batchMigrationWarnings: Array<{
+    path: string
+    connectionCount: number
+    reason: string
+  }> = []
 
   const filePathsCreated = new Set<string>()
   const gitRootPath = getGitRepoAbsolutePath(dir)
   const useTypeScript = !cmd.javascript
+  const batchMigratedDocs = new Set<CodeConnectJSON>()
+  const batchDocsByPath = getBatchMigrationGroups(allCodeConnectObjects, {
+    batchAll: cmd.batch === 'all',
+    disabled: cmd.batch === 'none',
+  })
+
+  for (const [batchPath, docs] of batchDocsByPath) {
+    const result = writeBatchTemplateFiles(docs, cmd.outDir, dir, {
+      localSourcePath: batchPath,
+      filePathsCreated,
+      includeProps: cmd.includeProps,
+      useTypeScript,
+    })
+
+    if (result.skipped) {
+      batchMigrationWarnings.push({
+        path: batchPath,
+        connectionCount: docs.length,
+        reason: result.reason || 'unable to create batch files',
+      })
+    } else {
+      logger.info(
+        `${success('✓')} Migrated ${result.componentCount} component(s) to batch ${highlight(result.batchPath || batchPath)}`,
+      )
+      migratedCount += result.componentCount
+      batchMigratedCount += result.componentCount
+      docs.forEach((doc) => batchMigratedDocs.add(doc))
+    }
+  }
+
+  const regularCodeConnectObjects = allCodeConnectObjects.filter(
+    (doc) => !batchMigratedDocs.has(doc),
+  )
+  const codeConnectObjectsByFigmaUrl = groupCodeConnectObjectsByFigmaUrl(regularCodeConnectObjects)
 
   for (const [figmaUrl, group] of Object.entries(codeConnectObjectsByFigmaUrl)) {
     try {
@@ -847,7 +886,10 @@ async function handleMigrate(
         const language = getInferredLanguageForRaw(label, docLanguage)
         const config: CodeConnectParserlessConfig = {
           parser: undefined,
-          include: [useTypeScript ? '**/*.figma.ts' : '**/*.figma.js'],
+          include: [
+            useTypeScript ? '**/*.figma.ts' : '**/*.figma.js',
+            ...(batchMigratedCount > 0 ? ['**/*.figma.batch.json'] : []),
+          ],
           language,
           label,
           ...(documentUrlSubstitutions && Object.keys(documentUrlSubstitutions).length > 0
@@ -860,6 +902,20 @@ async function handleMigrate(
     }
   }
 
+  if (batchMigrationWarnings.length > 0) {
+    console.log('')
+    logger.warn('Unable to migrate the following files to batch files:')
+    batchMigrationWarnings.forEach((warning) => {
+      logger.warn(
+        `- ${highlight(warning.path)} (${warning.connectionCount} connections): ${formatBatchMigrationWarningReason(warning.reason)}`,
+      )
+    })
+    console.log('')
+    logger.warn(
+      "If you'd like to create batch files for these, we recommend using a coding agent. See example prompt: https://developers.figma.com/docs/code-connect/template-files/#migration-script",
+    )
+  }
+
   // Summary
   console.log('')
   logger.info(
@@ -877,3 +933,10 @@ async function handleMigrate(
     exitWithError('No files were migrated')
   }
 }
+
+function formatBatchMigrationWarningReason(reason: string) {
+  const strippedReason = reason.replace(/^Cannot batch:\s*/i, '')
+  return strippedReason.replace(/^(\s*)(\S)/, (_match, prefix: string, firstChar: string) => {
+    return `${prefix}${firstChar.toUpperCase()}`
+  })
+}

cli/src/commands/connect_template.ts

@@ -10,7 +10,7 @@ import { LogLevel, exitWithError, highlight, logger, success } from '../common/l
 import { CodeConnectJSON } from '../connect/figma_connect'
 import { delete_docs } from '../connect/delete_docs'
 import { exitWithFeedbackMessage } from '../connect/helpers'
-import { isRawTemplate, parseRawFile } from '../connect/raw_templates'
+import { CodePropertiesError, isRawTemplate, parseRawFile } from '../connect/raw_templates'
 import { parseBatchFile } from '../connect/batch_templates'
 import { filterProjectInfoByFile } from './filter_project_info'
 import { createCodeConnectFromUrl } from '../connect/create_template'
@@ -92,6 +92,15 @@ async function getCodeConnectObjects(
         }
         rawTemplateDocs.push(doc)
       } catch (e) {
+        // A url-less file containing `codeProperties` is not Code Connect (e.g.
+        // Make's code component property definitions). Log and skip it instead
+        // of failing — never exit, not even with --exit-on-unreadable-files.
+        if (e instanceof CodePropertiesError) {
+          if (!silent || cmd.verbose) {
+            logger.info(e.message)
+          }
+          continue
+        }
         if (!silent || cmd.verbose) {
           logger.error(`❌ ${file}`)
           if (cmd.verbose) {