傳統架構                         Supabase 架構（純前端）
┌──────────┐                    ┌──────────┐
│  React   │                    │  React   │
│  前端     │                    │  前端     │
└────┬─────┘                    └────┬─────┘
     │ fetch('/api/todos')           │ supabase.from('todos').select()
     ↓                               ↓
┌──────────┐                    ┌──────────┐
│ Express  │                    │ Supabase │ ← 雲端服務
│ 後端 API  │                    │ (自帶 DB  │
└────┬─────┘                    │  + Auth   │
     │ SQL query                │  + API)   │
     ↓                          └──────────┘
┌──────────┐
│ PostgreSQL│
│ 資料庫    │
└──────────┘
Code language: JavaScript (javascript)

todo-app/
├── .env                         ← Supabase 連線資訊（環境變數）
├── package.json
├── vite.config.ts
├── src/
│   ├── main.tsx                 ← 應用入口（Router + Query 初始化）
│   ├── lib/
│   │   └── supabase.ts          ← Supabase Client 初始化
│   ├── types/
│   │   └── database.types.ts    ← 資料庫型別定義（自動生成的）
│   ├── api/
│   │   └── todos.ts             ← CRUD 函式 + Query Options
│   ├── routes/
│   │   ├── __root.tsx           ← 根路由（Layout + Context）
│   │   ├── index.tsx            ← 首頁 /
│   │   ├── login.tsx            ← 登入頁 /login
│   │   └── todos/
│   │       ├── index.tsx        ← 待辦列表 /todos
│   │       └── $todoId.tsx      ← 待辦詳情 /todos/123
│   └── components/
│       ├── TodoList.tsx
│       ├── TodoItem.tsx
│       └── CreateTodoForm.tsx
└── supabase/
    └── migrations/              ← 資料庫 Schema（SQL 檔案）
Code language: PHP (php)

# .env
VITE_SUPABASE_URL=https://abcdefg.supabase.co
VITE_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Code language: PHP (php)

// src/lib/supabase.ts
import { createClient } from '@supabase/supabase-js'
import type { Database } from '../types/database.types'

const supabaseUrl = import.meta.env.VITE_SUPABASE_URL
const supabaseAnonKey = import.meta.env.VITE_SUPABASE_ANON_KEY

export const supabase = createClient<Database>(supabaseUrl, supabaseAnonKey)
Code language: JavaScript (javascript)

-- supabase/migrations/001_create_todos.sql
create table todos (
  id          uuid default gen_random_uuid() primary key,
  user_id     uuid references auth.users(id) not null,
  title       text not null,
  completed   boolean default false,
  created_at  timestamptz default now()
);
Code language: JavaScript (javascript)

-- 啟用 RLS
alter table todos enable row level security;

-- 政策：使用者只能看自己的待辦
create policy "Users can view own todos"
  on todos for select
  using (auth.uid() = user_id);

-- 政策：使用者只能新增自己的待辦
create policy "Users can insert own todos"
  on todos for insert
  with check (auth.uid() = user_id);

-- 政策：使用者只能修改自己的待辦
create policy "Users can update own todos"
  on todos for update
  using (auth.uid() = user_id);

-- 政策：使用者只能刪除自己的待辦
create policy "Users can delete own todos"
  on todos for delete
  using (auth.uid() = user_id);
Code language: JavaScript (javascript)

沒有 RLS 的情況：
  任何人拿到 anon key → 可以讀/寫所有人的資料 → 危險！

有 RLS 的情況：
  任何人拿到 anon key → 可以連線
  但每次操作資料庫時 → PostgreSQL 會檢查：
    「這個請求的使用者是誰？」（auth.uid()）
    「他有權限碰這筆資料嗎？」（user_id 要匹配）
    → 只能碰自己的資料 → 安全！

npx supabase gen types typescript --project-id abcdefg > src/types/database.types.ts

