Deployment to Vercel & Convex

Relevant source files

The following files were used as context for generating this wiki page:

• vercel.json
• README.md
• AGENTS.md
• package.json
• vite.config.ts
• convex/README.md

The DreamCats project utilizes a dual-platform deployment strategy to manage its frontend and backend components. Vercel serves as the primary hosting provider for the React-based frontend and PWA assets, while Convex provides the serverless backend infrastructure for real-time database operations, game logic, and state synchronization.

This deployment architecture ensures that backend functions—including queries and mutations—are synchronized with frontend builds. The project uses a unified deployment command that triggers the Convex function deployment before initiating the Vite production build, ensuring API compatibility between the client and server.
Sources: README.md:1-20, AGENTS.md:1-20

Build Configuration and Environment

The project relies on specific environment variables and scripts to orchestrate the deployment process across Vercel and Convex.

Environment Variables

For successful deployment, the following variables must be configured in the deployment environment (e.g., Vercel Project Settings):

Variable	Description	Source
CONVEX_DEPLOYMENT	The unique name of your Convex deployment (e.g., dev:project-name).	README.md:104
CONVEX_URL	The URL of the Convex deployment (e.g., https://name.convex.cloud).	README.md:105
VITE_CONVEX_URL	The client-side variable used by Vite to connect to the Convex backend.	AGENTS.md:32

Build Pipeline

The deployment pipeline is defined in vercel.json. It overrides default Vercel behavior to ensure the backend is deployed first.

{
  "buildCommand": "npx convex deploy --cmd 'bun run build'",
  "installCommand": "bun install",
  "outputDirectory": "dist",
  "framework": "vite"
}

Sources: vercel.json:1

The npx convex deploy command with the --cmd flag ensures that Convex functions are updated and pushed to the cloud before the bun run build command (which executes tsc -b && vite build) generates the production assets.
Sources: AGENTS.md:13, package.json:13

Vercel Frontend Deployment

Vercel handles the distribution of the React frontend and PWA assets. The configuration in vite.config.ts optimizes the build for production performance and caching.

PWA and Asset Management

The project uses vite-plugin-pwa to manage offline capabilities and manifest generation. On Vercel, specific headers and rewrites are applied to ensure efficient asset delivery.

• Caching: Assets under /assets/ are served with a Cache-Control header of public, max-age=86400, must-revalidate.
• Rewrites: All requests to /assets/(.*) are routed to the corresponding destination to maintain PWA integrity.
• Optimization: The build process uses manual chunks to separate React, UI primitives, and Convex logic into distinct files.

Sources: vercel.json:1, vite.config.ts:100-120

Build Process Flow

The following diagram illustrates the sequence of operations during a Vercel deployment:

The diagram shows how the Convex deployment wraps the frontend build to ensure backend readiness.
Sources: vercel.json:1, package.json:13, AGENTS.md:13

Convex Backend Deployment

Convex serves as the authoritative backend. Deployment involves pushing the contents of the convex/ directory, which contains the database schema and server-side functions.

Manual Deployment

While Vercel automates this, developers can manually deploy backend changes using the CLI:

export CONVEX_DEPLOYMENT=dev:your-project-name
npx convex deploy

Sources: README.md:111-114

Data Flow Architecture

Convex handles real-time synchronization between clients. The deployment architecture supports queries for reading data and mutations for writing/modifying state.

The sequence shows the interaction between the Vercel-hosted frontend and the Convex backend.
Sources: convex/README.md:7-60

Summary of Deployment Components

Component	Technology	Role
Frontend Hosting	Vercel	Serves the production dist/ folder and handles edge routing.
Backend Provider	Convex	Hosts serverless functions, database schema, and handles real-time state.
Build Orchestrator	Convex CLI	Coordinates backend deployment with the frontend Vite build.
Package Manager	Bun	Used for installing dependencies and running build scripts.

Sources: README.md:40-60, package.json:1-15, vercel.json:1

Deployment of the DreamCats project is an integrated process where Vercel manages the web interface and PWA features, while Convex provides the underlying real-time game infrastructure. The configuration ensures that both layers remain in sync through a coordinated build pipeline.