Deployment & Build Process
Relevant source files
The following files were used as context for generating this wiki page:
The TREAD Talks platform utilizes a dual-layered deployment strategy involving Next.js for the frontend and Convex for the backend database and server-side functions. The build process orchestrates these layers to ensure that backend schemas and data exist before the frontend attempts to prerender routes.
Sources: README.md:1-5, scripts/vercel-build.sh:3-7
Build Orchestration
The project uses pnpm as its primary package manager. The build pipeline differs significantly between production and preview environments to accommodate dynamic backend requirements.
Vercel Build Script
The scripts/vercel-build.sh script acts as the entry point for Vercel deployments. It manages environment-specific logic, particularly for Convex backend provisioning.
- Environment Check: The script identifies the
VERCEL_ENV. If the environment is notpreview, it executes a standardpnpm build. - Preview Backend Provisioning: For preview builds, the script creates a branch-specific Convex backend. It replaces slashes in the git branch name with hyphens to create a valid
preview_name. - Deployment Sequence: It runs
convex deployto initialize the backend. This command provides theNEXT_PUBLIC_CONVEX_URLrequired by the frontend. - Data Seeding: Before running the Next.js build, the script executes
internal.preview.seedPreview. This ensures that prerendered routes (like the homepage) have access to fixture talks and speakers, preventing empty states during the build phase.
Sources: scripts/vercel-build.sh:23-74, package.json:11-12, AGENTS.md:5
Build Flow Diagram
The following diagram illustrates the logic branches within the build script.
This diagram shows the conditional execution paths for production versus preview deployments. Sources: scripts/vercel-build.sh:23-74
Environment Configuration
The application maps Vercel environment variables to internal deployment constants to standardize behavior across monitoring tools like Sentry.
Standardized Environments
Vercel Variable (NEXT_PUBLIC_VERCEL_ENV) | Internal DEPLOY_ENV | Purpose |
|---|---|---|
production | prod | Live user-facing environment |
preview | dev | Pull request and staging environments |
| (None / Local) | local | Development on local machine |
Sources: src/constants/env.ts:18-34
Convex Production Deployment
While preview environments are automated via the build script, production backend changes are typically shipped using the release script, which executes convex deploy --yes.
Sources: package.json:23-24
Backend Function Deployment
Convex backend functions (queries, mutations, and actions) must follow specific registration and deployment rules to maintain stability.
Index Backfilling
When deploying schema changes that include new indexes on large tables, the deployment will block until the backfill completes. Developers should use the staged: true flag to declare indexes that backfill asynchronously without blocking the deployment.
Sources: convex/_generated/ai/guidelines.md:120-123
Function Deployment Architecture
The interaction between the Vercel build environment and the Convex runtime during deployment follows this sequence:
This sequence ensures backend resources are available before the frontend tries to consume them during the build process. Sources: scripts/vercel-build.sh:42-74
Development Workflow
Local development requires running Next.js and Convex in parallel. The pnpm dev command orchestrates three concurrent processes:
dev:backend: Runsconvex devfor local database sync.dev:frontend: Runsnext devwith experimental HTTPS.dev:open: Waits for the local server and opens the browser.
Sources: package.json:14-17, README.md:38-48
Summary
The build process is centered on the vercel-build.sh script, which guarantees that Convex backend instances are correctly provisioned and seeded for preview environments. This synchronization prevents build-time failures during Next.js static generation and ensures that every pull request has a fully functional, isolated backend environment.