netlify-integration

Netlify の統合

このスキルを使用する場面

次のような場合に、このスキルを使用してください。

デプロイと設定：

• Next.js アプリケーションを Netlify にデプロイする
• ビルド設定、関数、リダイレクト、ヘッダー用に netlify.toml を設定する
• Netlify Dashboard または CLI で環境変数を設定する
• Git（GitHub、GitLab、Bitbucket）からの継続的デプロイを設定する

関数の開発：

• Netlify サーバーレス関数を作成する
• Webhook（Twilio、Telnyx、Stripe など）を処理する
• 関数のタイムアウト問題をデバッグする（無料プランでは上限 10s、Pro では 26s）
• 長時間実行されるタスク向けにバックグラウンド処理を実装する

トラブルシューティング：

• Webhook のタイムアウトエラーを修正する（特に SMS／テレフォニーアプリ）
• 「Function not found」（404）エラーをデバッグする
• 環境変数の問題を解決する
• ビルド失敗やデプロイエラーを修正する

SMS／テレフォニープロジェクト：

• SMS Webhook を処理する Twilio-Aldea のようなプロジェクトに取り組む
• Webhook に即座に応答し、バックグラウンドで処理する仕組みを実装する
• Webhook 署名（Twilio、Telnyx）を検証する

クイックリファレンス

1. 基本的な Netlify 関数ハンドラー

import type { Handler, HandlerEvent, HandlerContext } from "@netlify/functions";

export const handler: Handler = async (
  event: HandlerEvent,
  context: HandlerContext
) => {
  try {
    const body = JSON.parse(event.body || "{}");

    // Process request
    console.log("Request received:", body);

    return {
      statusCode: 200,
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ success: true }),
    };
  } catch (error) {
    console.error("Error:", error);
    return {
      statusCode: 500,
      body: JSON.stringify({ error: "Internal server error" }),
    };
  }
};

2. 即時応答する Webhook（重要なパターン）

メッセージの 60％ が失われる問題を解決します。即座に 200 を返し、非同期で処理します。

export const handler: Handler = async (event, context) => {
  // Validate webhook signature
  const isValid = validateWebhook(event);
  if (!isValid) {
    return { statusCode: 401, body: "Unauthorized" };
  }

  // IMMEDIATE: Return 200 OK (< 200ms)
  const response = {
    statusCode: 200,
    body: JSON.stringify({ received: true }),
  };

  // BACKGROUND: Process async (don't await)
  processWebhookAsync(event.body).catch(console.error);

  return response;
};

3. Next.js に必須の netlify.toml

[build]
  command = "npm run build"
  publish = ".next"

[build.environment]
  NODE_VERSION = "18"
  NEXT_TELEMETRY_DISABLED = "1"

# OpenNext adapter auto-detects Next.js — no plugin entry needed.
# Legacy: @netlify/plugin-nextjs is replaced by @opennextjs/netlify.

[functions]
  directory = ".netlify/functions"
  node_bundler = "esbuild"

# API rewrites
[[redirects]]
  from = "/api/*"
  to = "/.netlify/functions/:splat"
  status = 200
  force = true

# Security headers
[[headers]]
  for = "/*"
  [headers.values]
    X-Frame-Options = "DENY"
    X-Content-Type-Options = "nosniff"
    Referrer-Policy = "strict-origin-when-cross-origin"

4. 環境変数の設定（CLI）

前提条件 — まずプロジェクトをリンクします：

# Option 1: Interactive linking
netlify link

# Option 2: Manual linking (create .netlify/state.json)
mkdir -p .netlify
echo '{"siteId":"YOUR-SITE-ID-HERE"}' > .netlify/state.json

# Find your site ID
netlify sites:list  # Shows all sites with their IDs

# Verify link worked
netlify status

環境変数の管理：

# Set single variable (use --force to skip confirmation)
netlify env:set VARIABLE_NAME value
netlify env:set VARIABLE_NAME "value with spaces" --force

# Set for specific context (production, deploy-preview, branch-deploy, dev)
netlify env:set VARIABLE_NAME value --context production

# Import from .env file
netlify env:import .env.production

# List all variables
netlify env:list

# Get specific variable value
netlify env:get VARIABLE_NAME

# Delete variable
netlify env:unset VARIABLE_NAME

# Clone variables from another site
netlify env:clone --from OTHER_SITE_ID

一括追加の例（シェルから）：

# Add multiple env vars in sequence
netlify env:set API_KEY "sk-xxx" --force
netlify env:set ENABLE_FEATURE "true" --force
netlify env:set NEXT_PUBLIC_APP_URL "https://myapp.netlify.app" --force

