Figma REST APIで画像アセットを自動書き出し

curl -H "X-Figma-Token: $FIGMA_ACCESS_TOKEN" \
  "https://api.figma.com/v1/files/YOUR_FILE_KEY"

{
  "name": "utsusie Design System",
  "lastModified": "2026-01-25T01:28:27Z",
  "thumbnailUrl": "https://...",
  "version": "1234567890",
  "role": "owner",
  "document": {
    "id": "0:0",
    "name": "Document",
    "type": "DOCUMENT",
    "children": [
      {
        "id": "45:2",
        "name": "Components",
        "type": "CANVAS",
        "children": [
          {
            "id": "45:3",
            "name": "Toolbar",
            "type": "FRAME",
            "children": [
              {
                "id": "46:8",
                "name": "Toolbar / Item",
                "type": "INSTANCE",
                "exportSettings": [
                  {
                    "suffix": "",
                    "format": "PNG",
                    "constraint": {
                      "type": "SCALE",
                      "value": 1.0
                    }
                  }
                ],
                "children": [...]
              }
            ]
          }
        ]
      },
      {
        "id": "12:2",
        "name": "Background",
        "type": "CANVAS",
        "children": [
          {
            "id": "13:6",
            "name": "Texture / Light",
            "type": "COMPONENT",
            "exportSettings": [
              {
                "suffix": "",
                "format": "JPG",
                "constraint": {
                  "type": "SCALE",
                  "value": 1.0
                }
              }
            ]
          }
        ]
      }
    ]
  },
  "components": {...},
  "componentSets": {...},
  "schemaVersion": 0,
  "styles": {...}
}

const fileKey = "FIGMA_FILE_KEY"; // ここにFigmaファイルキーを設定
const token = process.env.FIGMA_ACCESS_TOKEN;

fetch(`https://api.figma.com/v1/files/${fileKey}`, {
  headers: {
    'X-Figma-Token': token,
  },
})
  .then(res => res.json())
  .then(data => {
    console.log(JSON.stringify(data, null, 2));
  })
  .catch(err => {
    console.error('Error:', err.message);
    process.exit(1);
  });

{
  "scripts": {
    "figma:file": "node scripts/get-figma-file.js"
  }
}

npm run figma:file

{
  "id": "46:8",  // ← Images endpointで使用
  "name": "Toolbar / Item",
  "type": "INSTANCE",
  "exportSettings": [
    {
      "suffix": "@2x",
      "format": "PNG",  // ← Images endpointのformatパラメータに使用
      "constraint": {
        "type": "SCALE",
        "value": 2  // ← Images endpointのscaleパラメータに使用
      }
    }
  ]
}

// Export設定から取得した情報
const nodeId = '46:8';  // Export設定があるノードのID
const format = 'png';   // exportSettings[0].format（小文字に変換）
const scale = 2;        // exportSettings[0].constraint.value

// Images endpointを呼び出し
const response = await fetch(
  `https://api.figma.com/v1/images/${fileKey}?ids=${nodeId}&format=${format}&scale=${scale}`,
  {
    headers: {
      'X-Figma-Token': process.env.FIGMA_ACCESS_TOKEN!,
    },
  }
);

const { images } = await response.json();
// images: { "46:8": "https://s3-alpha.figma.com/img/...", ... }

const fs = require('fs').promises;
const path = require('path');

// 環境変数
const FIGMA_ACCESS_TOKEN = process.env.FIGMA_ACCESS_TOKEN;
const FIGMA_FILE_KEY = process.env.FIGMA_FILE_KEY;
const OUTPUT_DIR = process.env.OUTPUT_DIR || 'figma/export';

/**
 * Figmaファイル情報を取得
 */
async function getFigmaFile(fileKey) {
  const response = await fetch(`https://api.figma.com/v1/files/${fileKey}`, {
    headers: { 'X-Figma-Token': FIGMA_ACCESS_TOKEN },
  });

  if (!response.ok) {
    throw new Error(`Figma API Error: ${response.status}`);
  }

  return await response.json();
}

/**
 * Export設定があるノードを再帰的に収集
 */
