Figma Multi-Environment Setup
Overview
Configure separate Figma API credentials and file targets per environment. Use different PATs with minimal scopes, point to different Figma files, and prevent accidental production operations from dev.
Prerequisites
- Separate Figma PATs for each environment
- Secret management solution
- Environment detection in application
Instructions
Step 1: Environment Strategy
| Environment | PAT Scopes | Figma File | Cache TTL |
|---|
| Development | file_content:read | Copy of design file | 10s (fast iteration) |
| Staging | file_content:read, file_comments:read | Staging branch/file | 60s |
| Production | file_content:read, webhooks:write | Production design file | 300s |
Step 2: Configuration by Environment
interface FigmaEnvConfig {
token: string;
fileKey: string;
cacheTTL: number;
webhookPasscode?: string;
maxConcurrency: number;
}
function getFigmaConfig(): FigmaEnvConfig {
const env = process.env.NODE_ENV || 'development';
const configs: Record<string, Partial<FigmaEnvConfig>> = {
development: {
token: process.env.FIGMA_PAT_DEV!,
fileKey: process.env.FIGMA_FILE_KEY_DEV!,
cacheTTL: 10_000,
maxConcurrency: 1,
},
staging: {
token: process.env.FIGMA_PAT_STAGING!,
fileKey: process.env.FIGMA_FILE_KEY_STAGING!,
cacheTTL: 60_000,
maxConcurrency: 3,
},
production: {
token: process.env.FIGMA_PAT_PROD!,
fileKey: process.env.FIGMA_FILE_KEY_PROD!,
cacheTTL: 300_000,
maxConcurrency: 5,
webhookPasscode: process.env.FIGMA_WEBHOOK_PASSCODE,
},
};
const config = configs[env];
if (!config?.token) throw new Error(`Figma token not configured for env: ${env}`);
if (!config?.fileKey) throw new Error(`Figma file key not configured for env: ${env}`);
return config as FigmaEnvConfig;
}
Step 3: Environment Files
FIGMA_PAT_DEV="figd_dev-token-read-only"
FIGMA_FILE_KEY_DEV="devFileKey123"
FIGMA_PAT_STAGING="figd_staging-token"
FIGMA_FILE_KEY_STAGING="stagingFileKey456"
FIGMA_PAT_PROD="figd_prod-token"
FIGMA_FILE_KEY_PROD="prodFileKey789"
FIGMA_WEBHOOK_PASSCODE="webhook-secret"
FIGMA_PAT_DEV=
FIGMA_FILE_KEY_DEV=
Step 4: Secret Management
gh secret set FIGMA_PAT_PROD --env production --body "figd_..."
gh secret set FIGMA_PAT_STAGING --env staging --body "figd_..."
echo -n "figd_prod-token" | gcloud secrets create figma-pat-prod --data-file=-
echo -n "figd_staging-token" | gcloud secrets create figma-pat-staging --data-file=-
gcloud run deploy my-service \
--set-secrets="FIGMA_PAT_PROD=figma-pat-prod:latest"
Step 5: Environment Guards
function requireProduction(operation: string) {
if (process.env.NODE_ENV !== 'production') {
throw new Error(
`${operation} is only allowed in production. ` +
`Current env: ${process.env.NODE_ENV}`
);
}
}
function blockInProduction(operation: string) {
if (process.env.NODE_ENV === 'production') {
throw new Error(`${operation} is blocked in production for safety`);
}
}
async function createWebhook(config: any) {
requireProduction('createWebhook');
return fetch('https://api.figma.com/v2/webhooks', { ... });
}
async function deleteAllCachedData() {
blockInProduction();
cache.();
}
Output
- Per-environment Figma configuration
- Secrets stored in appropriate secret managers
- Environment guards preventing cross-env mistakes
- Template env files for team onboarding
Error Handling
| Issue | Cause | Solution |
|---|
| Wrong file in dev | Using prod file key | Verify FIGMA_FILE_KEY_DEV |
| PAT expired in CI | 90-day expiry | Set rotation reminder per environment |
| Staging webhook pointing to prod | Wrong endpoint URL | Verify webhook endpoint per env |
| Config not loading | Missing NODE_ENV | Set NODE_ENV in deployment config |
Examples
Point the same integration at a staging file locally and the production file in CI using the Step 2 config loader:
FIGMA_ENV=development
FIGMA_FILE_KEY=stgAbC123fileKey
FIGMA_WEBHOOK_ENDPOINT=https://dev.example.com/figma/webhook
FIGMA_ENV=production
FIGMA_FILE_KEY=prodXyZ789fileKey
Verify the guard refuses a cross-environment mistake before any API call is made:
FIGMA_ENV=production FIGMA_FILE_KEY=stgAbC123fileKey node sync-tokens.js
Environment strategy and per-env webhook registration (POST /v2/webhooks per environment): references/configuration-by-environment.md and references/environment-guards.md.
Resources
Next Steps
For observability setup, see figma-observability.
