Packages

Understanding Confect’s modular package architecture

Confect is organized into five core packages, each serving a specific purpose in the development lifecycle. This modular design allows you to use only what you need and understand the boundaries between different parts of the framework.

Package Overview

@confect/core

Shared specs and schemas used by all packages

@confect/server

Backend bindings to the Convex platform

@confect/react

Client-side bindings for React applications

@confect/cli

Developer tooling for codegen and sync

@confect/test

Testing utilities for Confect applications

@confect/core

Description: Shared specs and schemas used by all Confect packages

When to use: Always required. This is the foundation package that defines the spec/impl model and schema types.

Key Exports

• FunctionSpec - Define function specifications (queries, mutations, actions)
• GroupSpec - Organize functions into logical groups
• Spec - Top-level specification container
• GenericId - Type-safe document IDs
• SystemFields - Convex system fields (_id, _creationTime)
• UserIdentity - User authentication types
• Refs - Type-safe function references

Dependencies

package.json

{
  "peerDependencies": {
    "convex": "^1.30.0",
    "effect": "^3.19.16"
  }
}

@confect/core has no production dependencies - only peer dependencies on convex and effect.

@confect/server

Description: Backend bindings to the Convex platform

When to use: Required for implementing Convex functions (queries, mutations, actions) with Confect.

Key Exports

• Impl - Implementation layer that connects specs to handlers
• FunctionImpl - Individual function implementations
• GroupImpl - Group-level implementations
• DatabaseReader - Effect service for reading from the database
• DatabaseWriter - Effect service for writing to the database
• DatabaseSchema - Define database schemas with Effect schemas
• Table - Table definitions with schema validation
• Auth - Authentication service
• Storage - File storage services
• Scheduler - Schedule functions for later execution
• Handler - Function handler types
• RegisteredFunctions - Export Convex-compatible functions

Dependencies

package.json

{
  "peerDependencies": {
    "@confect/core": "workspace:*",
    "@effect/platform": "^0.94.5",
    "@effect/platform-node": "^0.104.1",
    "convex": "^1.30.0",
    "effect": "^3.19.16"
  }
}

Use the /node export for Node.js-specific actions that need access to Node APIs.

@confect/react

Description: Client-side bindings for React applications

When to use: Required for React applications that need to call Confect functions.

Key Features

• Type-safe hooks generated from your specs
• Automatic encoding/decoding of Effect schemas
• Seamless integration with Convex’s React client

Dependencies

package.json

{
  "peerDependencies": {
    "@confect/core": "workspace:*",
    "convex": "^1.30.0",
    "effect": "^3.19.16",
    "react": "^18.0.0 || ^19.0.0"
  }
}

@confect/react supports both React 18 and React 19.

@confect/cli

Description: Developer tooling for codegen and sync

When to use: Required during development to generate type-safe APIs and sync your specs.

Key Features

• Automatic code generation from specs
• Generates type-safe function references
• Generates Effect services for database access
• Syncs specs with implementations
• Watches for changes during development

Usage

# Generate code and watch for changes
confect dev

# One-time code generation
confect codegen

Generated Files

The CLI generates files in confect/_generated/:

• api.ts - Type-safe API object for Convex functions
• refs.ts - Type-safe function references
• services.ts - Effect service types (DatabaseReader, DatabaseWriter)
• registeredFunctions.ts - Registry of all functions

Dependencies

package.json

{
  "dependencies": {
    "@effect/cli": "^0.73.2",
    "@effect/platform-node": "0.104.1",
    "@effect/printer": "^0.47.0",
    "@effect/printer-ansi": "^0.47.0",
    "code-block-writer": "^13.0.3",
    "esbuild": "^0.27.3"
  },
  "peerDependencies": {
    "@confect/core": "workspace:*",
    "@confect/server": "workspace:*",
    "@effect/platform": "^0.94.5",
    "effect": "^3.19.16"
  }
}

@confect/test

Description: Utilities for testing Confect applications without a live Convex backend

When to use: Use in your test files to test Confect functions in isolation.

Key Features

• Mock Convex backend for testing
• Test functions without deploying to Convex
• Fast unit tests for business logic

Dependencies

package.json

{
  "peerDependencies": {
    "@confect/core": "workspace:*",
    "@confect/server": "workspace:*",
    "convex": "^1.30.0",
    "convex-test": "^0.0.38",
    "effect": "^3.19.16"
  }
}

@confect/test requires convex-test as a peer dependency. Make sure to install it in your devDependencies.

Installing Packages

In a typical Confect project, your package.json will include:

package.json

{
  "dependencies": {
    "@confect/cli": "^2.0.0",
    "@confect/core": "^2.0.0",
    "@confect/react": "^2.0.0",
    "@confect/server": "^2.0.0",
    "@effect/platform": "^0.94.5",
    "convex": "^1.32.0",
    "effect": "^3.19.19"
  },
  "devDependencies": {
    "@confect/test": "^2.0.0",
    "convex-test": "^0.0.41"
  }
}

Next Steps

Project Structure

Learn how to organize your Confect project

Spec-Impl Model

Understand the separation between specs and implementations