insforge

InsForge アプリ統合スキル

このスキルでは、@insforge/sdk を使用したクライアントサイド SDK の統合を扱います。（テーブルの作成、スキーマの確認、関数のデプロイ、シークレット、ストレージバケットの管理、決済プロバイダーのキーやカタログの設定、ウェブサイトのデプロイ、cron ジョブとスケジュール、ログなど）バックエンドのインフラストラクチャ操作には、insforge-cli スキルを使用してください。

クイックセットアップ

1. SDK をインストールする

npm install @insforge/sdk@latest

2. 環境変数を設定する

SDK を使用する前に、プロジェクトのルートに InsForge の URL と anon キーを記載した .env ファイル（Next.js の場合は .env.local）を作成してください。

URL と anon キーの取得方法

1. プロジェクトがリンクされていることを確認します。 プロジェクトのルートにある .insforge/project.json を確認してください。

   • 既存のプロジェクトでは npx -y @insforge/cli link を、新しいプロジェクトでは npx -y @insforge/cli create を実行して生成します。

2. CLI で anon キーを取得します。

   npx -y @insforge/cli secrets get ANON_KEY
   

3. URL を取得します。 .insforge/project.json の oss_host フィールドを確認してください（例：https://myapp.us-east.insforge.app）。

4. 両方の値を .env ファイルに記述します。 使用するフレームワークに適したプレフィックスを指定してください（下表を参照）。

重要： SSR を含む、ユーザー権限の範囲で使用する SDK クライアントには anon キーを使用してください。管理者／サービスアクセスが必要な、特権を持つサーバー専用アプリコードでは、createAdminClient({ apiKey }) を使用します。API キーはすべてのアクセス権を持つ管理者キーで、他のプラットフォームにおけるサービスロールキーに相当します。

フレームワークに適した環境変数プレフィックスとアクセス方法を使用してください。

フレームワーク	.env ファイル	変数	アクセス方法
Next.js	.env.local	NEXT_PUBLIC_INSFORGE_URL、NEXT_PUBLIC_INSFORGE_ANON_KEY	process.env.NEXT_PUBLIC_*
Vite（React、Vue、Svelte）	.env	VITE_INSFORGE_URL、VITE_INSFORGE_ANON_KEY	import.meta.env.VITE_*
Astro	.env	PUBLIC_INSFORGE_URL、PUBLIC_INSFORGE_ANON_KEY	import.meta.env.PUBLIC_*
SvelteKit	.env	PUBLIC_INSFORGE_URL、PUBLIC_INSFORGE_ANON_KEY	import { env } from '$env/dynamic/public'
Create React App	.env	REACT_APP_INSFORGE_URL、REACT_APP_INSFORGE_ANON_KEY	process.env.REACT_APP_*
Node.js / Server	.env	INSFORGE_URL、INSFORGE_ANON_KEY	process.env.*

Next.js 用の .env.local の例：

NEXT_PUBLIC_INSFORGE_URL=https://your-appkey.us-east.insforge.app
NEXT_PUBLIC_INSFORGE_ANON_KEY=eyJhbGciOiJIUzI1NiIs...

重要： .env ファイルはローカルに保管してください。.env、.env.local、.env*.local を .gitignore に追加し、必要な変数を記載するための .env.example を用意してください。

3. クライアントを初期化する

Next.js：

import { createClient } from '@insforge/sdk'

const insforge = createClient({
  baseUrl: process.env.NEXT_PUBLIC_INSFORGE_URL,
  anonKey: process.env.NEXT_PUBLIC_INSFORGE_ANON_KEY
})

Vite：

import { createClient } from '@insforge/sdk'

const insforge = createClient({
  baseUrl: import.meta.env.VITE_INSFORGE_URL,
  anonKey: import.meta.env.VITE_INSFORGE_ANON_KEY
})

Astro：

import { createClient } from '@insforge/sdk'

const insforge = createClient({
  baseUrl: import.meta.env.PUBLIC_INSFORGE_URL,
  anonKey: import.meta.env.PUBLIC_INSFORGE_ANON_KEY
})

