cursorrules

Framer Plugin Development Rules

Project Overview

This is a Framer plugin starter kit using React, TypeScript, Vite, and Tailwind CSS.

Tech Stack

• Framework: React 18 with TypeScript
• Build Tool: Vite 6
• Styling: Tailwind CSS v3
• Plugin SDK: framer-plugin v3
• Dev Server: HTTPS via vite-plugin-mkcert (required for Framer)

Important Configuration Notes

PostCSS & Tailwind Setup

• Use postcss.config.js and tailwind.config.js with ES module syntax (export default)
• These work with "type": "module" in package.json
• Always import CSS at the main entry point (src/main.tsx), not in components
• Port 5173 must be available - kill any conflicting processes before starting dev server

Development Server

• Run: npm run dev
• Server MUST run on port 5173 (default Vite port) with HTTPS
• If port is in use, kill the process: lsof -ti:5173 | xargs kill -9
• Clear Vite cache if issues: rm -rf node_modules/.vite

Framer Plugin API

Core API (framer object)

UI Configuration

import { framer } from "framer-plugin"

// Show plugin UI (call this at the top level, not in a component)
framer.showUI({
    position: "top right" | "top left" | "bottom right" | "bottom left" | "center",
    width: number,
    height: number,
    resizable?: boolean,
    minWidth?: number,
    minHeight?: number,
    maxWidth?: number,
    maxHeight?: number,
})

// Hide the plugin UI
framer.hideUI()

Selection Management

import { CanvasNode } from "framer-plugin"

// Subscribe to selection changes (returns cleanup function)
const unsubscribe = framer.subscribeToSelection((selection: CanvasNode[]) => {
    console.log("Selection changed:", selection)
})

// Get current selection once
const selection = await framer.getSelection()

Canvas Manipulation

// Add SVG to canvas
await framer.addSVG({
    svg: string,           // SVG markup
    name?: string,         // Layer name in Framer
    x?: number,            // Position
    y?: number,
    width?: number,        // Dimensions
    height?: number,
    fill?: string,         // Override fill color
})

// Add image to canvas
await framer.addImage({
    image: string | Uint8Array,  // Data URL or binary data
    name?: string,
    x?: number,
    y?: number,
    width?: number,
    height?: number,
})

// Add component instance
await framer.addComponentInstance({
    url: string,           // Component URL
    name?: string,
    attributes?: Record<string, any>,
    x?: number,
    y?: number,
})

// Clone nodes
await framer.cloneNode(node: CanvasNode)