Framer Plugins

Framer Plugin Development Guide

You are an expert on the Framer Plugin SDK. Use this reference when building, debugging, or modifying Framer plugins. Always check the project's CLAUDE.md for project-specific overrides.

Quick Reference

• SDK package: @framer/plugin (v4+, the Framer 3.0 release). Renamed from framer-plugin, which is now deprecated on npm — never use the old name.
• Scaffolding: npm create framer-plugin@latest (the create-framer-plugin scaffolder keeps its name and installs @framer/plugin)
• Build: Vite + vite-plugin-framer (name unchanged; framer-plugin-tools pack CLI also unchanged)
• Base styles: import "@framer/plugin/framer.css" (optional: import "@framer/plugin/inter.css" to load Inter alone)
• Core import: import { framer } from "@framer/plugin"
• Dev workflow: npm run dev → Framer → Developer Tools → Development Plugin

SDK v4 (2026-06-16) and the recent v3.x additions

v4.0 itself is mostly the rename (version attributions verified against the official changelog 2026-07-13). Shipped in v4: the package rename framer-plugin → @framer/plugin (current stable 4.0.1; the old package is deprecated on npm; migration is a mechanical find-replace — no commonly-used API was removed; peerDeps react/react-dom ^18.2.0, csstype ^3.1.1), a restyled framer.css (Framer 3.0 design: new Inter character alternates, selection colors, input element styles — re-check custom input/selection styling after upgrading; new @framer/plugin/inter.css export loads Inter alone), WebPageNode.clone() / DesignPageNode.clone(), an optional filter on getLocalizationGroups(), new frame/text link attributes, and setParent accepting UnknownNode.

Added during v3.x (2025 – early 2026) — newer than many published examples, none permission-gated:

• framer.navigateTo(nodeId, opts?) (3.7.0) — selects + zooms a node into view (opts: { select?=true, zoom? }). Instance forms: node.navigateTo(), collectionItem.navigateTo(), codeFile.navigateTo(). Ideal right after an insert/replace.
• framer.setMenu(items) and framer.showContextMenu(items, config) (3.5.2) — global window-header menu + context menus anywhere in the plugin UI.
• framer.subscribeToOpenCodeFile(cb) (3.7.0) — fires when the user opens/switches code files.
• Design Pages (3.8.0): read/create/edit nodes on Design Pages via the same Nodes + Selection APIs.
• CMS: access all Collections (not just plugin-managed) and write to unmanaged collections (Plugins 3.0, Mar 2025); framer.createManagedCollection() (3.10.2); framer.setCloseWarning() (3.10.3). framer.getManagedCollection() is deprecated → use getActiveManagedCollection() (the deprecation is in the d.ts; the CMS docs page still shows the old call in examples).

Starting a New Plugin

1. npm create framer-plugin@latest → scaffolds Vite + React + framer.json + a sample App.
2. Pick modes first (see table below). CMS plugins need configureManagedCollection + syncManagedCollection; asset/insert plugins use canvas (or image/editImage).
3. import "@framer/plugin/framer.css" and call framer.showUI(...) in a useLayoutEffect.
4. Decide storage early: localStorage for per-user secrets, pluginData for shared state (see the decision tree below).

Cloning an existing plugin to start a new one? Change framer.json's id to a fresh hex value. A duplicate id makes Framer treat the two plugins as the same plugin — they share installation state, localStorage origin, and pluginData namespace, which silently cross-contaminates dev. The scaffolder generates a unique id; preserve that property when copying a repo.

framer.json

Every plugin needs a framer.json at the project root:

{
  "id": "6bbb4f",
  "name": "My Plugin",
  "modes": ["configureManagedCollection", "syncManagedCollection"],
  "icon": "/icon.svg"
}

• id — unique hex identifier (auto-generated by scaffolding)
• modes — array of supported modes (see below)
• icon — 30×30, SVG or bitmap (supply bitmaps at 90×90 px), in public/. SVGs need careful centering.

Plugin Modes

CMS plugins use both configureManagedCollection + syncManagedCollection. (The v4 d.ts Mode union also carries an undocumented api value — ignore it unless the docs pick it up.)

Core framer API

UI Management

