convex-component-authoring_skill

Overview

This skill explains how to create, structure, and publish self-contained Convex components with proper isolation, exports, and dependency management. It focuses on component layout, schema and function authoring, integration into consuming apps, and publishing best practices. The guidance is practical and aimed at production-ready, reusable components.

How this skill works

The skill inspects and organizes component files: a convex.config entry, isolated schema tables, server functions (queries, mutations, actions), and a main export surface. It describes how to bundle TypeScript types, optional React hooks, and consumer integration via app.use(component, { name }). It also covers package metadata, build steps, and runtime expectations so consumers can import and call component APIs through the generated app API.

When to use it

• You need reusable, versioned Convex logic that can be shared across projects.
• You want isolated database tables and functions that don’t touch the main app schema.
• You are packaging Convex features (rate limiter, auth hooks, cron jobs) for reuse or OSS distribution.
• You need type-safe public APIs and developer-friendly hooks for consumers.
• You want clear upgrade and dependency rules for Convex-based modules.

Best practices

• Keep component tables isolated — do not reference main app tables from inside the component.
• Export a compact, well-documented API surface (component, functions, types, and hooks).
• Publish with semantic versioning and a build step that emits declarations and compiled code. Include convex.config.ts in files.
• Provide TypeScript types and validators (convex/values) so consumers get compile-time safety.
• Document public functions, args, return shapes, and include usage examples and tests for the component in isolation.

Example use cases

• Rate limiter component providing checkLimit mutation plus schema and indices, consumable by multiple apps.
• Feature-flag or config component that stores app-wide settings isolated from main tables.
• Reusable auth/session component exporting mutations and queries for user records and hooks for React consumers.
• Data enrichment component that exposes queries and background actions (cron/webhook) to keep logic encapsulated.