Convex Best Practices

確立されたパターンに従い、関数の構成、クエリの最適化、バリデーション、TypeScript の使用方法、エラーハンドリングを実装することで、本番対応の Convex アプリケーションを構築します。

Code Quality

本スキルのすべてのパターンは @convex-dev/eslint-plugin に準拠しています。ビルド時バリデーションのためにインストールしてください:

npm i @convex-dev/eslint-plugin --save-dev

// eslint.config.js
import { defineConfig } from "eslint/config";
import convexPlugin from "@convex-dev/eslint-plugin";

export default defineConfig([
  ...convexPlugin.configs.recommended,
]);

プラグインは 4 つのルールを強制します:

ルール	強制内容
no-old-registered-function-syntax	handler を用いたオブジェクト構文
require-argument-validators	すべての関数で args: {} を要求
explicit-table-ids	db 操作でテーブル名を明示
import-wrong-runtime	Convex ランタイムで Node インポートを禁止

ドキュメント: https://docs.convex.dev/eslint

Documentation Sources

実装前に推測せず、最新ドキュメントを確認してください:

• 主要: https://docs.convex.dev/understanding/best-practices/
• エラーハンドリング: https://docs.convex.dev/functions/error-handling
• Write Conflicts: https://docs.convex.dev/error#1
• より広い文脈については: https://docs.convex.dev/llms.txt

Instructions

The Zen of Convex

1. Convex が難しい部分を管理する - キャッシング、リアルタイム同期、整合性を Convex に任せる
2. 関数が API である - 関数をアプリケーションのインターフェースとして設計する
3. スキーマが真実である - schema.ts でデータモデルを明示的に定義する
4. TypeScript がすべてを満たす - エンドツーエンドの型安全性を活用する
5. クエリはリアクティブである - リクエストではなく、サブスクリプションの観点で考える

Function Organization

Convex 関数をドメインごとに整理します:

// convex/users.ts - ユーザー関連の関数
import { query, mutation } from "./_generated/server";
import { v } from "convex/values";

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

Argument and Return Validation

引数と戻り値の両方に対してバリデータを常に定義してください:

export const createTask = mutation({
  args: {
    title: v.string(),
    description: v.optional(v.string()),
    priority: v.union(v.literal("low"), v.literal("medium"), v.literal("high")),
  },
  returns: v.id("tasks"),
  handler: async (ctx, args) => {
    return await ctx.db.insert("tasks", {
      title: args.title,
      description: args.description,
      priority: args.priority,
      completed: false,
      createdAt: Date.now(),
    });
  },
});

Query Patterns

効率的なクエリのためにフィルタの代わりにインデックスを使用してください:

// インデックス付きスキーマ
export default defineSchema({
  tasks: defineTable({
    userId: v.id("users"),
    status: v.string(),
    createdAt: v.number(),
  })
    .index("by_user", ["userId"])
    .index("by_user_and_status", ["userId", "status"]),
});

// インデックスを使用したクエリ
export const getTasksByUser = query({
  args: { userId: v.id("users") },
  returns: v.array(
    v.object({
      _id: v.id("tasks"),
      _creationTime: v.number(),
      userId: v.id("users"),
      status: v.string(),
      createdAt: v.number(),
    }),
  ),
  handler: async (ctx, args) => {
    return await ctx.db
      .query("tasks")
      .withIndex("by_user", (q) => q.eq("userId", args.userId))
      .order("desc")
      .collect();
  },
});

Error Handling

ユーザー向けエラーに ConvexError を使用してください:

import { ConvexError } from "convex/values";

export const updateTask = mutation({
  args: {
    taskId: v.id("tasks"),
    title: v.string(),
  },
  returns: v.null(),
  handler: async (ctx, args) => {
    const task = await ctx.db.get("tasks", args.taskId);

    if (!task) {
      throw new ConvexError({
        code: "NOT_FOUND",
        message: "Task not found",
      });
    }

    await ctx.db.patch("tasks", args.taskId, { title: args.title });
    return null;
  },
});

Avoiding Write Conflicts (Optimistic Concurrency Control)

Convex は OCC を使用します。以下のパターンに従い、コンフリクトを最小化してください:

// 良い: ミューテーションをべき等にする
export const completeTask = mutation({
  args: { taskId: v.id("tasks") },
  returns: v.null(),
  handler: async (ctx, args) => {
    const task = await ctx.db.get("tasks", args.taskId);

    // 既に完了している場合は早期リターン (べき等)
    if (!task || task.status === "completed") {
      return null;
    }

    await ctx.db.patch("tasks", args.taskId, {
      status: "completed",
      completedAt: Date.now(),
    });
    return null;
  },
});