function collectExportableNodes(node, nodes = []) {
  if (node.exportSettings && node.exportSettings.length > 0) {
    nodes.push({
      id: node.id,
      name: node.name,
      exportSettings: node.exportSettings,
    });
  }

  if (node.children) {
    node.children.forEach((child) => collectExportableNodes(child, nodes));
  }

  return nodes;
}

/**
 * 画像URLを取得
 */
async function getImageUrl(fileKey, nodeId, format, scale) {
  const params = new URLSearchParams({
    ids: nodeId,
    format: format.toLowerCase(),
  });

  if (format.toLowerCase() !== 'svg') {
    params.append('scale', scale);
  }

  const response = await fetch(
    `https://api.figma.com/v1/images/${fileKey}?${params}`,
    { headers: { 'X-Figma-Token': FIGMA_ACCESS_TOKEN } }
  );

  if (!response.ok) {
    throw new Error(`Figma API Error: ${response.status}`);
  }

  const data = await response.json();
  return data.images[nodeId];
}

/**
 * 画像をダウンロードして保存
 */
async function downloadImage(url, outputPath) {
  const response = await fetch(url);

  if (!response.ok) {
    throw new Error(`Download failed: ${response.status}`);
  }

  const buffer = await response.arrayBuffer();
  await fs.writeFile(outputPath, Buffer.from(buffer));
}

/**
 * ファイル名をサニタイズ
 */
function sanitizeFileName(name) {
  return name.replace(/[<>:"/\\|?*]/g, '-').replace(/\s+/g, '-').toLowerCase();
}

/**
 * メイン処理
 */
async function main() {
  if (!FIGMA_ACCESS_TOKEN || !FIGMA_FILE_KEY) {
    console.error('Error: FIGMA_ACCESS_TOKEN and FIGMA_FILE_KEY are required');
    process.exit(1);
  }

  console.log('Starting Figma asset export...\n');

  // 出力ディレクトリ作成
  await fs.mkdir(OUTPUT_DIR, { recursive: true });

  // Figmaファイル取得
  console.log('Fetching Figma file...');
  const fileData = await getFigmaFile(FIGMA_FILE_KEY);
  console.log(`File: ${fileData.name}\n`);

  // Export設定があるノードを収集
  const nodes = collectExportableNodes(fileData.document);
  console.log(`Found ${nodes.length} nodes with export settings\n`);

  if (nodes.length === 0) {
    console.log('No export settings found');
    return;
  }

  // 各ノードを処理
  let successCount = 0;

  for (const node of nodes) {
    for (const setting of node.exportSettings) {
      const format = setting.format.toLowerCase();
      const scale = setting.constraint?.value || 1;
      const suffix = setting.suffix || '';

      // ファイル名生成
      const fileName = `${sanitizeFileName(node.name)}${suffix}.${format}`;
      const outputPath = path.join(OUTPUT_DIR, fileName);

      console.log(`Processing: ${node.name} (${format.toUpperCase()} @${scale}x)`);

      try {
        // 画像URL取得
        const imageUrl = await getImageUrl(FIGMA_FILE_KEY, node.id, format, scale);

        if (!imageUrl) {
          throw new Error('Failed to get image URL');
        }

        // ダウンロード
        await downloadImage(imageUrl, outputPath);

        console.log(`  ✓ Saved: ${fileName}\n`);
        successCount++;

        // レート制限対策（300ms待機）
        await new Promise((resolve) => setTimeout(resolve, 300));
      } catch (error) {
        console.error(`  ✗ Error: ${error.message}\n`);
      }
    }
  }

  console.log(`\nCompleted: ${successCount} files exported to ${OUTPUT_DIR}`);
}

main().catch((error) => {
  console.error('Fatal error:', error.message);
  process.exit(1);
});

{
  "scripts": {
    "figma:export": "node scripts/export-figma-assets-simple.js"
  }
}

npm run figma:export

Starting Figma asset export...

Fetching Figma file...
File: utsusie Design System

Found 3 nodes with export settings

Processing: Toolbar / Item (PNG @1x)
  ✓ Saved: toolbar---item.png

Processing: Texture / Light (JPG @1x)
  ✓ Saved: texture---light.jpg

Processing: Texture / Dark (JPG @1x)
  ✓ Saved: texture---dark.jpg

Completed: 3 files exported to figma/export