Framer CI Integration

Prerequisites

Protected CI environments, scoped credentials available only to trusted jobs, synthetic site/CMS fixtures, and a deployment owner.

Error Handling

Stop promotion on failed build, publish, domain, integration, or privacy checks; roll back the canary and preserve redacted evidence for review.

Examples

Run fixture-based tests with no secrets on a pull request, then use a protected staging job to publish a fictional canary. Block production promotion when a route, integration, or access check differs from the approved result.

Overview

Set up CI/CD for Framer plugins and Server API integrations. Plugin builds are tested with Vite + vitest. Server API CMS sync can be triggered from CI for automated content publishing.

Instructions

Step 1: GitHub Actions for Plugin Build

name: Framer Plugin CI
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20', cache: 'npm' }
      - run: npm ci
      - run: npm run build
      - run: npm test

  cms-sync:
    if: github.ref == 'refs/heads/main'
    needs: build
    runs-on: ubuntu-latest
    env:
      FRAMER_API_KEY: ${{ secrets.FRAMER_API_KEY }}
      FRAMER_SITE_ID: ${{ secrets.FRAMER_SITE_ID }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20', cache: 'npm' }
      - run: npm ci
      - name: Sync CMS and publish
        run: node scripts/sync-and-publish.js

Step 2: CMS Sync Script for CI

// scripts/sync-and-publish.ts
import { framer } from 'framer-api';

async function main() {
  const client = await framer.connect({
    apiKey: process.env.FRAMER_API_KEY!,
    siteId: process.env.FRAMER_SITE_ID!,
  });

  // Fetch content from your CMS/API
  const posts = await fetch('https://your-api.com/posts').then(r => r.json());

  // Sync to Framer CMS
  const collections = await client.getCollections();
  const blogCollection = collections.find(c => c.name === 'Blog Posts');
  if (blogCollection) {
    await blogCollection.setItems(posts.map(p => ({ fieldData: { title: p.title, body: p.content, slug: p.slug } })));
    console.log(`Synced ${posts.length} posts`);
  }

  // Publish site
  await client.publish();
  console.log('Site published');
}

main().catch(e => { console.error(e); process.exit(1); });

Step 3: Configure Secrets

gh secret set FRAMER_API_KEY --body "framer_sk_..."
gh secret set FRAMER_SITE_ID --body "abc123"

Output

• Plugin builds verified on every PR
• Aut…

Framer Common Errors

Prerequisites

An authorized site owner, an opaque incident ID, redacted diagnostics, and a safe staging reproduction path.

Instructions

Classify the issue as publishing, domain, asset, access, integration, or availability; reproduce with a staging page; apply the smallest reversible correction; verify both recovery and a safe failure response.

Output

Return a receipt with category, opaque correlation ID, action, verification, owner, and follow-up. Keep visitor data, tokens, and page content out of support evidence.

Error Handling

Pause publishing or integration changes on access, domain, or unexpected-destination failures. Use a rollback and route repeated failures to the site owner.

Examples

Break a fictional staging publish configuration, restore it, and verify the production site is untouched while the receipt contains no visitor or credential data.

Overview

Diagnostic reference for common Framer plugin, component, and Server API errors with actionable fixes.

Error Reference

Plugin Not Appearing in Editor

Cause: Dev server not running or plugin not registered.

Fix:

npm run dev  # Start Vite dev server
# Then in Framer: Plugins > Development > select your plugin

framer is not defined

Cause: Calling framer API outside the Framer editor iframe context.

Fix: The framer global from framer-plugin only works inside the editor. For server-side access, use framer-api package instead.

// Plugin (editor): import { framer } from 'framer-plugin';
// Server (headless): import { framer } from 'framer-api';

Component Renders Blank on Canvas

Cause: Runtime error in component code (swallowed by Framer).

Fix: Open Framer's browser console (right-click > Inspect) and check for errors. Common causes:

• Missing export default on component
• Undefined props without defaults
• Fetch errors from blocked CORS requests

addPropertyControls Not Showing

Cause: Called on wrong component or wrong import.

Fix:

// Must import from 'framer', not 'framer-plugin'
import { addPropertyControls, ControlType } from 'framer';

// Must be called AFTER the component definition
export default function MyComponent(props) { /* ... */ }
addPropertyControls(MyComponent, { /* ... */ });

Code Override Not Applying

Cause: Override function not returning correct shape.

…

Framer CMS Plugin — Managed Collections

Examples

Create a fictional staging collection, approve its fields and publishing audience, then publish one canary entry. Verify a duplicate sync is suppressed and an unapproved destination receives neither content nor visitor data.

Overview

Build a Framer plugin that syncs external data into CMS Managed Collections. Managed Collections are plugin-controlled — your plugin creates the schema and populates items. This is the primary integration pattern for connecting Framer to external CMSes, databases, or APIs.

Prerequisites

• Completed framer-install-auth setup
• Plugin dev server running
• Understanding of Framer CMS concepts

Instructions

Step 1: Create a Managed Collection

// src/App.tsx — CMS sync plugin
import { framer } from 'framer-plugin';
import { useState } from 'react';

framer.showUI({ width: 340, height: 400, title: 'Content Sync' });

export function App() {
  const [status, setStatus] = useState('');

  const syncCollection = async () => {
    setStatus('Fetching data...');
    const response = await fetch('https://jsonplaceholder.typicode.com/posts');
    const posts = await response.json();

    setStatus('Creating collection...');
    const collection = await framer.createManagedCollection({
      name: 'Blog Posts',
      fields: [
        { id: 'title', name: 'Title', type: 'string' },
        { id: 'body', name: 'Body', type: 'formattedText' },
        { id: 'author', name: 'Author', type: 'string' },
        { id: 'slug', name: 'Slug', type: 'slug', userEditable: false },
      ],
    });

    setStatus(`Syncing ${posts.length} items...`);
    const items = posts.slice(0, 20).map((post: any) => ({
      fieldData: {
        title: post.title,
        body: `<p>${post.body}</p>`,
        author: `User ${post.userId}`,
        slug: post.title.toLowerCase().replace(/[^a-z0-9]+/g, '-').slice(0, 50),
      },
    }));

    await collection.setItems(items);
    setStatus(`Synced ${items.length} posts`);
    framer.notify(`Synced ${items.length} blog posts`);
  };

  return (
    <div style={{ padding: 16 }}>
      <h3>Blog Post Sync</h3>
      <button onClick={syncCollection} style={{ width: '100%', padding: 8 }}>Sync Now</button>
      {status && <p style={{ marginTop: 8, fontSize: 13, color: '#666' }}>{status}</p>}
    </div>
  );
}

Step 2: Handle CMS Field Types

// Framer CMS field types reference
const fields = [
  { id: 'title', name: 'Title', type: 'string' as const },
  { id: 'content', nam…

Framer Code Components & Overrides

Examples

Build a fictional staging component with no embedded secrets or visitor data, test its publish behavior under a limited role, and verify rollback removes the canary without changing production content.

Overview

Build code components with property controls and code overrides for Framer sites. Components are custom React rendered on the canvas. Overrides modify existing layer behavior (animations, interactions) without changing the component.

Prerequisites

• Framer project open in editor
• Understanding of React and Framer Motion

Instructions

Step 1: Code Component with Property Controls

import { addPropertyControls, ControlType } from 'framer';
import { useRef, useEffect, useState } from 'react';

interface Props { target: number; duration: number; suffix: string; fontSize: number; color: string; }

export default function AnimatedCounter({ target = 1000, duration = 2, suffix = '+', fontSize = 48, color = '#000' }: Props) {
  const ref = useRef(null);
  const [count, setCount] = useState(0);
  const [started, setStarted] = useState(false);

  useEffect(() => {
    const observer = new IntersectionObserver(([e]) => { if (e.isIntersecting) setStarted(true); }, { threshold: 0.5 });
    if (ref.current) observer.observe(ref.current);
    return () => observer.disconnect();
  }, []);

  useEffect(() => {
    if (!started) return;
    const inc = target / (duration * 60);
    let val = 0;
    const timer = setInterval(() => {
      val += inc;
      if (val >= target) { setCount(target); clearInterval(timer); }
      else setCount(Math.floor(val));
    }, 1000 / 60);
    return () => clearInterval(timer);
  }, [started, target, duration]);

  return <div ref={ref} style={{ fontSize, fontWeight: 700, color, textAlign: 'center' }}>{count.toLocaleString()}{suffix}</div>;
}

addPropertyControls(AnimatedCounter, {
  target: { type: ControlType.Number, title: 'Target', defaultValue: 1000 },
  duration: { type: ControlType.Number, title: 'Duration (s)', defaultValue: 2 },
  suffix: { type: ControlType.String, title: 'Suffix', defaultValue: '+' },
  fontSize: { type: ControlType.Number, title: 'Font Size', defaultValue: 48 },
  color: { type: ControlType.Color, title: 'Color', defaultValue: '#000' },
});

Step 2: Data-Fetching Component

import { addPropertyControls, ControlType } from 'framer';
import { useEffect, useState } from 'react';

export default function DataList({ apiUrl = 'https://jsonplaceholder.typicode.com/posts', limit = 5 }) {
  const [items, setItems] = useState<any[]>([]);
  useEffect(() => {
    fetch(apiUrl).then(r => r.json()).then(d => setItems(d…

Framer Cost Tuning

Prerequisites

Current plan/billing information, aggregate usage, a cost owner, required availability/features, and a staging site for changes.

Instructions

Measure aggregate usage, evaluate plan or asset changes against current terms, obtain owner approval, and test any performance/publishing effect before production.

Output

Record the measurement period, approved change, expected effect, owner, verification date, and rollback state. Do not include visitor data or billing credentials.

Error Handling

Revert changes that reduce required publishing, domain, privacy, or performance behavior; quarantine unexpected usage or access changes for review.

Examples

Test an asset optimization on a fictional staging page, compare aggregate performance, and promote only after the site owner approves the evidence.

Overview

Optimize Framer costs across plans and features. The Server API is free during beta. Main costs are Framer site plans, custom domains, and team seats.

Framer Plans

Cost Optimization Strategies

Step 1: CMS Item Budgeting

// Track CMS item usage to avoid plan overages
async function checkCMSUsage(client: any) {
  const collections = await client.getCollections();
  let totalItems = 0;
  for (const col of collections) {
    const items = await col.getItems();
    totalItems += items.length;
    console.log(`${col.name}: ${items.length} items`);
  }
  console.log(`Total CMS items: ${totalItems}`);
  // Pro plan: 10,000 limit
  console.log(`Usage: ${((totalItems / 10000) * 100).toFixed(1)}% of Pro limit`);
}

Step 2: Minimize Publish Frequency

// Batch CMS updates before publishing (each publish rebuilds the site)
async function batchUpdateAndPublish(updates: Array<{ collection: string; items: any[] }>) {
  const client = await getClient();
  for (const update of updates) {
    const col = (await client.getCollections()).find(c => c.name === update.collection);
    if (col) await col.setItems(update.items);
  }
  // Single publish after all updates
  await client.publish();
}

Step 3: Development vs Production Sites

Use a free plan site for development and testing. Only pay for the production site.

Resources

Framer Debug Bundle

Prerequisites

An incident owner, secure evidence location, retention date, redaction rules for tokens and visitor data, and an opaque correlation ID.

Error Handling

Stop collection if a credential, customer submission, or private page content is found; rotate the affected credential if necessary and preserve only approved evidence.

Examples

Collect a synthetic staging publish failure using release/version data and an opaque ID, review the bundle for secrets and form submissions, then restrict it to the incident owner and retire it at the retention date.

Overview

Collect diagnostic information for Framer plugin or Server API issues including package versions, API connectivity, and configuration.

Instructions

Step 1: Create Debug Bundle

#!/bin/bash
BUNDLE="framer-debug-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BUNDLE"

echo "=== Framer Debug Bundle ===" | tee "$BUNDLE/summary.txt"
echo "Date: $(date -u)" >> "$BUNDLE/summary.txt"

# Runtime
echo "--- Runtime ---" >> "$BUNDLE/summary.txt"
node --version >> "$BUNDLE/summary.txt" 2>&1
npm --version >> "$BUNDLE/summary.txt" 2>&1

# Packages
echo "--- Packages ---" >> "$BUNDLE/summary.txt"
npm list framer-plugin framer-api framer 2>/dev/null >> "$BUNDLE/summary.txt"

# Credentials (presence only)
echo "--- Config ---" >> "$BUNDLE/summary.txt"
echo "FRAMER_API_KEY: ${FRAMER_API_KEY:+[SET]}" >> "$BUNDLE/summary.txt"
echo "FRAMER_SITE_ID: ${FRAMER_SITE_ID:+[SET]}" >> "$BUNDLE/summary.txt"

# API connectivity
echo "--- API Test ---" >> "$BUNDLE/summary.txt"
curl -s -o /dev/null -w "Framer API: HTTP %{http_code}\n" https://api.framer.com/health >> "$BUNDLE/summary.txt" 2>&1

# Vite config
cp vite.config.ts "$BUNDLE/" 2>/dev/null
cp tsconfig.json "$BUNDLE/" 2>/dev/null
cp package.json "$BUNDLE/" 2>/dev/null

# Bundle
tar -czf "$BUNDLE.tar.gz" "$BUNDLE"
echo "Bundle: $BUNDLE.tar.gz"

Output

• summary.txt with runtime, packages, connectivity
• Configuration files (non-sensitive)
• Compressed archive for support

Resources

• Framer Support
• Framer Changelog

Next Steps

For rate limit issues, see framer-rate-limits.

Framer Deploy Integration

Prerequisites

A deployment owner, scoped integration credential, approved destination/domain policy, staging canary, and rollback operator.

Error Handling

Stop deployment on publishing, domain, access, integration, or privacy failures; restore the previous configuration and keep evidence redacted.

Examples

Deploy a fictional staging site, simulate a failed health/publish check, and verify production is unchanged after rollback.

Overview

Deploy Framer Server API integrations (CMS sync services, webhook handlers) to cloud platforms. Framer sites themselves are hosted by Framer — this covers deploying your backend services that interact with Framer.

Instructions

Step 1: Vercel Serverless (CMS Sync API)

// api/sync-framer.ts — Vercel serverless function
import type { VercelRequest, VercelResponse } from '@vercel/node';
import { framer } from 'framer-api';

export default async function handler(req: VercelRequest, res: VercelResponse) {
  if (req.method !== 'POST') return res.status(405).end();

  const client = await framer.connect({
    apiKey: process.env.FRAMER_API_KEY!,
    siteId: process.env.FRAMER_SITE_ID!,
  });

  const { items, collectionName } = req.body;
  const collections = await client.getCollections();
  const col = collections.find(c => c.name === collectionName);
  if (!col) return res.status(404).json({ error: 'Collection not found' });

  await col.setItems(items);
  await client.publish();
  res.json({ synced: items.length, published: true });
}

vercel env add FRAMER_API_KEY production
vercel env add FRAMER_SITE_ID production
vercel --prod

Step 2: Fly.io (Long-Running Sync Service)

fly secrets set FRAMER_API_KEY=framer_sk_...
fly secrets set FRAMER_SITE_ID=abc123
fly deploy

Step 3: Webhook Receiver for Content Updates

// api/webhook-handler.ts — receive webhooks from your CMS, sync to Framer
export default async function handler(req, res) {
  const { event, data } = req.body;
  if (event === 'content.published') {
    const client = await framer.connect({ apiKey: process.env.FRAMER_API_KEY!, siteId: process.env.FRAMER_SITE_ID! });
    // Sync updated content to Framer CMS
    const col = (await client.getCollections()).find(c => c.name === 'Blog Posts');
    if (col) await col.setItems([{ fieldData: data }]);
    await client.publish();
  }
  res.json({ ok: true });
}

Output

• Serverless CMS sync endpoint
• Webhook handler for content update automation
• Platform secrets configured

Resources

• Framer Server API
• …

Framer Hello World

Examples

Create a disposable staging page with fictional content, publish it only to the approved test domain, verify no credential or visitor data appears in output, then remove the test artifact through the approved process.

Overview

Build a minimal Framer plugin that inserts a styled text layer onto the canvas, and a code component that renders inside Framer sites. Both use the framer-plugin SDK which provides the framer global for editor interaction.

Prerequisites

• Completed framer-install-auth setup
• Framer editor open with a project
• Plugin dev server running (npm run dev)

Instructions

Step 1: Hello World Plugin

// src/App.tsx — Plugin UI that runs inside Framer editor
import { framer } from 'framer-plugin';

framer.showUI({ width: 300, height: 200, title: 'Hello World Plugin' });

export function App() {
  const insertText = async () => {
    await framer.addText('Hello from my plugin!', {
      position: { x: 100, y: 100 },
      style: { fontSize: 24, color: '#333' },
    });
    framer.notify('Text inserted on canvas!');
  };

  const insertImage = async () => {
    await framer.addImage({
      url: 'https://picsum.photos/400/300',
      position: { x: 100, y: 200 },
    });
  };

  return (
    <div style={{ padding: 16, display: 'flex', flexDirection: 'column', gap: 8 }}>
      <h2>Hello World</h2>
      <button onClick={insertText}>Insert Text</button>
      <button onClick={insertImage}>Insert Image</button>
    </div>
  );
}

Step 2: Hello World Code Component

// Code component — renders inside Framer sites (not a plugin)
// Create via: Framer editor > Assets > Code > New Component
import { addPropertyControls, ControlType } from 'framer';

interface Props {
  text: string;
  color: string;
}

export default function HelloComponent({ text, color }: Props) {
  return (
    <div style={{
      display: 'flex',
      alignItems: 'center',
      justifyContent: 'center',
      height: '100%',
      fontSize: 24,
      fontWeight: 600,
      color,
      background: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
      borderRadius: 12,
      padding: 20,
    }}>
      {text}
    </div>
  );
}

addPropertyControls(HelloComponent, {
  text: { type: ControlType.String, title: 'Text', defaultValue: 'Hello Framer!' },
  color: { type: ControlType.Color, title: 'Color', defaultValue: '#ffffff' },
});

Step 3: Hello World Code Override

// Code override — modifies existing layer behavior
// Create via: Framer edi…

Framer Install & Auth

Examples

Use a scoped staging credential to confirm a read-only project check, record only the scope and redacted outcome, then revoke the test credential and verify access is denied.

Overview

Set up the Framer Plugin SDK for building editor plugins, or the framer-api package for Server API access. Framer has two developer surfaces: Plugins (run inside the Framer editor UI) and Server API (run from any Node.js server via WebSocket).

Prerequisites

• Node.js 18+
• Framer account (free or paid)
• For Server API: API key from site settings

Instructions

Step 1: Choose Your Integration Type

Step 2: Set Up a Framer Plugin

# Scaffold a new plugin project
npx create-framer-plugin@latest my-plugin
cd my-plugin
npm install
npm run dev

This creates a Vite + React project with the framer-plugin package pre-configured. The plugin runs inside Framer's editor iframe.

Step 3: Set Up the Server API (Headless Access)

npm install framer-api

// server.ts — Server API connection
import { framer } from 'framer-api';

const client = await framer.connect({
  apiKey: process.env.FRAMER_API_KEY!, // From site settings
  siteId: process.env.FRAMER_SITE_ID!,
});

// List all CMS collections
const collections = await client.getCollections();
console.log('Collections:', collections.map(c => c.name));

Step 4: Configure Environment Variables

# .env (NEVER commit)
FRAMER_API_KEY=framer_sk_abc123...
FRAMER_SITE_ID=abc123def456

# .gitignore
.env
.env.local

Step 5: Verify Plugin Connection

Open Framer, go to your project, click Plugins > Development > select your local plugin. The dev server hot-reloads into the editor.

// Plugin verification — runs inside Framer editor
import { framer } from 'framer-plugin';

export function App() {
  const handleTest = async () => {
    const selection = await framer.getSelection();
    console.log('Selected layers:', selection.length);
    framer.notify(`Found ${selection.length} selected layers`);
  };

  return <button onC…

Framer Local Dev Loop

Examples

Use fictional pages, CMS records, and form submissions in local tests. Confirm the workflow runs without production credentials, redacts logs, and removes temporary artifacts after the staging validation is complete.

Overview

Set up a fast development workflow for Framer plugins and code components with Vite hot-reload, TypeScript, and testing.

Prerequisites

• Completed framer-install-auth setup
• Node.js 18+ with npm
• Framer editor open

Instructions

Step 1: Plugin Dev Environment

npx create-framer-plugin@latest my-plugin
cd my-plugin
npm install
npm run dev  # Starts Vite dev server — hot-reloads into Framer editor

Project structure:

my-plugin/
├── src/
│   ├── App.tsx           # Plugin UI (React)
│   ├── main.tsx          # Entry point
│   └── framer.d.ts       # Type definitions
├── package.json
├── vite.config.ts        # Vite config with framer-plugin
└── tsconfig.json

Step 2: Connect to Framer Editor

1. Open Framer, go to your project
2. Click Plugins > Development in the toolbar
3. Select your local dev plugin
4. Changes in src/App.tsx hot-reload instantly

Step 3: Testing Plugin Logic

// tests/sync.test.ts — test data transformation outside Framer
import { describe, it, expect } from 'vitest';

// Extract pure functions for testability
function transformPosts(posts: any[]) {
  return posts.map(p => ({
    fieldData: {
      title: p.title,
      body: `<p>${p.body}</p>`,
      slug: p.title.toLowerCase().replace(/[^a-z0-9]+/g, '-').slice(0, 50),
    },
  }));
}

describe('CMS Sync', () => {
  it('should transform posts into CMS items', () => {
    const posts = [{ title: 'Hello World', body: 'Content here', userId: 1 }];
    const items = transformPosts(posts);
    expect(items[0].fieldData.title).toBe('Hello World');
    expect(items[0].fieldData.slug).toBe('hello-world');
    expect(items[0].fieldData.body).toContain('<p>');
  });

  it('should handle slugs with special characters', () => {
    const posts = [{ title: 'What\'s New in 2025?', body: 'test', userId: 1 }];
    const items = transformPosts(posts);
    expect(items[0].fieldData.slug).toBe('what-s-new-in-2025-');
  });
});

Step 4: Code Component Development

# Code components are edited directly in Framer editor
# For local development of shared component libraries:
mkdir framer-components && cd framer-components
npm init -y
npm install react framer typescript @types/react

// …

Framer Performance Tuning

Prerequisites

A staging site, aggregate performance baseline, approved content/assets, a change owner, and rollback path.

Error Handling

Revert changes that harm accessibility, publishing, privacy, or agreed performance thresholds; retain only redacted telemetry for review.

Examples

Optimize a fictional staging page, compare aggregate performance metrics, and roll back if a synthetic form or route check regresses.

Overview

Optimize Framer plugin, component, and Server API performance. Key areas: CMS sync speed, component render performance, and plugin responsiveness.

Instructions

Step 1: Batch CMS Operations

// Process large collections in batches to avoid timeouts
async function batchSync(collection: any, items: any[], batchSize = 50) {
  const total = items.length;
  for (let i = 0; i < total; i += batchSize) {
    await collection.setItems(items.slice(i, i + batchSize));
    const progress = Math.min(i + batchSize, total);
    framer.notify(`Synced ${progress}/${total}`);
  }
}

Step 2: Optimize Code Component Rendering

import { memo, useMemo } from 'react';

// Memoize expensive components
export default memo(function DataGrid({ data, columns }) {
  const processedData = useMemo(() =>
    data.map(row => columns.reduce((acc, col) => ({ ...acc, [col.key]: row[col.key] }), {})),
    [data, columns]
  );

  return (
    <div style={{ display: 'grid', gridTemplateColumns: `repeat(${columns.length}, 1fr)` }}>
      {processedData.map((row, i) => columns.map(col => (
        <div key={`${i}-${col.key}`} style={{ padding: 8 }}>{row[col.key]}</div>
      )))}
    </div>
  );
});

Step 3: Persistent WebSocket Connection

// Reuse Server API connection instead of reconnecting each time
let clientInstance: any = null;

async function getClient() {
  if (!clientInstance) {
    const { framer } = await import('framer-api');
    clientInstance = await framer.connect({
      apiKey: process.env.FRAMER_API_KEY!,
      siteId: process.env.FRAMER_SITE_ID!,
    });
  }
  return clientInstance;
}

Step 4: Image Optimization

// Pre-optimize image URLs before syncing to CMS
function optimizeImageUrl(url: string, width = 800): string {
  // Use image CDN if available
  if (url.includes('cloudinary.com')) {
    return url.replace('/upload/', `/upload/w_${width},q_auto,f_auto/`);
  }
  if (url.includes('imgix.net')) {
    return `${url}?w=${width}&auto=format,compress`;
  }
  return url;
}

Output

• Batched CMS operations avoiding timeouts
• Memoized components for render performance
• Persistent WebSocket connec…

Framer Production Checklist

Prerequisites

A launch owner, approver, staging evidence with fictional content, domain/DNS owner, access policy, and rollback operator.

Instructions

Attach evidence or an owner decision to every control, validate publishing/domain/integration/privacy behavior in a canary, observe aggregate health, and stop promotion on threshold or access failures.

Error Handling

Pause publishing on domain, access, visitor-data, or integration failures; restore the prior configuration and verify the rollback before resolving the incident.

Examples

Publish a fictional staging page, revoke a test collaborator, and simulate a failed domain check. Promote only after the owner records that access and rollback behaved as expected.

Overview

Checklist for deploying Framer plugins, code components, and Server API integrations to production.

Checklist

Plugin Production

• [ ] Plugin tested in Framer editor with real data
• [ ] No console.log calls remaining
• [ ] Error states handled (network failures, API errors)
• [ ] Loading states shown during async operations
• [ ] Plugin UI responsive at configured width/height
• [ ] All property controls have default values

Code Components

• [ ] export default on all components
• [ ] addPropertyControls on all components
• [ ] Responsive at all viewport sizes
• [ ] No hardcoded data (use property controls or CMS)
• [ ] Error boundaries for data-fetching components
• [ ] Performance tested with large datasets

Server API (CMS Sync)

• [ ] API key in secrets vault (not .env)
• [ ] CMS collection schema matches source data
• [ ] Incremental sync (not full replace every run)
• [ ] Error handling with notifications
• [ ] Publish step tested
• [ ] Rate limiting for batch operations

Site Publishing

• [ ] Custom domain configured
• [ ] SEO meta tags on all pages
• [ ] CMS collections populated
• [ ] Code components rendering correctly in preview
• [ ] Code overrides working in published site

Output

• Verified plugin, components, and CMS sync
• Production API key secured
• Site published and accessible

Resources

• Framer Publishing
• Custom Domains

Next Steps

For version upgrades, see framer-upgrade-migration.

Framer Rate Limits

Prerequisites

Confirmed provider limits, bounded concurrency/retry policy, approved integration owner, and synthetic staging requests.

Output

Record policy version, aggregate throttles, retry/queue outcome, owner, and manual disposition without visitor data or credentials.

Examples

Simulate a throttled staging request, honor the retry bound under an opaque operation ID, and route repeated failures to review instead of replaying publish actions.

Overview

Handle Framer API rate limits for Server API and plugin operations. The Server API uses WebSocket, so rate limits apply per-connection. CMS operations are limited by collection size and concurrent writes.

Rate Limit Reference

Instructions

Step 1: Batch CMS Writes

async function batchSetItems(collection: any, items: any[], batchSize = 100) {
  for (let i = 0; i < items.length; i += batchSize) {
    const batch = items.slice(i, i + batchSize);
    await collection.setItems(batch);
    console.log(`Synced ${Math.min(i + batchSize, items.length)}/${items.length}`);
    if (i + batchSize < items.length) {
      await new Promise(r => setTimeout(r, 1000)); // 1s between batches
    }
  }
}

Step 2: Debounced Plugin Operations

// Debounce rapid plugin UI interactions
function debounce<T extends (...args: any[]) => any>(fn: T, ms = 300) {
  let timer: NodeJS.Timeout;
  return (...args: Parameters<T>) => {
    clearTimeout(timer);
    timer = setTimeout(() => fn(...args), ms);
  };
}

const debouncedSync = debounce(async () => {
  await syncCollection();
}, 500);

Step 3: Retry for Server API

async function withRetry<T>(fn: () => Promise<T>, maxRetries = 3): Promise<T> {
  for (let i = 0; i <= maxRetries; i++) {
    try {
      return await fn();
    } catch (err: any) {
      if (i === maxRetries) throw err;
      const delay = 1000 * Math.pow(2, i);
      console.log(`Retry ${i + 1} in ${delay}ms`);
      await new Promise(r => setTimeout(r, delay));
    }
  }
  throw new Error('Unreachable');
}

Error Handling

Framer Reference Architecture

Prerequisites

Documented site owners, publishing/domain access policy, approved integrations, visitor-data boundaries, synthetic staging site, and rollback owner.

Instructions

Separate editing, publishing, domain/DNS, forms, analytics, and downstream integrations by least privilege. Validate changes in staging, use redacted telemetry, promote a canary, and retain a tested rollback path.

Output

Maintain an architecture record with trust boundaries, approved destinations, access/retention controls, owners, canary result, and rollback mechanism. Exclude credentials and visitor submissions.

Error Handling

Quarantine unknown integration destinations and stop publishing on domain, access, or privacy-policy failures. Restore the prior configuration before retrying.

Examples

Publish a fictional staging page, deny an unapproved analytics consumer, and verify rollback restores the prior site without leaking form data.

Overview

Production architecture for Framer integrations covering plugins, Server API CMS sync, code components, and automated publishing pipelines.

Architecture Diagram

┌─────────────────────────────────────────────┐
│               Framer Editor                  │
│  ┌──────────┐  ┌───────────┐  ┌──────────┐ │
│  │ Plugins  │  │ Code      │  │ Code     │ │
│  │ (iframe) │  │ Components│  │ Overrides│ │
│  └────┬─────┘  └───────────┘  └──────────┘ │
│       │ framer-plugin SDK                    │
├───────┴──────────────────────────────────────┤
│             Framer CMS                       │
│  ┌──────────────┐  ┌───────────────────┐    │
│  │ Managed      │  │ Unmanaged         │    │
│  │ Collections  │  │ Collections       │    │
│  └──────┬───────┘  └───────────────────┘    │
├─────────┴────────────────────────────────────┤
│         Server API (WebSocket)               │
│  framer-api package                          │
└─────────┬────────────────────────────────────┘
          │
┌─────────┴────────────────────────────────────┐
│         Your Backend                          │
│  ┌────────────┐  ┌──────────┐  ┌──────────┐ │
│  │ CMS Sync   │  │ Webhook  │  │ CI/CD    │ │
│  │ Service    │  │ Handler  │  │ Pipeline │ │
│  └────────────┘  └──────────┘  └──────────┘ │
└──────────────────────────────────────────────┘

Project Structure

framer-integration/
├── plugin/                    # Framer editor plugin
│   ├── src/
│   │   ├── App.tsx           # Plugin UI
│   │   ├── hooks/            # Plugin state hooks
│   │   └── cms/              # CMS sync logic
│   ├── vite.config.ts
│   └── package.json
├── server/                    # Server API backend
│   ├── src/
│   │   ├── sync.ts           # CMS sync service
│   │   ├── publish.ts        # Auto-publish logic
│   │   └── webhooks.ts       # External webhook handlers
│   └── package.jso…

Framer SDK Patterns

Examples

Use a scoped staging integration and fictional CMS data to validate schema and idempotency. Reject an unexpected destination before publishing and record only opaque IDs and aggregate results.

Overview

Production-ready patterns for Framer plugins, Server API, code components, and CMS integrations. Covers plugin architecture, type-safe CMS operations, and reusable component patterns.

Prerequisites

• Completed framer-install-auth setup
• Familiarity with React and TypeScript

Instructions

Step 1: Type-Safe CMS Operations

// src/cms/types.ts — type-safe field definitions
interface BlogPost {
  title: string;
  body: string;
  author: string;
  publishDate: string;
  featured: boolean;
  slug: string;
}

const BLOG_FIELDS = [
  { id: 'title' as const, name: 'Title', type: 'string' as const },
  { id: 'body' as const, name: 'Body', type: 'formattedText' as const },
  { id: 'author' as const, name: 'Author', type: 'string' as const },
  { id: 'publishDate' as const, name: 'Published', type: 'date' as const },
  { id: 'featured' as const, name: 'Featured', type: 'boolean' as const },
  { id: 'slug' as const, name: 'Slug', type: 'slug' as const, userEditable: false },
] as const;

function toBlogItem(post: BlogPost) {
  return { fieldData: { ...post } };
}

Step 2: Plugin State Management

// src/hooks/usePluginState.ts
import { useState, useCallback } from 'react';
import { framer } from 'framer-plugin';

type SyncStatus = 'idle' | 'fetching' | 'syncing' | 'success' | 'error';

export function useSyncState() {
  const [status, setStatus] = useState<SyncStatus>('idle');
  const [error, setError] = useState<string | null>(null);
  const [count, setCount] = useState(0);

  const sync = useCallback(async (fn: () => Promise<number>) => {
    setStatus('syncing');
    setError(null);
    try {
      const synced = await fn();
      setCount(synced);
      setStatus('success');
      framer.notify(`Synced ${synced} items`);
    } catch (err: any) {
      setError(err.message);
      setStatus('error');
      framer.notify(`Sync failed: ${err.message}`);
    }
  }, []);

  return { status, error, count, sync };
}

Step 3: Reusable Component Patterns

// Responsive container pattern
import { addPropertyControls, ControlType } from 'framer';

export default function ResponsiveCard({ title, description, imageUrl, ctaText, ctaUrl }) {
  return (
    <div style={{ display: 'flex', flexDirection: 'column', borderR…

Framer Security Basics

Prerequisites

A security owner, least-privilege access policy, secret-manager references, domain/DNS ownership, and synthetic test project.

Output

Maintain a security receipt with identity scope, control result, access-review date, owner, and redacted incident state. Do not include keys, form submissions, or private content.

Error Handling

Deny unexpected permissions or publishing destinations, revoke access on suspected exposure, and route incidents through the designated owner.

Examples

Use a staging site to verify a temporary collaborator cannot publish to production, remove access, and record only the control outcome and opaque project reference.

Overview

Security best practices for Framer API keys, plugin development, and Server API access.

Instructions

Step 1: Credential Management

# .env (never commit)
FRAMER_API_KEY=framer_sk_abc123...
FRAMER_SITE_ID=abc123

# .gitignore
.env
.env.local

Step 2: Plugin Security

// Plugins run in Framer's iframe sandbox — limited browser APIs
// Never store secrets in plugin code (it's client-side)

// Fetch external data through your own API proxy
const data = await fetch('https://your-api.com/framer-data', {
  headers: { 'Authorization': `Bearer ${sessionToken}` },
});

Step 3: Server API Key Rotation

# 1. Generate new key in Framer site settings
# 2. Update in secrets vault
# 3. Test connection
node -e "
  const { framer } = require('framer-api');
  framer.connect({ apiKey: process.env.FRAMER_API_KEY, siteId: process.env.FRAMER_SITE_ID })
    .then(() => console.log('OK'))
    .catch(e => console.error('FAIL', e.message));
"
# 4. Revoke old key in site settings

Step 4: Security Checklist

• [ ] API keys in environment variables, never in code
• [ ] .env in .gitignore
• [ ] Plugin never stores or exposes API keys
• [ ] Server API accessed only from backend, never client
• [ ] Pre-commit hook scans for framer_sk_* leaks
• [ ] HTTPS-only for all API communication

Resources

• Framer Server API
• Plugin Security

Next Steps

Framer Upgrade & Migration

Prerequisites

Current release information, an inventory of site components, domains, integrations, and redirects, plus a staging site and rollback owner.

Output

Record versions/components reviewed, staging and canary outcome, redirect/integration checks, approver, and rollback state without copying visitor or credential data.

Error Handling

Stop promotion on routing, publishing, access, integration, or privacy mismatches; restore the prior version and review opaque failures before retrying.

Examples

Migrate a fictional staging page, compare published routes and a synthetic form flow, and roll back when a redirect or integration fails.

Overview

Guide for upgrading Framer plugin SDK, Server API, and migrating between Framer platform versions. Check the Framer Developer Changelog for breaking changes before upgrading.

Instructions

Step 1: Check Current Versions

npm list framer-plugin framer-api framer
npm view framer-plugin version
npm view framer-api version

Step 2: Review Changelog

Visit https://www.framer.com/developers/changelog for breaking changes.

Key migrations:

• Plugin API 3.x: Introduced Managed Collections, Code File APIs
• Server API beta: WebSocket-based programmatic access
• Code Components v2: Updated property control types

Step 3: Upgrade Plugin SDK

git checkout -b upgrade/framer-plugin
npm install framer-plugin@latest
npm run build  # Check for type errors
npm test       # Run tests

Step 4: Common Migration Patterns

// Plugin API 2.x → 3.x: Collection APIs changed
// BEFORE: framer.createCollection(...)
// AFTER: framer.createManagedCollection(...)

// Code components: ControlType changes
// BEFORE: ControlType.FusedNumber
// AFTER: ControlType.Number (with min/max/step)

// Overrides: import path
// BEFORE: import { Override } from 'framer'
// AFTER: import { Override } from 'framer' (unchanged, but check type shape)

Step 5: Rollback

# Pin to previous version
npm install framer-plugin@3.x.x --save-exact

Resources

• Framer Changelog
• Framer Upgrading Guide

Next Steps

For CI integration, see framer-ci-integration.

Framer Webhooks & Events

Prerequisites

Approved event source/destinations, signing or authentication controls where supported, event ledger, redaction policy, and synthetic fixtures.

Error Handling

Reject unknown event schemas/destinations, deduplicate replayed events, bound retries, and pause downstream actions on access or privacy failures.

Examples

Deliver a fictional event twice, process it once under an opaque ID, and reject an unknown destination without forwarding page or visitor data.

Overview

Framer's Server API uses a WebSocket channel for real-time communication, not traditional REST webhooks. For event-driven integrations, you subscribe to changes via the WebSocket connection or set up your own webhook endpoints that trigger Framer sync via the Server API.

Instructions

Step 1: Subscribe to CMS Changes via Server API

import { framer } from 'framer-api';

async function watchChanges() {
  const client = await framer.connect({
    apiKey: process.env.FRAMER_API_KEY!,
    siteId: process.env.FRAMER_SITE_ID!,
  });

  // Subscribe to collection changes
  const collections = await client.getCollections();
  for (const col of collections) {
    col.subscribe((items) => {
      console.log(`Collection "${col.name}" updated: ${items.length} items`);
    });
  }
}

Step 2: External Webhook → Framer Sync

// Receive webhook from your CMS, sync to Framer
import express from 'express';
import { framer } from 'framer-api';

const app = express();
app.use(express.json());

app.post('/webhooks/cms-update', async (req, res) => {
  const { event, data } = req.body;

  // Validate webhook source
  const signature = req.headers['x-webhook-signature'];
  if (!verifySignature(req.body, signature as string)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  if (event === 'content.updated') {
    const client = await framer.connect({
      apiKey: process.env.FRAMER_API_KEY!,
      siteId: process.env.FRAMER_SITE_ID!,
    });

    const col = (await client.getCollections()).find(c => c.name === data.collection);
    if (col) {
      await col.setItems(data.items.map(i => ({ fieldData: i })));
      await client.publish();
      console.log(`Synced ${data.items.length} items and published`);
    }
  }

  res.json({ received: true });
});

Step 3: Plugin Event Subscriptions

// Inside a Framer plugin — subscribe to canvas changes
import { framer } from 'framer-plugin';

// Watch for selection changes
framer.subscribeToSelection((selection) => {
  console.log('Selection changed:', selection.length, 'layers');
});

// Watch for code file changes
framer.subscribeToCodeFiles((codeFiles) =…