Figma Performance Tuning

Overview

Optimize Figma API performance with caching, batching, and connection pooling.

Prerequisites

• Figma SDK installed
• Understanding of async patterns
• Redis or in-memory cache available (optional)
• Performance monitoring in place

Latency Benchmarks

Caching Strategy

Response Caching

import { LRUCache } from 'lru-cache';

const cache = new LRUCache<string, any>({
  max: 1000,
  ttl: 60000, // 1 minute
  updateAgeOnGet: true,
});

async function cachedFigmaRequest<T>(
  key: string,
  fetcher: () => Promise<T>,
  ttl?: number
): Promise<T> {
  const cached = cache.get(key);
  if (cached) return cached as T;

  const result = await fetcher();
  cache.set(key, result, { ttl });
  return result;
}

Redis Caching (Distributed)

import Redis from 'ioredis';

const redis = new Redis(process.env.REDIS_URL);

async function cachedWithRedis<T>(
  key: string,
  fetcher: () => Promise<T>,
  ttlSeconds = 60
): Promise<T> {
  const cached = await redis.get(key);
  if (cached) return JSON.parse(cached);

  const result = await fetcher();
  await redis.setex(key, ttlSeconds, JSON.stringify(result));
  return result;
}

Request Batching

import DataLoader from 'dataloader';

const figmaLoader = new DataLoader<string, any>(
  async (ids) => {
    // Batch fetch from Figma
    const results = await figmaClient.batchGet(ids);
    return ids.map(id => results.find(r => r.id === id) || null);
  },
  {
    maxBatchSize: 100,
    batchScheduleFn: callback => setTimeout(callback, 10),
  }
);

// Usage - automatically batched
const [item1, item2, item3] = await Promise.all([
  figmaLoader.load('id-1'),
  figmaLoader.load('id-2'),
  figmaLoader.load('id-3'),
]);

Connection Optimization

import { Agent } from 'https';

// Keep-alive connection pooling
const agent = new Agent({
  keepAlive: true,
  maxSockets: 10,
  maxFreeSockets: 5,
  timeout: 30000,
});

const client = new FigmaClient({
  apiKey: process.env.FIGMA_API_KEY!,
  httpAgent: agent,
});

Pagination Optimization