プロジェクト管理者アクセスが必要な、信頼されたサーバー専用コードの場合：

import { createAdminClient } from "@insforge/sdk";

const admin = createAdminClient({
  baseUrl: process.env.INSFORGE_URL,
  apiKey: process.env.INSFORGE_API_KEY,
});

モジュールリファレンス

モジュール	統合ガイド
データベース	database/sdk-integration.md
認証	auth/sdk-integration.md
ストレージ	storage/sdk-integration.md
関数	functions/sdk-integration.md
AI	ai/overview.md
リアルタイム	realtime/sdk-integration.md
メール	email/sdk-integration.md
決済：Stripe	payments/stripe.md
決済：Razorpay	payments/razorpay.md

各モジュールの内容

モジュール	内容
データベース	CRUD 操作、フィルター、ページネーション、RPC 呼び出し
認証	サインアップ／サインイン、OAuth、セッション、プロフィール、パスワードリセット
ストレージ	ファイルのアップロード、ダウンロード、削除；CI／バックアップツール向けの S3 互換ゲートウェイ；バケット用の RLS ポリシーの作成
関数	エッジ関数の呼び出し
AI	チャット、画像、動画、音声、埋め込み、モデル検出のための OpenRouter AI 呼び出し
メール	カスタムのトランザクション HTML メール（ウェルカム、ニュースレター、通知）の送信
決済：Stripe	Stripe Checkout Sessions、サブスクリプション、Billing Portal へのリダイレクト
決済：Razorpay	Razorpay Orders、サブスクリプション、Checkout.js、サブスクリプション管理
リアルタイム	接続、サブスクライブ、イベントの公開、プレゼンススナップショットと参加／退出差分の追跡

ガイド

ガイド	使用するタイミング
../insforge-cli/references/database/access-control.md	アプリケーションテーブルのアクセス制御に向けたバックエンドの設定 — RLS、無限再帰の防止、SECURITY DEFINER のパターン、パフォーマンスのヒント、InsForge でよく使われるパターンを説明します
storage/s3-gateway.md	既存の S3 ツール（aws CLI、AWS SDKs、rclone、Terraform、boto3）を利用する場合の代替手段で、@insforge/sdk の導入が現実的でない場合に使用します — エンドポイント／リージョンの設定、アクセスキーの管理、パス形式のアドレス指定、サポート対象および非対応の S3 操作を説明します。InsForge 2.0.9 以降が必要です。 アプリのコードでは SDK を優先してください（storage/sdk-integration.md）。
storage/postgres-rls.md	storage.objects の RLS ポリシーの作成 — 所有者のみ、公開読み取り、パスの範囲指定、チーム共有、および REST と S3 を併用するバケットでの NULL uploaded_by に関する注意点
../insforge-cli/references/database/vector.md	セマンティック検索、レコメンデーション、または RAG に向けたバックエンドの設定 — vector 拡張機能、スキーマ／次元、距離演算子、HNSW／IVFFlat インデックス、RPC 類似性検索を説明します
ai/chat-completions.md	OpenRouter を介したテキスト生成、構造化された回答、ストリーミングチャット
ai/image-generation.md	OpenRouter を介した画像の生成／編集と、その後の InsForge Storage への永続保存
ai/video-generation.md	OpenRouter による非同期の動画ジョブ、ステータスのポーリング、生成したメディアの保存
ai/audio.md	音声テキスト変換、テキスト音声変換、InsForge での音声アセット／文字起こしの保存
ai/embeddings-and-rag.md	OpenRouter を介した埋め込みの生成、pgvector への保存、基本的な RAG パイプラインの構築
ai/models-list.md	OpenRouter のモデル ID、モダリティ、パラメーター、料金、埋め込み次元の確認
payments	Stripe／Razorpay キーの設定、プロバイダーカタログの同期、ウェブフックの設定、アプリを統合する前の決済 RLS の作成

新しいアプリの決済機能の構築

まずプロバイダーを選択してください。汎用的なアプリ決済ガイドはありません。

