Convex Quickstart

Быстрый запуск рабочего проекта на Convex.

Когда использовать

• Старт нового проекта с Convex.
• Добавление Convex в существующее приложение на React, Next.js, Vue, Svelte и других фреймворках.
• Скаффолдинг Convex-приложения для прототипирования.

Когда НЕ использовать

• Проект уже имеет Convex и директорию convex/ — просто начните разработку.
• Нужно только добавить аутентификацию в существующее Convex-приложение — используйте навык convex-setup-auth.

Рабочий процесс

1. Определить отправную точку: новый проект или существующее приложение.
2. Для нового проекта: выбрать шаблон и сделать скаффолдинг через npm create convex@latest.
3. Для существующего приложения: установить convex и подключить провайдер.
4. Запустить npx convex dev --once для provisioning локального деплоя, пуша кода, typechecking и генерации типов за один шаг.
5. Запустить npm run dev (шаблоны Convex объединяют watcher и frontend в одну команду).
6. Убедиться, что настройка работает.

Путь 1: новый проект (рекомендуется)

Выбор шаблона

По умолчанию используйте react-vite-shadcn для простых приложений или nextjs-shadcn для SSR или API routes.

Скаффолдинг проекта

Всегда передавайте имя проекта и флаг шаблона, чтобы избежать интерактивных подсказок:

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

Для скаффолдинга в текущей директории (если она пустая):

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

Provisioning деплоя и пуш кода

# Рекомендуемый способ (явный режим агента)
CONVEX_AGENT_MODE=anonymous npx convex dev --once

В non-TTY окружении (стандарт для большинства запусков агентов) это: создаёт анонимный локальный Convex бэкенд; записывает CONVEX_DEPLOYMENT и *_CONVEX_URL в .env.local; генерирует convex/_generated/; пушит текущий код convex/, типчекает его и валидирует схему.

Путь 2: добавление Convex в существующее приложение

1. Установить пакет: npm install convex
2. Инициализировать: npx convex dev --once для provisioning деплоя и генерации типов.
3. Подключить ConvexProvider в корневой компонент:

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

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

export default function App() {
  return (
    <ConvexProvider client={convex}>
      <YourApp />
    </ConvexProvider>
  );
}

Запуск для разработки

После provisioning запустите watcher для автоматического пуша изменений:

npx convex dev

Если шаблон определяет скрипт predev — он запускает одноразовую настройку. Используйте его вместе с convex dev --once:

npm run predev  # только один раз
npx convex dev  # watcher

Проверка настройки

• Файл .env.local содержит CONVEX_DEPLOYMENT и URL.
• Директория convex/_generated/ существует.
• Команда npx convex dev --once завершается без ошибок.
• Frontend успешно загружается и подключается к Convex бэкенду.