Convex クイックスタート

Convex プロジェクトを迅速に立ち上げます。

使用する場合

• Convex で新しいプロジェクトを開始する
• 既存の React、Next.js、Vue、Svelte、またはその他のアプリに Convex を追加する
• プロトタイピング用に Convex アプリをスカフォルディングする

使用しない場合

• プロジェクトに既に Convex がインストールされており、convex/ ディレクトリが存在する場合 - そのまま構築を開始してください
• 既存の Convex アプリに認証を追加するだけの場合 - convex-setup-auth スキルを使用してください

ワークフロー

1. 開始地点を確認：新規プロジェクトか既存アプリか
2. 新規プロジェクトの場合は、テンプレートを選択して npm create convex@latest でスカフォルディングする
3. 既存アプリの場合は、convex をインストールしてプロバイダーを設定する
4. npx convex dev を実行してデプロイメントに接続し、開発ループを開始する
5. セットアップが機能することを確認する

パス 1: 新規プロジェクト（推奨）

公式のスカフォルディングツールを使用します。フロントエンドフレームワーク、Convex バックエンド、およびすべての設定が構成されたプロジェクトを作成します。

テンプレートを選択

テンプレート	スタック
react-vite-shadcn	React + Vite + Tailwind + shadcn/ui
nextjs-shadcn	Next.js App Router + Tailwind + shadcn/ui
react-vite-clerk-shadcn	React + Vite + Clerk auth + shadcn/ui
nextjs-clerk	Next.js + Clerk auth
nextjs-convexauth-shadcn	Next.js + Convex Auth + shadcn/ui
nextjs-lucia-shadcn	Next.js + Lucia auth + shadcn/ui
bare	Convex バックエンドのみ、フロントエンドなし

ユーザーが優先順位を指定していない場合は、シンプルなアプリの場合は react-vite-shadcn、SSR または API ルートが必要なアプリの場合は nextjs-shadcn をデフォルトとします。

GitHub リポジトリをテンプレートとして使用することもできます：

npm create convex@latest my-app -- -t owner/repo
npm create convex@latest my-app -- -t owner/repo#branch

プロジェクトをスカフォルディングする

対話型プロンプトを回避するため、常にプロジェクト名とテンプレートフラグを指定してください：

npm create convex@latest my-app -- -t react-vite-shadcn
cd my-app
npm install

スカフォルディングツールはファイルを作成しますが、npm install は実行しないため、自分で実行する必要があります。

カレントディレクトリにスカフォルディングする場合（ディレクトリが空の場合）：

npm create convex@latest . -- -t react-vite-shadcn
npm install

開発ループを開始する

npx convex dev は長時間実行されるウォッチャープロセスで、保存時にバックエンドコードを Convex デプロイメントに同期します。また、初回実行時に認証が必要です（ブラウザベースの OAuth）。これらの特性により、エージェントが直接実行するのは適切ではありません。

ユーザーに実行してもらうように依頼してください：

ユーザーにターミナルで npx convex dev を実行するよう指示してください。初回実行時にはログインするか匿名で開発するかを促求されます。実行開始後は：

• Convex プロジェクトと開発デプロイメントを作成します
• デプロイメント URL を .env.local に書き込みます
• 生成されたタイプと共に convex/ ディレクトリを作成します
• 変更を監視し、継続的に同期します

npx convex dev を背景で実行し続けておき、コード作業中にしておいてください。ウォッチャーは、convex/ に作成または編集したファイルを自動的に検出します。

例外 - クラウドまたはヘッドレスエージェント： インタラクティブなログイン用にブラウザを開くことができない環境では、Agent Mode（下記参照）を使用して、ユーザーの操作なしに匿名で実行する必要があります。

フロントエンドを開始する

ユーザーは別のターミナルでフロントエンド開発サーバーも実行する必要があります：

npm run dev

Vite アプリは http://localhost:5173 で、Next.js は http://localhost:3000 で実行されます。

取得するもの

スカフォルディング後、プロジェクト構造は次のようになります：

my-app/
  convex/           # バックエンド関数とスキーマ
    _generated/     # 自動生成されたタイプ（git にチェックインしてください）
    schema.ts       # データベーススキーマ（テンプレートに含まれている場合）
  src/              # フロントエンドコード（Next.js の場合は app/）
  package.json
  .env.local        # CONVEX_URL / VITE_CONVEX_URL / NEXT_PUBLIC_CONVEX_URL

テンプレートには既に以下が含まれています：

• アプリルートに接続された ConvexProvider
• フレームワーク用の正しい環境変数名
• Tailwind と shadcn/ui が準備完了（shadcn テンプレートの場合）
• 認証プロバイダーが設定済み（認証テンプレートの場合）

スキーマ、関数、UI の追加に進んでください。

パス 2: 既存アプリに Convex を追加する

ユーザーが既にフロントエンドプロジェクトを持っていて、Convex をバックエンドとして追加したい場合に使用します。

インストール

npm install convex

初期化と開発ループの開始

ユーザーにターミナルで npx convex dev を実行するよう依頼してください。これはログイン、convex/ ディレクトリの作成、デプロイメント URL を .env.local への書き込み、およびファイルウォッチャーの開始を処理します。パス 1 のエージェントがこれを直接実行すべきでない理由についての注記を参照してください。

プロバイダーを設定する

Convex クライアントはアプリのルートでラップする必要があります。セットアップはフレームワークによって異なります。

ConvexReactClient をモジュールスコープで作成します。コンポーネント内では作成しません：

