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

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

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

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

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

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

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

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

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

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

Цель	Форма	Справочник
Компонент только для этого приложения	Local	`references/local-components.md`
Публикация или общий доступ из нескольких приложений	Packaged	`references/packaged-components.md`
Явно нужен local + shared library код	Hybrid	`references/hybrid-components.md`
Не уверен	Local (по умолчанию)	`references/local-components.md`

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

Если нет явного требования 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 и типов перед завершением.

convex-create-componentкомпоненты Convex с изоляцией

Установка