Создание компонентов Convex

Создание переиспользуемых компонентов Convex с чёткими границами и минималистичным публичным API.

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

• Создание нового Convex-компонента в существующем приложении.
• Извлечение переиспользуемой бэкенд-логики в компонент.
• Создание сторонней интеграции, которая должна владеть своими таблицами и воркфлоу.
• Упаковка Convex-функциональности для переиспользования в нескольких приложениях.

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

• Разовая бизнес-логика, которая принадлежит основному приложению.
• Тонкие утилиты без таблиц или функций Convex.
• Случаи, когда достаточно обычной TypeScript-библиотеки.

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

1. Спросите пользователя, что он создаёт и какова конечная цель.
2. Выберите форму компонента с помощью дерева решений ниже и прочитайте соответствующий справочный файл.
3. Решите, оправдан ли компонент. Предпочтите обычный код приложения, если функция не нуждается в изолированных таблицах или переиспользуемом состоянии.
4. Составьте краткий план: какие таблицы компонент владеет; какие публичные функции предоставляет; какие данные передаются из приложения (auth, env vars, parent IDs); что остаётся в приложении как обёртки.
5. Создайте структуру компонента с convex.config.ts, schema.ts и файлами функций.
6. Реализуйте функции с использованием собственных импортов ./_generated/server компонента, а не сгенерированных файлов приложения.
7. Подключите компонент в приложение через app.use(...).
8. Вызывайте компонент через components.<name> с помощью ctx.runQuery, ctx.runMutation, ctx.runAction.
9. Запустите npx convex dev и исправьте проблемы codegen, типов или границ.

Выбор формы компонента

Подход по умолчанию

Если нет явного требования npm-пакета — используйте локальный компонент:

• Разместите в convex/components/<componentName>/
• Определите через defineComponent(...) в собственном convex.config.ts
• Установите из convex/convex.config.ts приложения через app.use(...)

Скелет компонента

// convex/components/notifications/convex.config.ts
import { defineComponent } from "convex/server";
export default defineComponent("notifications");

// convex/components/notifications/schema.ts
import { defineSchema, defineTable } from "convex/server";
import { v } from "convex/values";

export default defineSchema({
  notifications: defineTable({
    userId: v.string(),
    message: v.string(),
    read: v.boolean(),
  }).index("by_user_read", ["userId", "read"]),
});

// convex/components/notifications/lib.ts
import { v } from "convex/values";
import { mutation, query } from "./_generated/server.js";

export const send = mutation({
  args: { userId: v.string(), message: v.string() },
  returns: v.id("notifications"),
  handler: async (ctx, args) => {
    return await ctx.db.insert("notifications", {
      userId: args.userId,
      message: args.message,
      read: false,
    });
  },
});

// convex/convex.config.ts
import { defineApp } from "convex/server";
import notifications from "./components/notifications/convex.config";

const app = defineApp();
app.use(notifications);
export default app;

Ключевые правила

• Компоненты используют собственные _generated/server импорты, не импорты приложения.
• Для доступа React-клиентов или HTTP-вызывателей создайте обёртки в приложении — не выставляйте функции компонента напрямую.
• Запускайте npx convex dev и исправляйте проблемы codegen и типов перед завершением.