// 悪い例：毎回レンダリング時にクライアントを再作成する
function App() {
  const convex = new ConvexReactClient(
    import.meta.env.VITE_CONVEX_URL as string,
  )
  return <ConvexProvider client={convex}>...</ConvexProvider>
}

// 良い例：モジュールスコープで一度だけ作成される
const convex = new ConvexReactClient(import.meta.env.VITE_CONVEX_URL as string)
function App() {
  return <ConvexProvider client={convex}>...</ConvexProvider>
}

React (Vite)

// src/main.tsx
import { ConvexProvider, ConvexReactClient } from "convex/react"
import { StrictMode } from "react"
import { createRoot } from "react-dom/client"
import App from "./App"

const convex = new ConvexReactClient(import.meta.env.VITE_CONVEX_URL as string)

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <ConvexProvider client={convex}>
      <App />
    </ConvexProvider>
  </StrictMode>,
)

Next.js (App Router)

// app/ConvexClientProvider.tsx
"use client"

import { ConvexProvider, ConvexReactClient } from "convex/react"
import { ReactNode } from "react"

const convex = new ConvexReactClient(process.env.NEXT_PUBLIC_CONVEX_URL!)

export function ConvexClientProvider({ children }: { children: ReactNode }) {
  return <ConvexProvider client={convex}>{children}</ConvexProvider>
}

// app/layout.tsx
import { ConvexClientProvider } from "./ConvexClientProvider"

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>
        <ConvexClientProvider>{children}</ConvexClientProvider>
      </body>
    </html>
  )
}

その他のフレームワーク

Vue、Svelte、React Native、TanStack Start、Remix、およびその他の場合は、対応するクイックスタートガイドに従ってください：

• Vue
• Svelte
• React Native
• TanStack Start
• Remix
• Node.js (フロントエンドなし)

環境変数

環境変数名はフレームワークによって異なります：

フレームワーク	変数
Vite	VITE_CONVEX_URL
Next.js	NEXT_PUBLIC_CONVEX_URL
Remix	CONVEX_URL
React Native	EXPO_PUBLIC_CONVEX_URL

npx convex dev は正しい変数を自動的に .env.local に書き込みます。

エージェントモード（クラウドおよびヘッドレスエージェント）

インタラクティブなブラウザログインが不可能なクラウド環境またはヘッドレスエージェント環境で実行する場合は、CONVEX_AGENT_MODE=anonymous を設定してローカル匿名デプロイメントを使用してください。

.env.local に CONVEX_AGENT_MODE=anonymous を追加するか、インラインで設定します：

CONVEX_AGENT_MODE=anonymous npx convex dev

これは認証を必要とせずに VM 上でローカル Convex バックエンドを実行し、ユーザーの個人開発デプロイメントとの競合を回避します。

セットアップの確認

セットアップ後、すべてが正常に機能していることを確認します：

1. ユーザーが npx convex dev がエラーなしで実行されていることを確認する
2. convex/_generated/ ディレクトリが存在し、api.ts と server.ts が含まれている
3. .env.local にデプロイメント URL が含まれている

最初の関数を書く

プロジェクトが設定されたら、スキーマとクエリを作成して、完全なループが機能することを確認します。

convex/schema.ts:

import { defineSchema, defineTable } from "convex/server"
import { v } from "convex/values"

export default defineSchema({
  tasks: defineTable({
    text: v.string(),
    completed: v.boolean(),
  }),
})

convex/tasks.ts:

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

export const list = query({
  args: {},
  handler: async (ctx) => {
    return await ctx.db.query("tasks").collect()
  },
})

export const create = mutation({
  args: { text: v.string() },
  handler: async (ctx, args) => {
    await ctx.db.insert("tasks", { text: args.text, completed: false })
  },
})

React コンポーネントで使用します（ファイルの場所に基づいてインポートパスを調整してください）：

import { useMutation, useQuery } from "convex/react"
import { api } from "../convex/_generated/api"

function Tasks() {
  const tasks = useQuery(api.tasks.list)
  const create = useMutation(api.tasks.create)

  return (
    <div>
      <button onClick={() => create({ text: "New task" })}>Add</button>
      {tasks?.map((t) => (
        <div key={t._id}>{t.text}</div>
      ))}
    </div>
  )
}

開発と本番環境

開発中は常に npx convex dev を使用してください。個人の開発デプロイメントに対して実行され、保存時にコードを同期します。

出荷の準備ができたら、本番環境にデプロイします：

npx convex deploy

これは本番デプロイメントにプッシュします。本番デプロイメントは開発とは別です。開発中は deploy を使用しないでください。

次のステップ

• 認証を追加：convex-setup-auth スキルを使用します
• スキーマを設計：スキーマドキュメントを参照
• コンポーネントを構築：convex-create-component スキルを使用します
• マイグレーションを計画：convex-migration-helper スキルを使用します
• ファイルストレージを追加：ファイルストレージドキュメントを参照
• Cron ジョブをセットアップ：スケジューリングドキュメントを参照

チェックリスト

• 開始地点を確認：新規プロジェクトか既存アプリか
• 新規プロジェクトの場合：適切なテンプレートを使用して npm create convex@latest でスカフォルディングした
• 既存アプリの場合：convex をインストールしてプロバイダーを設定した
• ユーザーが npx convex dev を実行していて、デプロイメントに接続されている
• convex/_generated/ ディレクトリが存在してタイプを含む
• .env.local にデプロイメント URL がある
• 基本的なクエリ/ミューテーションのラウンドトリップが機能することを確認した