convex-tanstack

Convex + TanStack Start

概要

このスキルでは、Convex（リアクティブなバックエンド・アズ・ア・サービス）と TanStack Start（フルスタック React メタフレームワーク）を使用して、リアクティブでリアルタイムなフルスタックアプリケーションを構築するためのガイダンスを提供します。このスタックは、ライブ更新されるクエリ、エンドツーエンドの型安全な開発、SSR のサポート、自動キャッシュ無効化を実現します。

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

• Convex のクエリ、ミューテーション、アクションを実装するとき
• Better Auth 認証を設定またはトラブルシューティングするとき
• TanStack Router のルートとローダーを設定するとき
• スキーマ定義とインデックスを記述するとき
• データ取得パターン（useQuery、useSuspenseQuery）を実装するとき
• ファイルストレージ、スケジューリング、または cron ジョブを扱うとき
• @convex-dev/agent で AI エージェントを構築するとき
• SSR またはハイドレーションの問題をデバッグするとき

クイックリファレンス

必須のインポート

// Data fetching (always use cached version)
import { useQuery } from 'convex-helpers/react/cache'
import { useMutation, useAction } from 'convex/react'

// SSR with React Query
import { useSuspenseQuery } from '@tanstack/react-query'
import { convexQuery } from '@convex-dev/react-query'

// API and types
import { api } from '~/convex/_generated/api'
import type { Id, Doc } from '~/convex/_generated/dataModel'

// Backend functions
import { query, mutation, action } from "./_generated/server"
import { v } from "convex/values"

Skip パターン

フックを条件付きで呼び出さないでください。代わりに "skip" を使用します。

const user = useQuery(api.users.get, userId ? { userId } : "skip")
const org = useQuery(api.orgs.get, user?.orgId ? { orgId: user.orgId } : "skip")

クエリの 3 状態処理

if (data === undefined) return <Skeleton />  // Loading
if (data === null) return <NotFound />       // Not found
return <Content data={data} />               // Success

関数の構文（必ず戻り値バリデーターを含める）

export const getUser = query({
  args: { userId: v.id("users") },
  returns: v.union(
    v.object({ _id: v.id("users"), name: v.string() }),
    v.null()
  ),
  handler: async (ctx, args) => {
    return await ctx.db.get(args.userId)
  },
})

インデックスのベストプラクティス

// Schema - name includes all fields
.index("by_organizationId_status", ["organizationId", "status"])

// Query - fields in same order as index
.withIndex("by_organizationId_status", (q) =>
  q.eq("organizationId", orgId).eq("status", "published")
)

認証チェック（バックエンド）

import { authComponent } from "./auth"

const user = await authComponent.getAuthUser(ctx)
if (!user) throw new Error("Not authenticated")

基本原則

1. 読み取りにはクエリを使用する - クエリはリアクティブで、キャッシュ可能で、一貫性があります
2. 関数を高速に保つ - < 100ms で完了し、数百件未満のレコードを扱います
3. アクションよりクエリ／ミューテーションを優先する - アクションは外部 API 呼び出し専用です
4. 常にインデックスを使用する - .filter() でテーブル全体をスキャンしないでください
5. クライアント状態を最小限にする - Convex のリアルタイム同期を活用します

よくあるアンチパターン

誤り	正しい方法
import { useQuery } from 'convex/react'	import { useQuery } from 'convex-helpers/react/cache'
if (id) useQuery(...)	useQuery(..., id ? {...} : "skip")
.filter(x => x.field === val)	.withIndex("by_field", q => q.eq("field", val))
ctx.db を使うアクション	ctx.runQuery/runMutation を使用する
`count

リファレンスファイル

タスクに応じて適切なリファレンスファイルを読み込みます。

ファイル	使用する場面
references/01-setup.md	プロジェクトのセットアップ、設定ファイル、環境変数
references/02-router.md	ルーターのセットアップ、ルートルート、ファイルベースのルーティング、レイアウト
references/03-auth.md	Better Auth のセットアップ、サインアップ／サインイン／サインアウト、保護されたルート、SSR 認証
references/04-data-fetching.md	useQuery、useSuspenseQuery、ミューテーション、ローダー、プリフェッチ
references/05-backend.md	スキーマ、クエリ、ミューテーション、アクション、内部関数、HTTP エンドポイント
references/06-types.md	TypeScript のパターン、バリデーター、型のマッピング
references/07-storage.md	ファイルのアップロード、ダウンロード、メタデータ、削除
references/08-scheduling.md	scheduler.runAfter、cron ジョブ
references/09-agents.md	AI エージェント、ツール、RAG のセットアップ
references/10-frontend.md	コンポーネントのパターン、読み込み状態、Tailwind/shadcn
references/11-permissions.md	ロール階層、機能アクセスのパターン
references/12-deployment.md	開発コマンド、Convex CLI、Vercel へのデプロイ
references/13-quick-reference.md	インポートのチートシート、一般的なパターンの概要

リファレンスを読み込むタイミング

• 新しいプロジェクトを開始する：01-setup.md を読み込みます
• 認証を追加する：03-auth.md を読み込みます
• バックエンド関数を記述する：05-backend.md を読み込みます
• データ取得を実装する：04-data-fetching.md を読み込みます
• UI コンポーネントを構築する：10-frontend.md を読み込みます
• 構文をすぐに確認する：13-quick-reference.md を読み込みます