supabase-auth-storage-realtime-core

Supabase Auth + Storage + Realtime Core

概要

Supabase データベースを完全なアプリケーションバックエンドにする3つの柱、すなわちユーザー認証（メールアドレス／パスワード、OAuth、マジックリンク、セッションのライフサイクル）、ファイルストレージ（アップロード、ダウンロード、署名付き URL、バケットレベルの RLS ポリシー）、リアルタイムサブスクリプション（Postgres の変更イベント、クライアント間ブロードキャスト、プレゼンス追跡）を実装します。すべての操作は auth.uid() を通じて Row-Level Security と連携します。

以下の各柱について、このファイルには簡潔な骨組みを記載しています。詳しいコピー＆ペースト形式の手順は references/ にまとめているため、このファイルをざっと確認しやすい状態に保てます。

前提条件

• supabase.com/dashboard で Supabase プロジェクトを作成していること
• @supabase/supabase-js v2 をインストールしていること（npm install @supabase/supabase-js）
• プロジェクトの Settings > API で SUPABASE_URL と SUPABASE_ANON_KEY を確認できること
• Python の場合：pip install supabase（postgrest-py、gotrue-py、storage3、realtime-py をラップします）

手順

ファイルを読み込み（Read）、クライアントとルート／コンポーネントのコードを編集または作成（Write、Edit）し、新しいクライアントを作成する前にプロジェクトを検索（Grep）して、既存の Supabase クライアントを再利用してください。SDK のインストールには Bash(npm:*) を、マイグレーション／ポリシーの実行には Bash(supabase:*) を使用してください。

ステップ 1：Auth — 登録、ログイン、OAuth

まずクライアントを一度だけ初期化し、アプリで必要なフローを組み込みます。基本形：

import { createClient } from '@supabase/supabase-js'

const supabase = createClient(process.env.SUPABASE_URL!, process.env.SUPABASE_ANON_KEY!)

// Email/password
await supabase.auth.signUp({ email, password })
await supabase.auth.signInWithPassword({ email, password })

// OAuth — redirect the user to data.url
const { data } = await supabase.auth.signInWithOAuth({ provider: 'google' })

// React to session changes (SIGNED_IN / SIGNED_OUT / TOKEN_REFRESHED)
supabase.auth.onAuthStateChange((event, session) => { /* update UI */ })

Auth の詳しい手順 — OAuth コールバック、マジックリンク、セッションのライフサイクル、パスワードのリセット：references/auth.md。Python：references/python-examples.md。

ステップ 2：Storage — アップロード、ダウンロード、バケットポリシーによる保護

パブリックバケットは CDN URL で配信し、プライベートバケットでは署名付き URL が必要です。基本形：

// Upload to the signed-in user's own folder (RLS enforces ownership)
await supabase.storage.from('avatars').upload(`${userId}/avatar.png`, file, { upsert: true })

// Public URL (public bucket) vs. time-limited signed URL (private bucket)
supabase.storage.from('avatars').getPublicUrl(`${userId}/avatar.png`)
await supabase.storage.from('documents').createSignedUrl('reports/q4.pdf', 3600)

Storage の詳しい手順 — ダウンロード、一覧表示、削除、およびユーザーごとのアクセスを適用するバケット RLS ポリシー：references/storage.md。Python：references/python-examples.md。

ステップ 3：Realtime — Postgres の変更、ブロードキャスト、プレゼンス

チャネルは3種類あります。データベース変更のリスナー、クライアント間ブロードキャスト、プレゼンスです。基本形：

const channel = supabase
  .channel('chat-room')
  .on('postgres_changes',
    { event: 'INSERT', schema: 'public', table: 'messages' },
    (payload) => console.log('New:', payload.new))
  .subscribe()
// One-time table setup: ALTER PUBLICATION supabase_realtime ADD TABLE messages;
supabase.removeChannel(channel)  // clean up

Realtime の詳しい手順 — UPDATE／DELETE フィルター、RLS の適用範囲に応じたサブスクリプション、ブロードキャスト、プレゼンス追跡：references/realtime.md。Python：references/python-examples.md。

出力

• Auth：ユーザー登録、パスワードログイン、OAuth フロー（Google／GitHub）、マジックリンク、onAuthStateChange によるセッションのライフサイクル、パスワードのリセット
• Storage：ファイルのアップロード／ダウンロード、CDN 配信アセット用のパブリック URL、プライベートファイル用の有効期限付き署名付き URL、auth.uid() と storage.foldername() を使用したバケットレベルの RLS ポリシー
• Realtime：サーバー側フィルターを使用した Postgres 変更サブスクリプション、クライアント間メッセージ用のブロードキャストチャネル、オンライン状態のプレゼンス追跡

エラー処理

エラー	原因	解決策
AuthApiError: User already registered	メールアドレスが重複して登録されています	signInWithPassword を使用するか、事前に登録済みか確認します
AuthApiError: Invalid login credentials	メールアドレスまたはパスワードが正しくありません	認証情報を確認し、メールアドレスの確認状況も確認します
AuthApiError: Email not confirmed	ユーザーが確認リンクをクリックしていません	resend({ type: 'signup', email }) で再送します
StorageApiError: Bucket not found	バケットが存在しません	ダッシュボードまたは INSERT INTO storage.buckets で作成します
StorageApiError: new row violates row-level security	RLS ポリシーによって操作がブロックされています	storage.objects のポリシーがユーザーとバケットに一致することを確認します
StorageApiError: The resource already exists	ファイルが存在し、upsert: false になっています	上書きするには upsert: true を設定するか、一意のパスを使用します
Realtime: channel error または TIMED_OUT	ネットワークの問題、または Realtime が有効になっていません	対象テーブルに対する ALTER PUBLICATION supabase_realtime ADD TABLE を確認します
Realtime: too many channels	同時チャンネル数の上限を超えています	removeChannel() で使用していないチャンネルの購読を解除します

例

サインインし、RLS で保護されたユーザーフォルダーにアバターをアップロードして公開 URL を取得し、プロフィールのライブ更新を購読する一連の流れは、references/examples.md に記載されています。各ステップでは、上記の 3 つの基本例を組み合わせており、新しい API は使用していません。

リソース

• 認証ガイド
• 認証 API リファレンス
• ストレージガイド
• ストレージのアクセス制御
• Realtime ガイド
• Realtime の Postgres 変更
• Realtime ブロードキャスト
• Realtime プレゼンス

次のステップ

Supabase の一般的なエラーとデバッグについては、supabase-common-errors を参照してください。 データベースのクエリと CRUD 操作については、supabase-crud-core を参照してください。