• Stripe Checkout、サブスクリプション、Billing Portal については、payments/stripe.md を読み込んでください。
• Razorpay Orders、Subscriptions、Checkout.js、キャンセル／一時停止／再開のフローについては、payments/razorpay.md を読み込んでください。

アプリのコードを書く前に、insforge-cli の決済リファレンスでプロバイダーの設定を確認してください。

npx -y @insforge/cli payments stripe status
npx -y @insforge/cli payments razorpay status

選択したプロバイダーが設定されていない場合は、まず開発者／管理者にそのプロバイダーを設定するよう依頼してください。

リアルタイムバックエンドの設定

リアルタイム SDK は、フロントエンドでのイベント処理とメッセージングに使用します。チャネルパターン、データベーストリガー、チャネル／メッセージの RLS は、insforge-cli スキルを使って設定してください。realtime を参照してください。

バックエンドの設定

サポートされているプロジェクト設定項目は CLI で管理します。認証リダイレクト URL、 確認フラグ、パスワードポリシー、認証 SMTP 設定、ストレージのアップロードサイズ、 リアルタイム／スケジュールの保持期間、クラウドデプロイのサブドメインには、 npx -y @insforge/cli config export/plan/apply を使用してください。OAuth プロバイダー、 外部アプリのセットアップ、ストレージバケット、関数、シークレット、デプロイ環境変数は、 引き続き専用のダッシュボードまたは CLI フローを使用します。insforge-cli スキルの「Configuration」セクションを参照してください。

リスクのあるバックエンド変更を行う場合は、まずブランチを使用してください

このスキルでのコード変更がスキーママイグレーション、新しい RLS ポリシー、OAuth プロバイダー設定の変更、または本番環境の動作に影響するその他のバックエンド変更に依存する場合は、まずバックエンドブランチを作成してください。ブランチ間でJWT_SECRETは共有されます（既存のユーザー JWT は引き続き動作します）が、新しいデータベース、EC2、API_KEY／ANON_KEYが用意されるため、SDK とバックエンドの変更を分離された環境でエンドツーエンドにテストできます。

ブランチを使ったワークフロー全体はinsforge-cliスキルに記載されています。判断ガイドとライフサイクルコマンドについては、branch を参照してください。一般的な流れは次のとおりです。

npx -y @insforge/cli branch create feat-x --mode schema-only
# ... apply migrations / change auth config / update RLS on the branch ...
# ... test the SDK against the branch backend ...
npx -y @insforge/cli branch merge feat-x --dry-run     # review SQL
npx -y @insforge/cli branch merge feat-x               # apply to parent

⚠ branch create または branch switch の実行後は、アプリの InsForge URL と anon-key の環境変数を更新し、その後開発サーバーを再起動してください（または .env を再読み込みしてください）。これにより、SDK が選択したブランチのバックエンドに接続します。

SDK クイックリファレンス

SDK のすべてのメソッドは { data, error } を返します。

モジュール	メソッド
insforge.database	.from().select()、.insert()、.update()、.delete()、.rpc()
insforge.auth	.signUp()、.signInWithPassword()、.signInWithOtp() / .verifyOtp()、.signInWithOAuth()、.signOut()、.getCurrentUser()
insforge.storage	.from().upload()、.uploadAuto()、.download()、.remove()
insforge.functions	.invoke()
insforge.ai	非推奨のフォールバックのみ：.chat.completions.create()、.images.generate()、.embeddings.create()
insforge.realtime	.connect()、.subscribe()、.publish()、.on()、.disconnect()
insforge.emails	.send({ to, subject, html, cc?, bcc?, from?, replyTo? })
insforge.payments.stripe	.createCheckoutSession()、.createCustomerPortalSession()
insforge.payments.razorpay	.createOrder()、.verifyOrder()、.createSubscription()、.verifySubscription()、.cancelSubscription()、.pauseSubscription()、.resumeSubscription()

重要な注意事項

