core

@figmavars/core

@figmavars/core provides the shared Figma Variables types, normalization, alias resolution, comparison, and REST API functions used by FigmaVars.

npm install @figmavars/core

Requirements

• Node.js 24 or newer

Normalize a variables export

import { normalizeVariables } from '@figmavars/core'

const normalized = normalizeVariables(json)

normalized.collections
normalized.variables
normalized.collectionsById
normalized.variablesById
normalized.warnings

normalizeVariables accepts:

• a Figma REST local variables response
• a bare { variables, variableCollections } object
• a plugin-style { variables, collections } object
• a JSON string containing one of those shapes

It rejects published-variable responses because those records do not contain the mode values needed for conversion.

Resolve aliases

import { resolveAllVariableValues, resolveVariableValue } from '@figmavars/core'

const result = resolveVariableValue(normalized, 'VariableID:2:201', '1:0')

console.log(result.value, result.aliasChain)

const resolved = resolveAllVariableValues(normalized)
console.log(resolved.values, resolved.errors)

The resolver follows variable aliases across collections. It reports cycles, missing targets, and values that cannot resolve for a requested mode.

Compare two exports

import { diffVariables, formatDiffMarkdown } from '@figmavars/core'

const diff = diffVariables(previousExport, nextExport)

console.log(diff.variables.renamed)
console.log(diff.variables.valueChanged)
console.log(diff.breaking)
console.log(formatDiffMarkdown(diff))

The comparison matches collections and variables by Figma ID. Its breaking flag covers removals, renames, moves, and type changes.

Call the Variables REST API

import { fetcher, FIGMA_LOCAL_VARIABLES_ENDPOINT, mutator, withRetry } from '@figmavars/core'

const variables = await fetcher(FIGMA_LOCAL_VARIABLES_ENDPOINT(fileKey), token)

The package exports endpoint builders, FigmaApiError, retry helpers, runtime type guards, mutation payload types, and Figma domain types. Import the domain types from the package root or @figmavars/core/types.

redactToken returns a shortened display value. The result still exposes token characters, so do not treat it as safe for logs.

Related packages

• @figmavars/dtcg converts normalized data into token files.
• @figmavars/cli writes a token pipeline to disk.
• @figmavars/hooks provides React hooks.

Read the FigmaVars documentation or review the 5.0.0 changelog.

License

MIT © Mark Learst