framer.showUI({ position?, width, height, minWidth?, minHeight?, maxWidth?, resizable? })
framer.hideUI()
framer.closePlugin(message?, { variant: "success" | "error" | "info" })  // returns never
framer.notify(message, { variant?, durationMs?, button?: { text, onClick } })
framer.setCloseWarning(message | false)  // warn before closing during sync
framer.setBackgroundMessage(message)     // status while plugin runs hidden
framer.setMenu([{ label, onAction, visible? }, { type: "separator" }])
framer.showContextMenu(items, { location })        // context menu inside the plugin UI (3.0)
framer.navigateTo(nodeId, { select?, zoom? })      // select + zoom a node into view (3.0; not gated)
framer.subscribeToOpenCodeFile(callback)           // fires on code-file open/switch (3.0)

• closePlugin throws FramerPluginClosedError internally — always ignore in catch blocks
• showUI should be called in useLayoutEffect to avoid flicker

Properties

• framer.mode — current mode string

Collection Access

framer.getActiveManagedCollection()    // → Promise<ManagedCollection>
framer.getActiveCollection()           // → Promise<Collection> (unmanaged)
framer.getManagedCollections()          // → Promise<ManagedCollection[]>
framer.getCollections()                // → Promise<Collection[]>
framer.createManagedCollection()       // → Promise<ManagedCollection>

Canvas Methods (canvas mode)

framer.addImage(image)                // NamedImageAssetInput | File → Promise<void>
framer.setImage(image)                // sets on the current selection
framer.getImage()
framer.addText(text, options?)
framer.addSVG(svg)                     // SVGData; max 10kB
framer.addComponentInstance({ url, attributes?, parentId? })  // → Promise<ComponentInstanceNode>
framer.addDetachedComponentLayers({ url, layout, attributes? })  // → Promise<FrameNode> (inlines the layers)
framer.getSelection()
framer.subscribeToSelection(callback)

addComponentInstance resolves to the created node — keep it; you need its id for selection-aware replace/geometry-copy flows. addImage/addSVG/addText resolve to void.

CMS / ManagedCollection (pointer)

CMS plugins are their own world — the full surface (ManagedCollection API, field types, the silent-sync algorithm, user-editable fields, slug generation, field-data type wrappers, CMS pitfalls) lives in cms-managed-collections.md. Read it when the plugin syncs an external data source into a Framer collection; skip it otherwise.

Two things to carry even if you never open that file:

• ManagedCollection.addItems() is an upsert (matched by id) — and there is no getItems(), only getItemIds().
• Every fieldData value needs an explicit type wrapper: { type: "string", value: "..." }. Raw values are silently ignored.

Permissions

import { framer, useIsAllowedTo, type ProtectedMethod } from "@framer/plugin"

// Imperative check
framer.isAllowedTo("ManagedCollection.addItems", "ManagedCollection.removeItems")

// React hook (reactive)
const canSync = useIsAllowedTo("ManagedCollection.addItems", "ManagedCollection.removeItems")

// Standard CMS sync permissions
const SYNC_METHODS = [
    "ManagedCollection.setFields",
    "ManagedCollection.addItems",
    "ManagedCollection.removeItems",
    "ManagedCollection.setPluginData",
] as const satisfies ProtectedMethod[]

Only mutating methods are permission-gated. Reads — getItemIds, getPluginData, getActiveManagedCollection, getFields — have empty arrays in the SDK ProtectedMethod table, so isAllowedTo() on them always returns true. Gate writes; wrap reads in try/catch for robustness instead of adding no-op read guards. (The docs' own phrasing: unprotected methods "mostly start with get, but not all" — when unsure, let TypeScript decide: if a name isn't accepted as a ProtectedMethod, it needs no gate.)

Marketplace-reviewer contract (verdict-tested 2026-07): the automated review wants, at EVERY protected call site, all three of: an explicit framer.isAllowedTo() check adjacent to the call (a reactive useIsAllowedTo early-return far upstream does not count on its own), try/catch around the call with clear user-facing failure copy (no silent no-ops), and UI disabled via useIsAllowedTo while the permission is missing. Ungated protected calls in dead/parked code get flagged too — delete them. Detail: marketplace.md.

Data Storage Decision Tree

• pluginData: 2kB per entry, 4kB total. Strings only. Pass null to delete.
• pluginData is for small, bounded values. Anything that grows with content count (per-item delta-sync state, caches) will exceed 2kB/entry — keep it in localStorage and treat it as a rebuildable optimization, not shared truth (per-user, so collaborators rebuild it on first use).
• pluginData is namespaced per plugin — other plugins (and external agent tooling) cannot read or write your keys.
• localStorage: Sandboxed per-plugin origin, persists across all projects, but per-browser/device — soft friction only, never enforcement.
• setPluginData() (and other protected methods) surface an "Invoking protected message type" toast when called without a prior framer.isAllowedTo() check. It's the permission system, not a bug — gate the call and the toast disappears.