> ## Documentation Index
> Fetch the complete documentation index at: https://getoverlay.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Convex Workflow

> How to update Convex safely for Overlay Web changes.

Convex owns durable app state, domain mutations, scheduled work, and some webhook processing. The web app depends on Convex for conversations, files, memory, projects, billing state, and related data.

When a change touches `convex/`, push both deployments before considering the web app verified:

```bash theme={null}
npm run convex:push:all
```

Do not pass `.env.local` to production Convex deploys. Use the dedicated scripts so production and development deployments receive the right environment.

## Development backend

For local web work against the development Convex backend:

```bash theme={null}
npm run dev:with-convex
```

This runs the development push first, then starts Next.js.

## Production backend

Use the production script when intentionally deploying production Convex changes:

```bash theme={null}
npm run convex:push:prod
```

Use the development script for dev-only backend updates:

```bash theme={null}
npm run convex:push:dev
```

## Import boundary

Convex code may import browser-safe shared modules from `src/shared`. Convex must not import `src/server`, because server-only modules can break Convex bundling.