// src/types/database.types.ts（自動生成，不要手動修改）
export interface Database {
  public: {
    Tables: {
      todos: {
        Row: {                           // 讀取時的型別
          id: string
          user_id: string
          title: string
          completed: boolean
          created_at: string
        }
        Insert: {                        // 新增時的型別
          id?: string                    // 有預設值的欄位變成可選
          user_id: string
          title: string
          completed?: boolean
          created_at?: string
        }
        Update: {                        // 更新時的型別
          id?: string                    // 所有欄位都是可選的
          user_id?: string
          title?: string
          completed?: boolean
          created_at?: string
        }
      }
    }
  }
}
Code language: PHP (php)

// src/api/todos.ts
import { supabase } from '../lib/supabase'
import type { Database } from '../types/database.types'

// 從自動生成的型別中取出需要的型別
type Todo = Database['public']['Tables']['todos']['Row']
type TodoInsert = Database['public']['Tables']['todos']['Insert']
type TodoUpdate = Database['public']['Tables']['todos']['Update']

// ===== 查詢（Read）=====
export async function getTodos(status?: 'completed' | 'active') {
  let query = supabase
    .from('todos')           // 從 todos 表
    .select('*')             // 選所有欄位
    .order('created_at', { ascending: false })  // 新的在前

  // 如果有篩選條件
  if (status === 'completed') {
    query = query.eq('completed', true)
  } else if (status === 'active') {
    query = query.eq('completed', false)
  }

  const { data, error } = await query

  if (error) throw error     // 有錯就拋出，讓 TanStack Query 接住
  return data                // 回傳 Todo[]
}

// ===== 查詢單筆（Read）=====
export async function getTodoById(id: string) {
  const { data, error } = await supabase
    .from('todos')
    .select('*')
    .eq('id', id)            // WHERE id = ?
    .single()                // 只要一筆（回傳物件而非陣列）

  if (error) throw error
  return data                // 回傳 Todo
}

// ===== 新增（Create）=====
export async function createTodo(todo: TodoInsert) {
  const { data, error } = await supabase
    .from('todos')
    .insert(todo)            // 插入一筆
    .select()                // 回傳插入後的完整資料
    .single()

  if (error) throw error
  return data
}

// ===== 修改（Update）=====
export async function updateTodo(id: string, updates: TodoUpdate) {
  const { data, error } = await supabase
    .from('todos')
    .update(updates)         // 更新指定欄位
    .eq('id', id)            // WHERE id = ?
    .select()
    .single()

  if (error) throw error
  return data
}

// ===== 刪除（Delete）=====
export async function deleteTodo(id: string) {
  const { error } = await supabase
    .from('todos')
    .delete()                // 刪除
    .eq('id', id)            // WHERE id = ?

  if (error) throw error
}
Code language: JavaScript (javascript)

// src/api/todos.ts（接續上面）
import { queryOptions } from '@tanstack/react-query'

// 列表的 query options
export const todosQueryOptions = (status?: 'completed' | 'active') =>
  queryOptions({
    queryKey: ['todos', 'list', { status }],   // status 不同 → 快取不同
    queryFn: () => getTodos(status),
  })

// 單筆的 query options
export const todoDetailQueryOptions = (todoId: string) =>
  queryOptions({
    queryKey: ['todos', 'detail', todoId],
    queryFn: () => getTodoById(todoId),
  })
Code language: JavaScript (javascript)

// src/components/CreateTodoForm.tsx
import { useMutation, useQueryClient } from '@tanstack/react-query'
import { createTodo } from '../api/todos'