// 良い: 可能な限り、最初に読み込まずに直接パッチする
export const updateNote = mutation({
  args: { id: v.id("notes"), content: v.string() },
  returns: v.null(),
  handler: async (ctx, args) => {
    // 直接パッチ - ドキュメントが存在しない場合 ctx.db.patch は例外をスロー
    await ctx.db.patch("notes", args.id, { content: args.content });
    return null;
  },
});

// 良い: 独立した並列更新に Promise.all を使用する
export const reorderItems = mutation({
  args: { itemIds: v.array(v.id("items")) },
  returns: v.null(),
  handler: async (ctx, args) => {
    const updates = args.itemIds.map((id, index) =>
      ctx.db.patch("items", id, { order: index }),
    );
    await Promise.all(updates);
    return null;
  },
});

TypeScript Best Practices

import { Id, Doc } from "./_generated/dataModel";

// ドキュメント参照に Id 型を使用
type UserId = Id<"users">;

// フルドキュメントに Doc 型を使用
type User = Doc<"users">;

// Record 型を適切に定義
const userScores: Record<Id<"users">, number> = {};

Internal vs Public Functions

// 公開関数 - クライアントに公開される
export const getUser = query({
  args: { userId: v.id("users") },
  returns: v.union(
    v.null(),
    v.object({
      /* ... */
    }),
  ),
  handler: async (ctx, args) => {
    // ...
  },
});

// 内部関数 - 他の Convex 関数からのみ呼び出し可能
export const _updateUserStats = internalMutation({
  args: { userId: v.id("users") },
  returns: v.null(),
  handler: async (ctx, args) => {
    // ...
  },
});

Examples

Complete CRUD Pattern

// convex/tasks.ts
import { query, mutation } from "./_generated/server";
import { v } from "convex/values";
import { ConvexError } from "convex/values";

const taskValidator = v.object({
  _id: v.id("tasks"),
  _creationTime: v.number(),
  title: v.string(),
  completed: v.boolean(),
  userId: v.id("users"),
});

export const list = query({
  args: { userId: v.id("users") },
  returns: v.array(taskValidator),
  handler: async (ctx, args) => {
    return await ctx.db
      .query("tasks")
      .withIndex("by_user", (q) => q.eq("userId", args.userId))
      .collect();
  },
});

export const create = mutation({
  args: {
    title: v.string(),
    userId: v.id("users"),
  },
  returns: v.id("tasks"),
  handler: async (ctx, args) => {
    return await ctx.db.insert("tasks", {
      title: args.title,
      completed: false,
      userId: args.userId,
    });
  },
});

export const update = mutation({
  args: {
    taskId: v.id("tasks"),
    title: v.optional(v.string()),
    completed: v.optional(v.boolean()),
  },
  returns: v.null(),
  handler: async (ctx, args) => {
    const { taskId, ...updates } = args;

    // undefined 値を削除
    const cleanUpdates = Object.fromEntries(
      Object.entries(updates).filter(([_, v]) => v !== undefined),
    );

    if (Object.keys(cleanUpdates).length > 0) {
      await ctx.db.patch("tasks", taskId, cleanUpdates);
    }
    return null;
  },
});

export const remove = mutation({
  args: { taskId: v.id("tasks") },
  returns: v.null(),
  handler: async (ctx, args) => {
    await ctx.db.delete("tasks", args.taskId);
    return null;
  },
});

Best Practices

• 明示的に指示されない限り npx convex deploy を実行しないこと
• 明示的に指示されない限り git コマンドを実行しないこと
• 関数に対して常に戻り値バリデータを定義すること
• データをフィルタするすべてのクエリにインデックスを使用すること
• ミューテーションをべき等にして、リトライを適切に処理すること
• ユーザー向けエラーメッセージに ConvexError を使用すること
• 関数をドメイン別に整理すること (users.ts, tasks.ts など)
• 機密操作に内部関数を使用すること
• TypeScript の Id 型と Doc 型を活用すること

Common Pitfalls

1. filter の代わりに withIndex を使用する - 常にインデックスを定義し withIndex を使用すること
2. 戻り値バリデータが不足している - 常に returns フィールドを指定すること
3. べき等でないミューテーション - 更新前に現在の状態を確認すること
4. 不必要に読み込んでからパッチする - 可能な限り直接パッチすること
5. null リターンをハンドルしない - ドキュメント ID が存在しない可能性があることを文書化すること

References

• Convex Documentation: https://docs.convex.dev/
• Convex LLMs.txt: https://docs.convex.dev/llms.txt
• Best Practices: https://docs.convex.dev/understanding/best-practices/
• Error Handling: https://docs.convex.dev/functions/error-handling
• Write Conflicts: https://docs.convex.dev/error#1