Quickstart

Installation

pnpm add convex @confect/core @confect/server @confect/cli @confect/react

npm install convex @confect/core @confect/server @confect/cli @confect/react

yarn add convex @confect/core @confect/server @confect/cli @confect/react

bun add convex @confect/core @confect/server @confect/cli @confect/react

Usage

Set up your Convex dev deployment

Run convex dev to set up your Convex dev deployment.

Define your database schema

Not every Effect Schema is valid for use in Confect. See Schema Restrictions for more information about what’s permitted and what’s not.

Define a table — one file per table under confect/tables/, where the filename is the table name (so filenames must be valid JS identifiers and may not start with _). Each file must default-export a Table; codegen reads module.default and applies the filename as the table name. From other modules (e.g. specs), default-import the codegen-emitted wrapper at confect/_generated/tables/<name> to reach the table’s derived Schemas (notes.Doc, notes.Fields).

confect/tables/notes.ts

import { Table } from "@confect/server";
import * as Schema from "effect/Schema";

export default Table.make(() =>
  Schema.Struct({
    text: Schema.String,
  }),
);

Codegen will assemble every confect/tables/*.ts into a DatabaseSchema (in confect/_generated/schema.ts) and a Convex deploy SchemaDefinition (in confect/_generated/convexSchema.ts) for you — you never write a confect/schema.ts. It also emits a confect/_generated/id.ts module exporting a type-safe Id constructor (Id("notes")) for cross-table references.

Define your Confect API spec

Create a GroupSpec and add some functions to it.

confect/notes.spec.ts

import { FunctionSpec, GroupSpec } from "@confect/core";
import * as Schema from "effect/Schema";

import { Id } from "./_generated/id";
import notes from "./_generated/tables/notes";

export default GroupSpec.make()
  .addFunction(
    FunctionSpec.publicQuery({
      name: "list",
      args: () => Schema.Struct({}),
      returns: () => Schema.Array(notes.Doc),
    }),
  )
  .addFunction(
    FunctionSpec.publicMutation({
      name: "create",
      args: () => Schema.Struct({ text: Schema.String }),
      returns: () => Id("notes"),
    }),
  );

Run the codegen command

Generate your app’s confect/_generated/ files.

confect codegen

Implement your Confect functions

Create a GroupImpl and implement its functions.

confect/notes.impl.ts

import { FunctionImpl, GroupImpl } from "@confect/server";
import * as Effect from "effect/Effect";
import * as Layer from "effect/Layer";

import databaseSchema from "./_generated/schema";
import { DatabaseReader, DatabaseWriter } from "./_generated/services";
import notes from "./notes.spec";

const list = FunctionImpl.make(databaseSchema, notes, "list", () =>
  Effect.gen(function* () {
    const reader = yield* DatabaseReader;

    return yield* reader
      .table("notes")
      .index("by_creation_time", "desc")
      .collect();
  }).pipe(Effect.orDie),
);

const create = FunctionImpl.make(databaseSchema, notes, "create", ({ text }) =>
  Effect.gen(function* () {
    const writer = yield* DatabaseWriter;

    return yield* writer.table("notes").insert({ text });
  }).pipe(Effect.orDie),
);

export default GroupImpl.make(databaseSchema, notes).pipe(
  Layer.provide(list),
  Layer.provide(create),
  GroupImpl.finalize,
);

GroupImpl.finalize only typechecks once every function declared by the spec has a corresponding FunctionImpl, so it acts as a per-group completeness check.Run confect codegen again to pick up the new impl.

Start your Confect app

Run the confect dev command to generate your app’s Convex functions.

confect dev

In another terminal, run the convex dev command to start your Convex dev deployment.

convex dev

Call your Confect functions from your React app

Set up the Convex React client and provider.

src/main.tsx

import { ConvexProvider, ConvexReactClient } from "convex/react";
import React from "react";
import ReactDOM from "react-dom/client";

import App from "./App";

const convexClient = new ConvexReactClient(import.meta.env.VITE_CONVEX_URL);

ReactDOM.createRoot(document.getElementById("root") as HTMLElement).render(
  <React.StrictMode>
    <ConvexProvider client={convexClient}>
      <App />
    </ConvexProvider>
  </React.StrictMode>,
);

Use Confect’s React hooks alongside your Confect public refs to call your Confect functions.

src/App.tsx

import { QueryResult, useMutation, useQuery } from "@confect/react";
import * as Array from "effect/Array";
import { useState } from "react";

import refs from "../confect/_generated/refs";

const App = () => {
  const notes = useQuery(refs.public.notes.list, {});

  const createNote = useMutation(refs.public.notes.create);

  const [newNote, setNewNote] = useState("");

  return (
    <div>
      <ul>
        {QueryResult.match(notes, {
          onLoading: () => <p>Loading…</p>,
          onSuccess: (notes) =>
            Array.map(notes, (note) => (
              <li key={note._id}>{note.text}</li>
            )),
        })}
      </ul>

      <br />

      <textarea
        rows={4}
        cols={50}
        value={newNote}
        onChange={(e) => setNewNote(e.target.value)}
      />
      <br />
      <button
        onClick={() =>
          void createNote({ text: newNote }).then(() => setNewNote(""))
        }
      >
        Create note
      </button>
    </div>
  );
};

export default App;

Example project

See a full, working example project here.

Getting Started

Concepts

Server

Clients

Guides

Installation

Usage

Example project

​Installation

​Usage

​Example project

Installation

Usage

Example project