Agent skill

framer-plugins

Framer Plugin SDK expert. Use when building, debugging, or modifying Framer plugins. Covers ManagedCollection API, CMS sync, plugin modes, UI patterns, permissions, data storage, and common pitfalls.

View SKILL.md on GitHub Repository
Stars 121
Forks 8

Install this agent skill to your Project

npx add-skill https://github.com/fredm00n/framerlabs/tree/main/skills/framer-plugins

Metadata

Additional technical details for this skill

author
fredm00n
version
1.0.0

SKILL.md

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:

json
{
  "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

typescript
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

typescript
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)

typescript
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

typescript
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

typescript
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

typescript
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

typescript
{ 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

typescript
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"

typescript
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

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

fredm00n/framerlabs

framer-code-components-overrides

Create Framer Code Components and Code Overrides. Use when building custom React components for Framer, writing Code Overrides (HOCs) to modify canvas elements, implementing property controls, working with Framer Motion animations, handling WebGL/shaders in Framer, or debugging Framer-specific issues like hydration errors and font handling.

121 8
Explore
mattpocock/skills

obsidian-vault

Search, create, and manage notes in the Obsidian vault with wikilinks and index notes. Use when user wants to find, create, or organize notes in Obsidian.

111,310 9,758
Explore
mattpocock/skills

scaffold-exercises

Create exercise directory structures with sections, problems, solutions, and explainers that pass linting. Use when user wants to scaffold exercises, create exercise stubs, or set up a new course section.

111,310 9,758
Explore
mattpocock/skills

setup-pre-commit

Set up Husky pre-commit hooks with lint-staged (Prettier), type checking, and tests in the current repo. Use when user wants to add pre-commit hooks, set up Husky, configure lint-staged, or add commit-time formatting/typechecking/testing.

111,310 9,758
Explore
mattpocock/skills

git-guardrails-claude-code

Set up Claude Code hooks to block dangerous git commands (push, reset --hard, clean, branch -D, etc.) before they execute. Use when user wants to prevent destructive git operations, add git safety hooks, or block git push/reset in Claude Code.

111,310 9,758
Explore
mattpocock/skills

handoff

Compact the current conversation into a handoff document for another agent to pick up.

111,310 9,758
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results