Deploying to Vercel

Relevant source files

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

• package.json
• src/App.tsx
• index.html
• README.md
• convex/http.ts
• vercel.json

The TalkCRM project is composed of a React frontend built with Vite and a Convex backend. While the backend is managed by the Convex platform, the frontend application is a standard Vite project that can be built and deployed as a static site on hosting platforms like Vercel. This document outlines the configuration and process for such a deployment.

The deployment process leverages Vercel's automated build system, which installs dependencies, runs the build script defined in package.json, and deploys the resulting static assets. The live application then communicates with the Convex backend for all data operations.

Build Configuration

The build process is primarily defined by the scripts and dependencies in the package.json file. Vercel automatically detects the project as a Vite application and uses the appropriate build commands.

Sources: package.json

Build Scripts

The package.json file contains the necessary scripts for development and building the production application. The build script is the most critical for a Vercel deployment.

Script	Command	Description
dev	npm-run-all --parallel dev:frontend dev:backend	Runs the Vite frontend and Convex backend development servers concurrently.
build	tsc --noEmit && vite build	First, runs the TypeScript compiler to check for type errors without emitting files, then runs Vite to bundle the application for production.
lint	tsc && eslint . --ext ts,tsx ...	Runs the TypeScript compiler and ESLint to check for code quality and errors.

Sources: package.json:6-11

The build command generates a static dist directory containing the index.html, bundled JavaScript, CSS, and other assets. This directory is the target for Vercel's deployment.

Vercel Configuration (vercel.json)

While a vercel.json file was specified for analysis, its contents were not provided in the source files. In its absence, Vercel would use its default settings for a Vite project. A typical vercel.json for this project would look like this to ensure all paths are routed to the main index.html for client-side routing:

{
  "rewrites": [
    {
      "source": "/(.*)",
      "destination": "/index.html"
    }
  ]
}

This configuration is necessary because the application uses client-side routing, as seen in src/App.tsx. Without it, refreshing a page on a path like /terms would result in a 404 error.

Sources: src/App.tsx:10-23

Deployment Flow

The deployment to Vercel is an automated process triggered by a Git push. The flow involves building the static frontend and deploying it to Vercel's CDN, while the application at runtime communicates with the already-deployed Convex backend.

This diagram illustrates the deployment and runtime data flow.

1. Push to Git: A developer pushes code changes to the connected GitHub repository.
2. Trigger Build: Vercel detects the push and starts a new deployment.
3. Install Dependencies: Vercel runs npm install to fetch all project dependencies listed in package.json.
4. Build Application: Vercel executes the npm run build script. Vite bundles the React/TypeScript code into optimized static files.
5. Deploy Assets: The contents of the generated dist directory are uploaded and deployed to Vercel's global CDN.
6. User Request: A user accesses the application URL.
7. Runtime: The browser downloads the static application from Vercel. The React application then runs in the user's browser and makes live queries and mutations to the Convex backend for all dynamic data.

Runtime Architecture

The deployed application is a Single Page Application (SPA). The server's only role is to serve the initial index.html file and its associated static assets.

Client-Side Routing

All navigation within the app is handled on the client side. A custom router useSimpleRouter in src/App.tsx manages the browser's History API to change the URL without making new requests to the server.

// src/App.tsx:10-23
function useSimpleRouter() {
  const [path, setPath] = useState(window.location.pathname);

  useEffect(() => {
    const handlePopState = () => setPath(window.location.pathname);
    window.addEventListener("popstate", handlePopState);
    return () => window.removeEventListener("popstate", handlePopState);
  }, []);

  const navigate = (newPath: string) => {
    window.history.pushState({}, "", newPath);
    setPath(newPath);
  };

  return { path, navigate };
}

This handles paths like /terms and /privacy within the React application itself. This is why the Vercel rewrite rule is important.

Sources: src/App.tsx:10-23, src/App.tsx:34-39

Backend Communication

The frontend deployed on Vercel is decoupled from the backend. All backend logic, database operations, and API endpoints are handled by Convex. The frontend application communicates directly with the Convex deployment URL, which is configured via environment variables.

The architecture diagram in the README.md file clearly separates the "Dashboard (React)" from the "CONVEX" backend, confirming this separation of concerns. The HTTP actions defined in convex/http.ts are part of the Convex backend and are not deployed on Vercel.

Sources: README.md:12-46, convex/http.ts