注： 環境変数を追加または変更した後、本番環境に変更を反映するには、再デプロイを実行する必要がある場合があります。

5. 関数のタイムアウト設定

[functions]
  directory = ".netlify/functions"
  timeout = 10  # Default for all functions

# Increase timeout for specific function
[[functions."webhook"]]
  timeout = 26  # Max for Pro tier (10s for free)

6. 署名検証のための生のボディ解析

Twilio／Telnyx の Webhook 署名検証に不可欠です：

export const config = {
  api: {
    bodyParser: false,  // Disable Next.js body parsing
  },
};

async function readRawBody(req: NextApiRequest): Promise<string> {
  return new Promise<string>((resolve, reject) => {
    let data = '';
    req.setEncoding('utf8');
    req.on('data', (chunk) => { data += chunk; });
    req.on('end', () => resolve(data));
    req.on('error', reject);
  });
}

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  const rawBody = await readRawBody(req);

  // Validate signature with raw body
  const isValid = validateSignature(rawBody, req.headers['x-twilio-signature']);
  if (!isValid) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Process webhook...
}

7. データベースエラーのログ記録パターン

export const handler: Handler = async (event) => {
  try {
    await processMessage(data);
    return { statusCode: 200, body: 'Success' };
  } catch (error: unknown) {
    const err = error instanceof Error ? error : new Error(String(error));
    console.error('[Function] Error:', err);

    // Log to database for visibility
    await supabase.from('processing_errors').insert({
      error_message: err.message,
      error_stack: err.stack,
      created_at: new Date().toISOString(),
    });

    return { statusCode: 500, body: `Error: ${err.message}` };
  }
};

8. コネクションプーリングのパターン

// Reuse connections across function invocations
let supabaseClient: any = null;

function getSupabaseClient() {
  if (!supabaseClient) {
    supabaseClient = createClient(
      process.env.SUPABASE_URL!,
      process.env.SUPABASE_SERVICE_KEY!
    );
  }
  return supabaseClient;
}

export const handler: Handler = async (event, context) => {
  const supabase = getSupabaseClient();
  // Use cached client - reduces cold start time
};

9. ベース URL の動的検出

function getBaseUrl(req: NextApiRequest): string {
  const proto = (req.headers['x-forwarded-proto'] as string) || 'https';
  const host = (req.headers['x-forwarded-host'] as string) || (req.headers.host as string);
  return `${proto}://${host}`;
}

// Works in production, preview deploys, and localhost
const baseUrl = getBaseUrl(req);
const backgroundUrl = `${baseUrl}/.netlify/functions/background`;

10. Zod による入力検証

import { z } from "zod";

const WebhookSchema = z.object({
  from: z.string().min(10).max(15),
  to: z.string().min(10).max(15),
  body: z.string().min(1).max(1600),
  messageId: z.string().uuid(),
});

export const handler: Handler = async (event, context) => {
  try {
    const data = JSON.parse(event.body || "{}");
    const validated = WebhookSchema.parse(data);

    await processMessage(validated);
    return { statusCode: 200, body: JSON.stringify({ success: true }) };
  } catch (error) {
    if (error instanceof z.ZodError) {
      return {
        statusCode: 400,
        body: JSON.stringify({ error: "Validation failed", details: error.errors }),
      };
    }
    throw error;
  }
};

主要な概念

Netlify Functions

• AWS Lambda 上で実行されるサーバーレス関数
• .netlify/functions/ ディレクトリに配置します
• Node.js、TypeScript、Go をサポートします
• タイムアウト上限： 10s（無料プラン）、26s（Pro プラン）
• バックグラウンド関数： 15 分のタイムアウトにするには、名前の末尾に -background.ts を付けます

netlify.toml

• Netlify デプロイ用のファイルベースの設定
• リポジトリのルートに配置します
• ビルド設定、関数、リダイレクト、ヘッダーを制御します
• コンテキスト固有の設定（production、deploy-preview、branch-deploy）をサポートします

環境変数

• サーバー側： process.env.VARIABLE_NAME でアクセスします（名前の制約はありません）
• クライアント側： ブラウザーに公開するには、NEXT_PUBLIC_ を接頭辞として付ける必要があります
• Netlify Dashboard（Site Settings → Environment Variables）または CLI で設定します
• .env ファイルを Git にコミットしないでください

Webhook のタイムアウト問題

• SMS プロバイダー（Twilio／Telnyx）は 10 秒以内の応答を必要とします
• AI 処理には 15～25 秒かかります
• 解決策： 即座に 200 を返し、バックグラウンド関数で非同期処理します
• 結果： タイムアウト率が 60％ の失敗状態から 0％ になります

バックグラウンド関数