• データベースへの挿入には配列形式が必要です：insert([{...}])
• 帯域幅効率の高い読み取り：列名を指定し、一覧読み取りには.limit()を使用してください。間隔を空けて無制限のselect()をポーリングしないでください。代わりに、リアルタイム（realtime.publishトリガーと組み合わせる）でサブスクライブするか、低コストの順序付きプローブをポーリングしてください。無駄の多いクエリ形式は、プロジェクトが月間の送信データ量の上限を超える主な原因です。プローブのスニペットとルール全文については、database/sdk-integration.mdを参照してください。
• Next.js／SSR 認証：@insforge/sdk/ssrヘルパー（createBrowserClient、createServerClient、createAuthActions、createRefreshAuthRouter）を使用し、Proxy／Middlewareでは@insforge/sdk/ssr/middlewareからupdateSessionをインポートしてください。リフレッシュトークンはhttpOnlyに保ち、認証関連の変更はサーバー上のcreateAuthActions()を通じて実行し、Server Actionsからは安全なアプリデータのみを返し、ブラウザーではStorage／Realtime用に有効期間の短いアクセストークンを読み取れるようにしてください。auth/ssr-integration.mdを参照してください。
• Storage：ダウンロード／削除操作に備えて、urlとkeyの両方をデータベースに保存してください。
• Functionsの呼び出しURL：insforge.functions.invoke(slug)を優先してください。ルートの構築はSDKが処理します。生のHTTPを使用する場合、プロジェクトのベースURLでは互換パス/functions/{slug}が提供され、Functionsのデプロイホスト（例：*.function2.insforge.app）ではルート/{slug}でslugが提供されます。
• メール配信：認証メール（サインアップ確認、パスワードリセット、マジックリンク、招待）はすべてのプランで送信できます。insforge.emails.send()によるカスタムメールはすべての有料プランで送信できます。プラットフォーム管理の配信経路を使用してください。カスタム送信者ドメインはダッシュボードで設定します。email/sdk-integration.mdを参照してください。
• 決済：まずnpx -y @insforge/cli payments <provider> ...でプロバイダーキー／カタログを設定してください。フロントエンドコードではプロバイダーごとのSDKモジュールを使用します。
• 決済のRLS：決済UIを追加する前に、プロバイダーのランタイムテーブルにアプリ固有のRLSを設定してください。Stripeではpayments.stripe_checkout_sessionsとpayments.stripe_customer_portal_sessionsを、Razorpayではpayments.razorpay_ordersとpayments.razorpay_subscriptionsを使用します。永続的な履行トリガーは、成功URL、Checkoutコールバック、payments.transactionsではなく、payments.webhook_eventsに設定してください。
• Tailwind CSS v3.4を使用してください
• デプロイ前に必ずローカルでビルドしてください：ビルドリソースの無駄を防ぎ、デバッグを迅速化できます。
• SDKパッケージ：認証を含むすべての機能で、@insforge/sdkを直接使用してください。
• デプロイ：SPAルーティング（React、React Routerアプリ）には、プロジェクトのルートにvercel.jsonを含めてください。download-templateツールには、これがあらかじめ含まれています。
• リスクの高いバックエンド変更に対するブランチ運用：SDKコードが新しいスキーマ、RLSポリシー、または認証設定の変更に依存する場合は、まずnpx -y @insforge/cli branch createでブランチを作成してください。insforge-cliスキルのbranchリファレンスを参照してください。branch create／branch switchの実行後は、アプリのInsForge URLとanon-keyの環境変数を更新し、開発サーバーを再起動してください。
• InsForge側で問題が発生しましたか？ SDK、バックエンド、ドキュメント、またはスキルが想定どおりに動作しない場合（動作するはずのAPIでエラーが発生する（--type bug）、必要な機能がサポートされていない（--type feature-request）、ドキュメントが実際の動作と矛盾している（--type bug --component docsと--doc／--expectedを指定）など）は、問題を報告し、回避策を続けてください：npx -y @insforge/cli feedback --json --type <bug|feature-request|friction> --component <backend|sdk|cli|skills|docs> --title "..." --detail "..."。SDKの問題では--language <lang>を追加してください（ログイン不要。PIIはローカルで伏せられます）。利用可能なフラグと状況に応じたtypeの対応表については、insforge-cliスキルのFeedbackセクションを参照してください。作成中のアプリコードに関する問題は、決してフィードバックとして報告しないでください。