async function* paginatedFigmaList<T>(
  fetcher: (cursor?: string) => Promise<{ data: T[]; nextCursor?: string }>
): AsyncGenerator<T> {
  let cursor: strin

Figma Policy & Guardrails

Overview

Automated policy enforcement and guardrails for Figma integrations.

Prerequisites

• ESLint configured in project
• Pre-commit hooks infrastructure
• CI/CD pipeline with policy checks
• TypeScript for type enforcement

ESLint Rules

Custom Figma Plugin

// eslint-plugin-figma/rules/no-hardcoded-keys.js
module.exports = {
  meta: {
    type: 'problem',
    docs: {
      description: 'Disallow hardcoded Figma API keys',
    },
    fixable: 'code',
  },
  create(context) {
    return {
      Literal(node) {
        if (typeof node.value === 'string') {
          if (node.value.match(/^sk_(live|test)_[a-zA-Z0-9]{24,}/)) {
            context.report({
              node,
              message: 'Hardcoded Figma API key detected',
            });
          }
        }
      },
    };
  },
};

ESLint Configuration

// .eslintrc.js
module.exports = {
  plugins: ['figma'],
  rules: {
    'figma/no-hardcoded-keys': 'error',
    'figma/require-error-handling': 'warn',
    'figma/use-typed-client': 'warn',
  },
};

Pre-Commit Hooks

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: figma-secrets-check
        name: Check for Figma secrets
        entry: bash -c 'git diff --cached --name-only | xargs grep -l "sk_live_" && exit 1 || exit 0'
        language: system
        pass_filenames: false

      - id: figma-config-validate
        name: Validate Figma configuration
        entry: node scripts/validate-figma-config.js
        language: node
        files: '\.figma\.json$'

TypeScript Strict Patterns

// Enforce typed configuration
interface FigmaStrictConfig {
  apiKey: string;  // Required
  environment: 'development' | 'staging' | 'production';  // Enum
  timeout: number;  // Required number, not optional
  retries: number;
}

// Disallow any in Figma code
// @ts-expect-error - Using any is forbidden
const client = new Client({ apiKey: any });

// Prefer this
const client = new FigmaClient(config satisfies FigmaStrictConfig);

Architecture Decision Records

ADR Template

# ADR-001: Figma Client Initialization

## Status
Accepted

## Context
We need to decide how to initialize the Figma client across our application.

## Decision
We will use the singleton pattern with lazy initialization.

## Consequences
- Pro: Single client instance, connection reuse
- Pro: Easy to mock in tests
- Con: Global state requires careful lifecycle management

## Enforcement
- ESLint rule: figma/use-singleton-client
- CI check: gr

Figma Production Checklist

Overview

Complete checklist for deploying Figma integrations to production.

Prerequisites

• Staging environment tested and verified
• Production API keys available
• Deployment pipeline configured
• Monitoring and alerting ready

Instructions

Step 1: Pre-Deployment Configuration

• [ ] Production API keys in secure vault
• [ ] Environment variables set in deployment platform
• [ ] API key scopes are minimal (least privilege)
• [ ] Webhook endpoints configured with HTTPS
• [ ] Webhook secrets stored securely

Step 2: Code Quality Verification

• [ ] All tests passing (npm test)
• [ ] No hardcoded credentials
• [ ] Error handling covers all Figma error types
• [ ] Rate limiting/backoff implemented
• [ ] Logging is production-appropriate

Step 3: Infrastructure Setup

• [ ] Health check endpoint includes Figma connectivity
• [ ] Monitoring/alerting configured
• [ ] Circuit breaker pattern implemented
• [ ] Graceful degradation configured

Step 4: Documentation Requirements

• [ ] Incident runbook created
• [ ] Key rotation procedure documented
• [ ] Rollback procedure documented
• [ ] On-call escalation path defined

Step 5: Deploy with Gradual Rollout

# Pre-flight checks
curl -f https://staging.example.com/health
curl -s https://status.figma.com

# Gradual rollout - start with canary (10%)
kubectl apply -f k8s/production.yaml
kubectl set image deployment/figma-integration app=image:new --record
kubectl rollout pause deployment/figma-integration

# Monitor canary traffic for 10 minutes
sleep 600
# Check error rates and latency before continuing

# If healthy, continue rollout to 50%
kubectl rollout resume deployment/figma-integration
kubectl rollout pause deployment/figma-integration
sleep 300

# Complete rollout to 100%
kubectl rollout resume deployment/figma-integration
kubectl rollout status deployment/figma-integration

Output

• Deployed Figma integration
• Health checks passing
• Monitoring active
• Rollback procedure documented

Error Handling

Examples

Health Check Implementation

async function healthCheck(): Promise<{ status: string; figma: any }> {
  const start = Date.now();
  tr

Figma Rate Limits

Overview

Handle Figma rate limits gracefully with exponential backoff and idempotency.

Prerequisites

• Figma SDK installed
• Understanding of async/await patterns
• Access to rate limit headers

Instructions

Step 1: Understand Rate Limit Tiers

Step 2: Implement Exponential Backoff with Jitter

async function withExponentialBackoff<T>(
  operation: () => Promise<T>,
  config = { maxRetries: 5, baseDelayMs: 1000, maxDelayMs: 32000, jitterMs: 500 }
): Promise<T> {
  for (let attempt = 0; attempt <= config.maxRetries; attempt++) {
    try {
      return await operation();
    } catch (error: any) {
      if (attempt === config.maxRetries) throw error;
      const status = error.status || error.response?.status;
      if (status !== 429 && (status < 500 || status >= 600)) throw error;

      // Exponential delay with jitter to prevent thundering herd
      const exponentialDelay = config.baseDelayMs * Math.pow(2, attempt);
      const jitter = Math.random() * config.jitterMs;
      const delay = Math.min(exponentialDelay + jitter, config.maxDelayMs);

      console.log(`Rate limited. Retrying in ${delay.toFixed(0)}ms...`);
      await new Promise(r => setTimeout(r, delay));
    }
  }
  throw new Error('Unreachable');
}

Step 3: Add Idempotency Keys

import { v4 as uuidv4 } from 'uuid';
import crypto from 'crypto';

// Generate deterministic key from operation params (for safe retries)
function generateIdempotencyKey(operation: string, params: Record<string, any>): string {
  const data = JSON.stringify({ operation, params });
  return crypto.createHash('sha256').update(data).digest('hex');
}

async function idempotentRequest<T>(
  client: FigmaClient,
  params: Record<string, any>,
  idempotencyKey?: string  // Pass existing key for retries
): Promise<T> {
  // Use provided key (for retries) or generate deterministic key from params
  const key = idempotencyKey || generateIdempotencyKey(params.method || 'POST', params);
  return client.request({
    ...params,
    headers: { 'Idempotency-Key': key, ...params.headers },
  });
}

Output

• Reliable API calls with automatic retry
• Idempotent requests preventing duplicates
• Rate limit headers properly handled

Error Handling

my-figma-project/
├── src/
│   ├── figma/
│   │   ├── client.ts           # Singleton client wrapper
│   │   ├── config.ts           # Environment configuration
│   │   ├── types.ts            # TypeScript types
│   │   ├── errors.ts           # Custom error classes
│   │   └── handlers/
│   │       ├── webhooks.ts     # Webhook handlers
│   │       └── events.ts       # Event processing
│   ├── services/
│   │   └── figma/
│   │       ├── index.ts        # Service facade
│   │       ├── sync.ts         # Data synchronization
│   │       └── cache.ts        # Caching layer
│   ├── api/
│   │   └── figma/
│   │       └── webhook.ts      # Webhook endpoint
│   └── jobs/
│       └── figma/
│           └── sync.ts         # Background sync job
├── tests/
│   ├── unit/
│   │   └── figma/
│   └── integration/
│       └── figma/
├── config/
│   ├── figma.development.json
│   ├── figma.staging.json
│   └── figma.production.json
└── docs/
    └── figma/
        ├── SETUP.md
        └── RUNBOOK.md

┌─────────────────────────────────────────┐
│             API Layer                    │
│   (Controllers, Routes, Webhooks)        │
├─────────────────────────────────────────┤
│           Service Layer                  │
│  (Business Logic, Orchestration)         │
├─────────────────────────────────────────┤
│          Figma Layer        │
│   (Client, Types, Error Handling)        │
├─────────────────────────────────────────┤
│         Infrastructure Layer             │
│    (Cache, Queue, Monitoring)            │
└─────────────────────────────────────────┘

// src/figma/client.ts
export class FigmaService {
  private client: FigmaClient;
  private cache: Cache;
  private monitor: Monitor;

  constructor(config: FigmaConfig) {
    this.client = new FigmaClient(config);
    this.cache = new Cache(config.cacheOptions);
    this.monitor = new Monitor('figma');
  }

  async get(id: string): Promise<Resource> {
    return this.cache.getOrFetch(id, () =>
      this.monitor.track('get', () => this.client.get(id))
    );
  }
}

// src/figma/errors.ts
export class FigmaServiceError extends Error {
  constructor(
    message: string,
    public readonly code: string,
    public readonly retryable: boolean,
    public readonly originalError?: Error
  ) {
    super(message);
    this.name = 'FigmaServiceError';
  }
}

export function wrapFigmaError(error: unknown

import CircuitBreaker from 'opossum';

const figmaBreaker = new CircuitBreaker(
  async (operation: () => Promise<any>) => operation(),
  {
    timeout: 30000,
    errorThresholdPercentage: 50,
    resetTimeout: 30000,
    volumeThreshold: 10,
  }
);

// Events
figmaBreaker.on('open', () => {
  console.warn('Figma circuit OPEN - requests failing fast');
  alertOps('Figma circuit breaker opened');
});

figmaBreaker.on('halfOpen', () => {
  console.info('Figma circuit HALF-OPEN - testing recovery');
});

figmaBreaker.on('close', () => {
  console.info('Figma circuit CLOSED - normal operation');
});

// Usage
async function safeFigmaCall<T>(fn: () => Promise<T>): Promise<T> {
  return figmaBreaker.fire(fn);
}

import { v4 as uuidv4 } from 'uuid';
import crypto from 'crypto';

// Generate deterministic idempotency key from input
function generateIdempotencyKey(
  operation: string,
  params: Record<string, any>
): string {
  const data = JSON.stringify({ operation, params });
  return crypto.createHash('sha256').update(data).digest('hex');
}

// Or use random key with storage
class IdempotencyManager {
  private store: Map<string, { key: string; expiresAt: Date }> = new Map();

  getOrCreate(operationId: string): string {
    const existing = this.store.get(operationId);
    if (existing && existing.expiresAt > new Date()) {
      return existing.key;
    }

    const key = uuidv4();
    this.store.set(operationId, {
      key,
      expiresAt: new Date(Date.now() + 24 * 60 * 60 * 1000),
    });
    return key;
  }
}

import PQueue from 'p-queue';

// Separate queues for different operations
const figmaQueues = {
  critical: new PQueue({ concurrency: 10 }),
  normal: new PQueue({ concurrency: 5 }),
  bulk: new PQueue({ concurrency: 2 }),
};

async function prioritizedFigmaCall<T>(
  priority: 'critical' | 'normal' | 'bulk',
  fn: () => Promise<T>
): Promise<T> {
  return figmaQueues[priority].add(fn);
}

// Usage
await prioritizedFigmaCall('critical', () =>
  figmaClient.processPayment(order)
);

await prioritizedFigmaCall('bulk', () =>
  figmaClient.syncCatalog(products)
);

const TIMEOUT_CONFIG = {
  connect: 5000,   

// src/figma/client.ts
import { FigmaClient } from '@figma/sdk';

let instance: FigmaClient | null = null;

export function getFigmaClient(): FigmaClient {
  if (!instance) {
    instance = new FigmaClient({
      apiKey: process.env.FIGMA_API_KEY!,
      // Additional options
    });
  }
  return instance;
}

import { FigmaError } from '@figma/sdk';

async function safeFigmaCall<T>(
  operation: () => Promise<T>
): Promise<{ data: T | null; error: Error | null }> {
  try {
    const data = await operation();
    return { data, error: null };
  } catch (err) {
    if (err instanceof FigmaError) {
      console.error({
        code: err.code,
        message: err.message,
      });
    }
    return { data: null, error: err as Error };
  }
}

async function withRetry<T>(
  operation: () => Promise<T>,
  maxRetries = 3,
  backoffMs = 1000
): Promise<T> {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await operation();
    } catch (err) {
      if (attempt === maxRetries) throw err;
      const delay = backoffMs * Math.pow(2, attempt - 1);
      await new Promise(r => setTimeout(r, delay));
    }
  }
  throw new Error('Unreachable');
}

const clients = new Map<string, FigmaClient>();

export function getClientForTenant(tenantId: string): FigmaClient {
  if (!clients.has(tenantId)) {
    const apiKey = getTenantApiKey(tenantId);
    clients.set(tenantId, new FigmaClient({ apiKey }));
  }
  return clients.get(tenantId)!;
}