• ファイル名（function-name-background.ts）に基づいて自動検出されます
• 15 分のタイムアウト（通常の関数は 10～26s）
• 長時間実行される AI 処理、データ処理などに最適です
• 追加の設定は不要です

Next.js と Netlify の統合

• オープンソースの OpenNext アダプター（@opennextjs/netlify）を基盤としています。これは、標準的な方法として従来の @netlify/plugin-nextjs に代わるものです
• App Router、Server Components、Streaming を含め、Next.js 13.5 から 16 までをサポートします
• ISR、SSR、静的生成、きめ細かなエッジキャッシュを自動で処理します
• API ルートは自動的にサーバーレス関数に変換されます
• カスタム関数は .netlify/functions/ に配置します（pages/api/ とは別です）
• package.json でバージョンを固定しない限り、アダプターはビルドのたびに自動更新されます

リファレンスファイル

コア設定

• references/netlify_config.md - すべての設定オプション（build、functions、redirects、headers、contexts）を網羅した netlify.toml リファレンス
• references/environment_variables.md - 環境変数の管理、スコープ、クライアントとサーバーの違い、一括インポート／エクスポート

Functions の開発

• references/functions_best_practices.md - Functions のパターン：非同期処理、エラー処理、セキュリティ、データベース操作、モニタリング
• references/production-patterns.md - Twilio-Aldea の本番環境で使われている8つの実践的なパターン（Webhook のタイムアウト、バックグラウンド処理、エラーログ記録）

トラブルシューティング

• references/debugging.md - ビルド失敗、Functions のエラー、Webhook の問題、データベースの問題に関する包括的なデバッグガイド

Netlify 公式ドキュメント

• references/official-docs/functions.md - ハンドラーの種類、イベント構造、デプロイを網羅した Netlify Functions の完全ガイド
• references/official-docs/environment-variables.md - 環境変数の設定、スコープ、実行時のアクセス
• references/official-docs/netlify-toml.md - ファイルベースの設定リファレンス
• references/official-docs/nextjs.md - OpenNext アダプターを使用した Netlify 上の Next.js：App Router、ISR、SSR、skew protection、画像の最適化

コード例

• assets/examples/webhook-function.ts - 即時応答パターンを使用した Webhook ハンドラー
• assets/examples/background-function.ts - 長時間実行される処理向けのバックグラウンド Function
• assets/examples/netlify.toml - コメント付きの完全な設定例
• assets/examples/api-route.ts - raw body の解析と署名検証を行う Next.js API ルート

プロジェクト固有

• references/twilio_aldea_specific.md - Twilio-Aldea SMS プラットフォーム固有のパターン（Webhook 処理、セッション管理、統一されたプロバイダーインターフェース）

GitHub リポジトリ（新規）

references/github/README.md

GitHub の Netlify CLI 公式 README（netlify/cli、スター1,752個）

references/github/issues.md

よくある問題と解決策を示す GitHub の Issue 12件：

• ビルドの失敗とデプロイエラー
• 環境変数の問題
• Function のタイムアウト問題
• リダイレクトとルーティングの設定
• ローカル開発環境のセットアップ

references/github/CHANGELOG.md

破壊的変更と新機能を含む完全なバージョン履歴

references/github/releases.md

詳細な CLI 変更履歴を含む GitHub リリース1,203件

references/github/file_structure.md

CLI のソースコード構成を示すリポジトリ構造（871ファイル）

このスキルの使い方

初心者向け

Netlify を初めて使う場合は、ここから始めてください：

1. 最初のアプリをデプロイする：

   • 以下の「初回デプロイ（Git 統合）」セクションを確認します
   • 手順に沿ってワークフローを進めます
   • Quick Reference #3 を、netlify.toml の最初のテンプレートとして使用します

2. 基本を理解する：

   • Netlify Functions の基本について、references/official-docs/functions.md を読みます
   • Quick Reference（#1、#4）のシンプルな例を確認します
   • 環境設定について、references/official-docs/environment-variables.md を確認します

3. 最初の Function を作成する：

   • Basic Function Handler の例（#1）をコピーします
   • .netlify/functions/hello.ts に配置します
   • デプロイして、https://yoursite.netlify.app/.netlify/functions/hello でテストします

中級者向け

Netlify の基本をすでに理解している方：

1. 本番環境向けのパターンを実装する：

   • 実際のユースケース例については、references/production-patterns.md を確認してください
   • Webhook を処理する場合は、パターン 1（即時応答＋バックグラウンド処理）を実装してください
   • モニタリングを改善するため、パターン 5（データベースへのエラーログ記録）を確認してください

