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 (v3.6+)
• Scaffolding: npm create framer-plugin@latest
• Build: Vite + vite-plugin-framer
• Base styles: import "framer-plugin/framer.css"
• Core import: import { framer } from "framer-plugin"
• Dev workflow: npm run dev → Framer → Developer Tools → Development Plugin

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/PNG in public/. SVGs need careful centering.

Plugin Modes

CMS plugins use both configureManagedCollection + syncManagedCollection.

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" }])

• 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, name, altText })
framer.setImage({ image, name, altText })
framer.getImage()
framer.addText(text)
framer.addFrame()
framer.addSVG(svg, name)              // max 10kB
framer.addComponentInstance({ url, attributes? })
framer.getSelection()
framer.subscribeToSelection(callback)

ManagedCollection API

interface ManagedCollection {
    id: string
    getItemIds(): Promise<string[]>
    setItemOrder(ids: string[]): Promise<void>
    getFields(): Promise<ManagedCollectionField[]>
    setFields(fields: ManagedCollectionFieldInput[]): Promise<void>
    addItems(items: ManagedCollectionItemInput[]): Promise<void>   // upsert!
    removeItems(ids: string[]): Promise<void>
    setPluginData(key: string, value: string | null): Promise<void>
    getPluginData(key: string): Promise<string | null>
}

Critical: addItems() is an upsert — it adds new items and updates existing ones matched by id.

Field Types

"boolean" | "color" | "number" | "string" | "formattedText" |
"image" | "file" | "link" | "date" | "enum" |
"collectionReference" | "multiCollectionReference" | "array"

Field Definition

interface ManagedCollectionFieldInput {
    id: string
    name: string
    type: CollectionFieldType
    userEditable?: boolean        // default false for managed
    cases?: { id, name }[]       // for "enum"
    collectionId?: string         // for collection references
    fields?: ManagedCollectionFieldInput[]  // for "array" (gallery)
}

Item Structure

interface ManagedCollectionItemInput {
    id: string
    slug: string
    draft: boolean
    fieldData: Record<string, FieldDataEntryInput>
}

Field Data Values — MUST specify type explicitly

{ type: "string", value: "hello" }
{ type: "number", value: 42 }
{ type: "boolean", value: true }
{ type: "date", value: "2024-01-01T00:00:00Z" }   // ISO 8601
{ type: "link", value: "https://example.com" }
{ type: "image", value: "https://img.url" | null }
{ type: "file", value: "https://file.url" | null }
{ type: "color", value: "#FF0000" | null }
{ type: "formattedText", value: "<p>hello</p>", contentType: "html" }
{ type: "enum", value: "case-id" }
{ type: "collectionReference", value: "item-id" }
{ type: "multiCollectionReference", value: ["id1", "id2"] }
{ type: "array", value: [{ id: "1", fieldData: { ... } }] }

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[]

Data Storage Decision Tree

• pluginData: 2kB per entry, 4kB total. Strings only. Pass null to delete.
• localStorage: Sandboxed per-plugin origin. No size warnings.
• setPluginData() triggers "Invoking protected message type" toast (SDK bug).

Key Exports from "framer-plugin"

import { framer, useIsAllowedTo, FramerPluginClosedError } from "framer-plugin"
import type {
    ManagedCollection, ManagedCollectionField, ManagedCollectionFieldInput,
    ManagedCollectionItemInput, FieldDataInput, FieldDataEntryInput,
    ProtectedMethod, Collection, CollectionItem
} from "framer-plugin"
import "framer-plugin/framer.css"

Supporting References

For deeper information, see the companion files in this skill directory:

• api-reference.md — Complete API signatures and type definitions
• patterns.md — Common plugin patterns extracted from 32 official examples
• pitfalls.md — Known gotchas, workarounds, and debugging tips

Key Rules

1. Always check the project's CLAUDE.md for project-specific overrides and decisions
2. CMS plugins should attempt silent sync in syncManagedCollection mode before showing UI
3. addItems() is upsert — no need to check for existing items before adding
4. Field data values MUST include explicit type property: { type: "string", value: "..." }
5. Use localStorage for sensitive/user-specific data, pluginData for shared sync state
6. Import "framer-plugin/framer.css" for standard Framer plugin styling
7. Use <div role="button"> instead of <button> to avoid Framer's CSS overrides
8. Handle FramerPluginClosedError in catch blocks — ignore it silently
9. Call showUI in useLayoutEffect to avoid flicker when resizing
10. Always check permissions with framer.isAllowedTo() before sync operations