Agent Skills: Framer Plugin Development Guide

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

| Mode | Purpose | framer.mode value | |------|---------|---------------------| | canvas | General-purpose canvas access | "canvas" | | configureManagedCollection | CMS: first-time setup / field config | "configureManagedCollection" | | syncManagedCollection | CMS: re-sync existing collection | "syncManagedCollection" | | image | User picks an image | "image" | | editImage | Edit existing image | "editImage" | | collection | Access user-editable collections | "collection" |

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       // Must be unique, max 64 characters
    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

| Need | Use | Why | |------|-----|-----| | API keys, auth tokens | localStorage | Per-user, no size warnings, not shared | | User preferences | localStorage | Per-user, synchronous | | Data source ID, last sync time | collection.setPluginData() | Shared across collaborators, tied to collection | | Project-level config | framer.setPluginData() | Shared, but 4kB total limit |

• 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
• marketplace.md — Marketplace submission workflow, listing requirements, review process, plugin policies, and post-publication obligations

Key Rules

1. Always check the project's CLAUDE.md for project-specific overrides and decisions
2. Before building any new feature, check marketplace.md — the plugin must comply with Framer's policies (English UI, light+dark mode, no ads, USD-only pricing, IP ownership, etc.) or it will be rejected during the ~3-week review process
3. CMS plugins should attempt silent sync in syncManagedCollection mode before showing UI
4. addItems() is upsert — no need to check for existing items before adding
5. Field data values MUST include explicit type property: { type: "string", value: "..." }
6. Use localStorage for sensitive/user-specific data, pluginData for shared sync state
7. Import "framer-plugin/framer.css" for standard Framer plugin styling
8. Use <div role="button"> instead of <button> to avoid Framer's CSS overrides
9. Handle FramerPluginClosedError in catch blocks — ignore it silently
10. Call showUI in useLayoutEffect to avoid flicker when resizing
11. Always check permissions with framer.isAllowedTo() before sync operations
12. Slugs must be unique and max 64 characters — append a unique ID suffix to title-based slugs
13. Use userEditable: true on field definitions for fields users edit manually in the CMS
14. Never include user-editable fields in fieldData during upsert — omitting them preserves user values
15. Never remove-all + re-add during sync — only remove items no longer in the source to preserve user data
16. ManagedCollection has no getItems() — you can only read item IDs, not field data