2. セットアップを最適化する：

   • コールドスタートを減らすため、コネクションプーリング（#8）を追加してください
   • データベースへのログ記録（#7）を含む、適切なエラー処理を実装してください
   • Zod を使った入力検証（#10）を追加してください

3. 複雑なシナリオに対応する：

   • Webhook の署名検証のために、Raw Body の解析（#6）を学んでください
   • netlify.toml でコンテキスト固有のビルドを設定してください
   • API 呼び出し用のプロキシパターンを設定してください（production-patterns.md のパターン 4）

上級者向け

本番環境向けの高品質なサーバーレスアプリを構築する方：

1. Webhook 処理を習得する：

   • references/production-patterns.md のパターン 1（Webhook タイムアウトの解決策）を詳しく確認してください
   • Twilio／Telnyx の Webhook 向けに署名検証を実装してください
   • 複数の関数を使ったアーキテクチャを設計してください（API ルート＋バックグラウンド関数）

2. パフォーマンスを最適化する：

   • references/functions_best_practices.md でコールドスタートを減らす手法を確認してください
   • 重い依存関係を遅延読み込みするよう実装してください
   • 関数のメモリとタイムアウトを適切に設定してください

3. 高度なデバッグ：

   • 可観測性を向上させるため、構造化ログのパターンを使ってください
   • パフォーマンス指標の追跡を実装してください
   • データベースへの永続化を含む、包括的なエラーログ記録を設定してください

4. 複数環境のセットアップ：

   • コンテキスト固有の環境（本番、ステージング、開発）を設定してください
   • コンテキスト間で環境変数を管理してください
   • フィーチャーフラグと A/B テストのパターンを実装してください

よく使われるワークフロー

Next.js アプリを Netlify にデプロイする

1. リポジトリを準備する：

   # Add netlify.toml (use Quick Reference #3 as template)
   # Add .env.example with all required variables
   git add netlify.toml .env.example
   git commit -m "Add Netlify configuration"
   git push origin main
   

2. Netlify に接続する：

   • Netlify Dashboard → 「Add new site」→「Import an existing project」にアクセスします
   • Git プロバイダーとリポジトリを選択します
   • netlify.toml に基づいてビルド設定が自動検出されます

3. 環境変数を設定する：

   netlify env:set VARIABLE_NAME value
   # Or use Netlify Dashboard: Site Settings → Environment Variables
   

4. デプロイする：

   • git push で自動デプロイするか、手動で実行します：netlify deploy --prod

Webhook のタイムアウト問題を解決する

症状： メッセージの 60% が失われ、504 Gateway Timeout エラーが発生する

解決策：

1. 処理に 10 秒以上かかっているかどうかを確認します
2. 即時応答パターンを実装します（クイックリファレンス #2）
3. -background.ts のサフィックスを付けてバックグラウンド関数を作成します
4. 時間のかかる処理をバックグラウンド関数に移します
5. netlify dev を使ってローカルでテストします

参照： 完全な実装については、references/production-patterns.md のパターン 1 を参照してください

関数のエラーをデバッグする

1. 関数のログを確認する：

   netlify functions:log function-name --stream
   

2. 構造化ログを追加する：

   console.log(JSON.stringify({
     timestamp: new Date().toISOString(),
     level: "error",
     message: "Error details",
     context: { requestId: context.requestId }
   }));
   

3. ローカルでテストする：

   netlify dev
   # Test at http://localhost:8888/.netlify/functions/function-name
   

4. よくある問題を確認する：

   • 包括的なトラブルシューティングガイドについては、references/debugging.md を参照してください

バージョン履歴

• v2.1（2026-04-21）- OpenNext アダプター（従来の @netlify/plugin-nextjs を置き換え）に対応し、Next.js 16 のサポートと、より細かなエッジキャッシュを追加
• v2.0（2025-11-01）- Netlify の公式ドキュメント、Twilio-Aldea の本番環境向けパターン、TypeScript の例、Webhook タイムアウトの解決策、包括的な Next.js 統合ガイドで強化。実際の本番環境のコードから抽出した、実用的なクイックリファレンスの例を 10 個追加。
• v1.0 - デプロイのワークフロー、設定、関数開発、デバッグを含む初期スキルの作成

その他のリソース

公式ドキュメント：

• Netlify Functions
• Netlify on Next.js
• 環境変数

Netlify CLI：

• インストール：npm install -g netlify-cli
• ログイン：netlify login
• ドキュメント：netlify help

ヘルパースクリプト：

• scripts/check_deployment.sh - デプロイのステータスと稼働状況を確認します
• scripts/setup_env_vars.sh - 環境変数を一括設定します
• scripts/test_function_locally.sh - Netlify Functions をローカルでテストします