Convex Backend Deploys

When to use Convex

SiteKnock's default backend is an Express server with Prisma, deployed as a Docker container. If you prefer a serverless backend instead, you can replace it with a Convex functions project and deploy it directly from Studio without building any container images.

Convex is a hosted platform — your backend functions run on Convex's infrastructure, not in a container you manage. Studio treats Convex as a backend-only hosted PaaS target: it deploys your convex/ functions directory and manages the Convex project and deployment for you.

What you need in your app

A Convex backend lives under apps/<app>-be (or a custom root you configure on the target). Studio detects a Convex backend when any of the following is true:

• apps/<app>-be/Dockerfile exists (the standard Express backend path).
• apps/<app>-be/convex/ directory exists.
• apps/<app>-be/package.json lists convex as a dependency or devDependency.

For a pure Convex backend (no Express server), the minimum structure is:

apps/<app>-be/
  package.json          # must include "convex" as a dependency
  convex/
    schema.ts           # your Convex schema
    myFunctions.ts      # your queries, mutations, actions

Connecting your Convex account

Studio uses shared integration connections to store provider credentials. Before you can deploy to Convex:

1. Open Settings → Integrations in Studio.
2. Add a Convex connection with your account access token. You can generate one from the Convex dashboard under Settings → Access Tokens.
3. Save the connection. Studio validates the token against the Convex API.

See Integrations & Remote for details on managing shared connections.

Setting up a Convex deploy target

In the deployment workspace:

1. Add a target and choose Convex as the orchestrator. The target class is automatically set to Hosted PaaS.
2. Select your Convex connection from the shared connection picker.
3. Load resources — Studio fetches your Convex teams, projects, and deployments from the management API.
4. Choose a team from the dropdown. This is required before deploying.
5. Choose a project (optional) — if you leave this blank, Studio auto-creates a new Convex project named after your app slug and environment.
6. Choose a deployment (optional) — if none exists for the selected project and deployment type, Studio creates one automatically on first deploy.

Custom backend root

If your Convex functions are not under apps/<app>-be, expand the Convex source section on the target and set the Backend root to the relative path from your app root (for example, apps/my-convex-backend). Studio will deploy from that directory instead.

Configuring the environment

Convex targets use split package mode with only the backend service enabled. The frontend service should be disabled — Convex is a backend-only deploy.

Environment variables

Convex-specific variables are set automatically by Studio at deploy time:

Any additional environment variables you add to the backend service in the deployment workspace are passed through to the Convex CLI at deploy time. Use these for secrets your functions need (API keys, third-party tokens, etc.).

Deployment type

Studio infers the Convex deployment type from the environment stage:

You can override this by setting the deployment type explicitly on the target or build override.

How the deploy works

When you trigger a Build & Deploy action on a Convex target, Studio runs two phases:

Phase 1 — Build check

Studio runs a dry-run to typecheck your functions and validate the project without pushing anything:

• Prod deployments: convex deploy --dry-run --typecheck enable
• Dev deployments: convex codegen --dry-run --typecheck enable

If this fails, the deploy stops and the console shows the typecheck or validation errors.

Phase 2 — Deploy

If the build check passes, Studio runs the actual deploy:

• Prod deployments: convex deploy --typecheck enable
• Dev deployments: convex dev --once --tail-logs disable --typecheck enable

Both commands run via pnpm exec convex from your backend root, so the Convex CLI version pinned in your package.json is used.

What Studio does not manage

Convex is a hosted platform, so some operations stay outside Studio:

• Runtime lifecycle — starting, stopping, and restarting Convex services is managed by Convex automatically.
• Logs — Convex dashboard provides real-time logs. Studio does not tail them.
• Plan previews — Docker Compose plan previews are not available for hosted PaaS targets.
• Port mappings, volumes, labels, secrets, and configs — these Docker-specific concepts don't apply to Convex.

Studio focuses on what it can do well: credential resolution, project and deployment provisioning, typechecked builds, and function deploys.

Build overrides

If you use image builds with override mode, you can set Convex team, project, and deployment type at the build level instead of the target level. This lets you deploy the same app to different Convex projects from different environments without duplicating the target.

The override fields for Convex are:

• convexTeamSlug / convexTeamName
• convexProjectSlug / convexProjectName
• convexDeploymentType
• convexDeployment

Next steps