function CreateTodoForm() {
  const queryClient = useQueryClient()

  const mutation = useMutation({
    mutationFn: createTodo,                      // 要執行的函式
    onSuccess: () => {
      queryClient.invalidateQueries({            // 成功後，把列表快取標記為「過期」
        queryKey: ['todos', 'list'],
      })
    },
  })

  const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault()
    const formData = new FormData(e.currentTarget)
    mutation.mutate({                            // 觸發 mutation
      title: formData.get('title') as string,
      user_id: '...',                            // 從認證狀態取得
    })
  }

  return (
    <form onSubmit={handleSubmit}>
      <input name="title" placeholder="新增待辦..." />
      <button
        type="submit"
        disabled={mutation.isPending}            // 送出中時停用按鈕
      >
        {mutation.isPending ? '新增中...' : '新增'}
      </button>
      {mutation.isError && (
        <p>新增失敗：{mutation.error.message}</p>
      )}
    </form>
  )
}
Code language: JavaScript (javascript)

使用者點「新增」按鈕
  ↓
mutation.mutate({ title: '買牛奶' })
  ↓
呼叫 createTodo → Supabase 插入資料
  ↓ 成功
onSuccess 執行
  ↓
invalidateQueries(['todos', 'list'])
  ↓
TanStack Query 自動重新抓取列表 → 畫面更新！
Code language: CSS (css)

// src/components/TodoItem.tsx
import { useMutation, useQueryClient } from '@tanstack/react-query'
import { updateTodo, deleteTodo } from '../api/todos'

function TodoItem({ todo }: { todo: Todo }) {
  const queryClient = useQueryClient()

  // 切換完成狀態
  const toggleMutation = useMutation({
    mutationFn: () => updateTodo(todo.id, { completed: !todo.completed }),
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ['todos'] })
    },
  })

  // 刪除
  const deleteMutation = useMutation({
    mutationFn: () => deleteTodo(todo.id),
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ['todos'] })
    },
  })

  return (
    <li>
      <input
        type="checkbox"
        checked={todo.completed}
        onChange={() => toggleMutation.mutate()}
        disabled={toggleMutation.isPending}
      />
      <span style={{
        textDecoration: todo.completed ? 'line-through' : 'none',
      }}>
        {todo.title}
      </span>
      <button
        onClick={() => deleteMutation.mutate()}
        disabled={deleteMutation.isPending}
      >
        刪除
      </button>
    </li>
  )
}
Code language: JavaScript (javascript)

const toggleMutation = useMutation({
  mutationFn: () => updateTodo(todo.id, { completed: !todo.completed }),

  // 在 API 回應之前就先更新畫面
  onMutate: async () => {
    // 1. 取消正在進行的查詢（避免覆蓋我們的樂觀更新）
    await queryClient.cancelQueries({ queryKey: ['todos', 'list'] })

    // 2. 保存目前的快取（萬一失敗要回復）
    const previousTodos = queryClient.getQueryData(['todos', 'list'])

    // 3. 樂觀更新快取
    queryClient.setQueryData(
      ['todos', 'list'],
      (old: Todo[] | undefined) =>
        old?.map(t =>
          t.id === todo.id
            ? { ...t, completed: !t.completed }   // 先把這筆改掉
            : t
        )
    )

    return { previousTodos }   // 回傳舊資料（給 onError 用）
  },

  // 失敗時回復到之前的狀態
  onError: (_err, _vars, context) => {
    if (context?.previousTodos) {
      queryClient.setQueryData(['todos', 'list'], context.previousTodos)
    }
  },

  // 不管成功失敗，最後都重新抓一次確保資料正確
  onSettled: () => {
    queryClient.invalidateQueries({ queryKey: ['todos', 'list'] })
  },
})
Code language: JavaScript (javascript)

使用者勾選「完成」
  ↓
onMutate 執行（API 還沒回應）
  → 備份舊快取
  → 直接改快取（畫面立刻更新！）
  ↓
同時，API 請求送出...
  ↓
API 成功 → onSettled → invalidate → 重新抓取確認
API 失敗 → onError → 用備份還原快取（畫面回復）
           → onSettled → invalidate → 重新抓取

// src/routes/__root.tsx
import { createRootRouteWithContext, Outlet } from '@tanstack/react-router'
import type { QueryClient } from '@tanstack/react-query'
import { supabase } from '../lib/supabase'
import type { Session } from '@supabase/supabase-js'

