Quickstart

npm create convex@latest -- --component

This will generate a new template component, with an example app.

Examples

Check out the template’s README for details about the contents and how to make the component your own.

All first-party components are open source, so you can check out their source code to see example patterns.

Examples:

sharded-counter gives an example of attaching a component to an app’s table with a Trigger.
twilio gives an example of defining an HTTP action.
aggregate gives an example of writing tests of a component.
migrations gives an example of defining a function that gets exported by the app.

Anatomy of a Component

A component has functions, tables, file storage, and scheduled functions. A component gets plugged into a Convex app (or into a parent component), which can then access it through its public interface.

src/component/ is the component
- It looks like a convex/ directory would look in a Convex app. Importantly it’s not in the convex/ directory.
- It can have files containing exported functions. Internal functions won’t be accessible outside of the component. Public functions will be accessible to the app, but not from a client, so they behave like the app’s internal functions.
- It can have a schema.ts. These tables are only accessible from within the component.
- It has a _generated directory for auto-generated types, specific to the component’s API and data model.
src/client/ contains a class that runs in the app (or parent component)
- This class has a constructor like new Counter(components.counter), and defines functions that take in arguments like ctx: RunQueryCtx
- Methods of this class call component functions like ctx.runQuery(this.component.public.count)
- This client is optional. The app can call ctx.runQuery(components.counter.public.count) directly. The client library is useful for hiding implementation details and implicit dependencies (see below).
src/react/ can hold React components (no pun intended) for interacting with the Convex component.
- This is entirely optional; many components don't need UI if they're only used on the server.
example/ is an example Convex app for testing the component
In the Convex dashboard, you can select each component to see data, functions, file storage, logs, etc. for each component.