Convex Create Component

Choose the Shape

Ask the user, then pick one path:

Read exactly one reference file before proceeding.

Default Approach

Unless the user explicitly wants an npm package, default to a local component:

• Put it under convex/components/<componentName>/
• Define it with defineComponent(...) in its own convex.config.ts
• Install it from the app's convex/convex.config.ts with app.use(...)
• Let npx convex dev generate the component's own _generated/ files

Component Skeleton

A minimal local component with a table and two functions, plus the app wiring.

// 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', ['userId']),
})

// 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,
    })
  },
})

export const listUnread = query({
  args: { userId: v.string() },
  returns: v.array(
    v.object({
      _id: v.id('notifications'),
      _creationTime: v.number(),
      userId: v.string(),
      message: v.string(),
      read: v.boolean(),
    }),
  ),
  handler: async (ctx, args) => {
    return await ctx.db
      .query('notifications')
      .withIndex('by_user', (q) => q.eq('userId', args.userId))
      .filter((q) => q.eq(q.field('read'), false))
      .collect()
  },
})

// convex/convex.config.ts
import { defineApp } from 'convex/server'
import notifications from './components/notifications/convex.config.js'

const app = defineApp()
app.use(notifications)

export default app

// convex/notifications.ts  (app-side wrapper)
import { v } from 'convex/values'
import { mutation, query } from './_generated/server'
import { components } from './_generated/api'
import { getAuthUserId } from '@convex-dev/auth/server'

export const sendNotification = mutation({
  args: { message: v.string() },
  returns: v.null(),
  handler: async (ctx, args) => {
    const userId = await getAuthUserId(ctx)
    if (!userId) throw new Error('Not authenticated')

    await ctx.runMutation(components.notifications.lib.send, {
      userId,
      message: args.message,
    })
    return null
  },
})

export const myUnread = query({
  args: {},
  handler: async (ctx) => {
    const userId = await getAuthUserId(ctx)
    if (!userId) throw new Error('Not authenticated')

    return await ctx.runQuery(components.notifications.lib.listUnread, {
      userId,
    })
  },
})

Note the reference path shape: a function in convex/components/notifications/lib.ts is called as components.notifications.lib.send from the app.

Critical Rules

• Keep authentication in the app. ctx.auth is not available inside components.
• Keep environment access in the app. Component functions cannot read process.env.
• Pass parent app IDs across the boundary as strings. Id types become plain strings in the app-facing ComponentApi.
• Do not use v.id("parentTable") for app-owned tables inside component args or schema.
• Import query, mutation, and action from the component's own ./_generated/server.
• Do not expose component functions directly to clients. Create app wrappers when client access is needed.
• If the component defines HTTP handlers, mount the routes in the app's convex/http.ts.
• If the component needs pagination, use paginator from convex-helpers instead of built-in .paginate().
• Add args and returns validators to all public component functions.

Patterns

Authentication and environment access

// Bad: component code cannot rely on app auth or env
const identity = await ctx.auth.getUserIdentity()
const apiKey = process.env.OPENAI_API_KEY

// Good: the app resolves auth and env, then passes explicit values
const userId = await getAuthUserId(ctx)
if (!userId) throw new Error('Not authenticated')

await ctx.runAction(components.translator.translate, {
  userId,
  apiKey: process.env.OPENAI_API_KEY,
  text: args.text,
})

Client-facing API

// Bad: assuming a component function is directly callable by clients
export const send = components.notifications.send

// Good: re-export through an app mutation or query
export const sendNotification = mutation({
  args: { message: v.string() },
  returns: v.null(),
  handler: async (ctx, args) => {
    const userId = await getAuthUserId(ctx)
    if (!userId) throw new Error('Not authenticated')

    await ctx.runMutation(components.notifications.lib.send, {
      userId,
      message: args.message,
    })
    return null
  },
})

IDs across the boundary

// Bad: parent app table IDs are not valid component validators