interface RouterContext {
  queryClient: QueryClient
  session: Session | null       // 認證狀態也放進 context
}

export const Route = createRootRouteWithContext<RouterContext>()({
  component: () => (
    <div>
      <nav>{/* 導覽列 */}</nav>
      <Outlet />
    </div>
  ),
})
Code language: JavaScript (javascript)

// src/routes/todos/index.tsx
import { createFileRoute } from '@tanstack/react-router'
import { useQuery } from '@tanstack/react-query'
import { z } from 'zod'
import { todosQueryOptions } from '../../api/todos'

// search params 驗證
const todosSearchSchema = z.object({
  status: z.enum(['all', 'completed', 'active']).optional(),
})

export const Route = createFileRoute('/todos/')({
  validateSearch: todosSearchSchema,

  loader: async ({ search, context }) => {
    // 用 search.status 決定要抓什麼資料
    await context.queryClient.ensureQueryData(
      todosQueryOptions(
        search.status === 'all' ? undefined : search.status
      )
    )
  },

  component: TodoListPage,
})

function TodoListPage() {
  const { status } = Route.useSearch()
  const { data: todos } = useQuery(
    todosQueryOptions(status === 'all' ? undefined : status)
  )

  return (
    <div>
      <h1>我的待辦</h1>
      <FilterTabs currentStatus={status} />
      <CreateTodoForm />
      <ul>
        {todos?.map(todo => (
          <TodoItem key={todo.id} todo={todo} />
        ))}
      </ul>
    </div>
  )
}
Code language: JavaScript (javascript)

// src/routes/todos/$todoId.tsx
import { createFileRoute } from '@tanstack/react-router'
import { useQuery } from '@tanstack/react-query'
import { todoDetailQueryOptions } from '../../api/todos'

export const Route = createFileRoute('/todos/$todoId')({
  loader: async ({ params, context }) => {
    await context.queryClient.ensureQueryData(
      todoDetailQueryOptions(params.todoId)
    )
  },
  pendingComponent: () => <div>載入中...</div>,
  errorComponent: ({ error }) => <div>找不到這筆待辦：{error.message}</div>,
  component: TodoDetailPage,
})

function TodoDetailPage() {
  const { todoId } = Route.useParams()
  const { data: todo } = useQuery(todoDetailQueryOptions(todoId))

  return (
    <article>
      <h1>{todo?.title}</h1>
      <p>狀態：{todo?.completed ? '已完成' : '未完成'}</p>
      <p>建立時間：{todo?.created_at}</p>
    </article>
  )
}
Code language: JavaScript (javascript)

// src/routes/login.tsx
import { supabase } from '../lib/supabase'

function LoginPage() {
  const handleEmailLogin = async (email: string, password: string) => {
    const { error } = await supabase.auth.signInWithPassword({
      email,
      password,
    })
    if (error) alert(error.message)
  }

  const handleGoogleLogin = async () => {
    await supabase.auth.signInWithOAuth({
      provider: 'google',
    })
  }

  return (
    <div>
      {/* 帳號密碼登入表單 */}
      {/* Google 登入按鈕 */}
    </div>
  )
}
Code language: JavaScript (javascript)

// src/main.tsx
import { useState, useEffect } from 'react'
import { supabase } from './lib/supabase'
import type { Session } from '@supabase/supabase-js'

function App() {
  const [session, setSession] = useState<Session | null>(null)

  useEffect(() => {
    // 取得目前的 session
    supabase.auth.getSession().then(({ data: { session } }) => {
      setSession(session)
    })

    // 監聽 session 變化（登入、登出、token 更新）
    const { data: { subscription } } = supabase.auth.onAuthStateChange(
      (_event, session) => {
        setSession(session)
      }
    )

    // 元件卸載時取消監聽
    return () => subscription.unsubscribe()
  }, [])

  // 把 session 傳進 Router context
  const router = createRouter({
    routeTree,
    context: { queryClient, session },
  })

  return (
    <QueryClientProvider client={queryClient}>
      <RouterProvider router={router} />
    </QueryClientProvider>
  )
}
Code language: JavaScript (javascript)

// src/routes/todos/index.tsx（加上 beforeLoad）
export const Route = createFileRoute('/todos/')({
  beforeLoad: ({ context }) => {
    if (!context.session) {
      throw redirect({ to: '/login' })     // 沒登入就跳轉到登入頁
    }
  },
  // ... loader, component 等
})
Code language: JavaScript (javascript)

使用者打開 /todos
  ↓
Router 匹配到 /todos 路由
  ↓
beforeLoad 執行
  → 檢查 context.session
  → 有 session → 繼續
  → 沒 session → redirect('/login')
  ↓
loader 執行
  → ensureQueryData(todosQueryOptions)
  → Supabase Client 發出請求時自動帶上 session 的 token
  → RLS 根據 token 裡的 user_id 篩選資料
  ↓
component 渲染 → 只看到自己的待辦
Code language: JavaScript (javascript)

npm run build

dist/
├── index.html          ← 單一 HTML 入口
├── assets/
│   ├── index-abc123.js  ← 打包後的 JavaScript
│   └── index-def456.css ← 打包後的 CSS

# Netlify：在 dist/ 或專案根目錄放一個 _redirects 檔案
/*    /index.html   200
Code language: PHP (php)

// Vercel：vercel.json
{
  "rewrites": [
    { "source": "/(.*)", "destination": "/index.html" }
  ]
}
Code language: JSON / JSON with Comments (json)

VITE_SUPABASE_URL=https://abcdefg.supabase.co
VITE_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIs...
Code language: JavaScript (javascript)

使用者在 /todos 頁面，點了「新增」按鈕
  │
  │  ① React 元件（第 1 篇）
  ↓
CreateTodoForm 的 handleSubmit 執行
  → mutation.mutate({ title: '買牛奶', user_id: '...' })
  │
  │  ② TanStack Query Mutation（第 3 篇 + 本篇）
  ↓
mutationFn 執行 → createTodo()
  → supabase.from('todos').insert(...)
  │
  │  ③ Supabase Client（本篇）
  ↓
請求送到 Supabase（帶著 session token）
  → RLS 檢查：auth.uid() = user_id？ → 通過
  → PostgreSQL 插入資料
  → 回傳新增的資料
  │
  │  ④ Mutation 成功（第 3 篇 + 本篇）
  ↓
onSuccess → invalidateQueries(['todos', 'list'])
  │
  │  ⑤ TanStack Query 自動重新抓取（第 3 篇）
  ↓
getTodos() 重新執行
  → supabase.from('todos').select('*')
  → 回傳更新後的列表
  │
  │  ⑥ React 自動重新渲染（第 1 篇）
  ↓
TodoList 元件更新 → 畫面顯示新的待辦！
Code language: JavaScript (javascript)

┌─────────────────────────────────────────────┐
│                 使用者瀏覽器                    │
│                                             │
│  ┌──────────────┐    ┌──────────────────┐   │
│  │ TanStack     │    │ TanStack Query   │   │
│  │ Router       │    │                  │   │
│  │              │    │ useQuery  快取管理  │   │
│  │ 路由匹配      │───→│ useMutation      │   │
│  │ loader 預取   │    │ invalidate       │   │
│  │ beforeLoad   │    │ optimistic update│   │
│  └──────────────┘    └────────┬─────────┘   │
│                               │              │
│                    Supabase Client           │
│                               │              │
└───────────────────────────────┼──────────────┘
                                │
                                ↓
                    ┌──────────────────┐
                    │    Supabase      │
                    │                  │
                    │  PostgreSQL + RLS│
                    │  Auth            │
                    │  Storage         │
                    └──────────────────┘