Deploying to Vercel

You can deploy the full Evolve stack to Vercel as one project: the storefront, the GraphQL gateway, and the domain services. This guide covers the one-time setup and the deploy command. For how the stack maps to Vercel, see Hosting on Vercel.

One-time setup

These steps configure the Vercel project once. They are not part of the deploy command itself.

Link the repository to a Vercel project
Terminal window
```
vercel link
```
This creates a .vercel/ directory linking the working copy to a Vercel project.
Provision Redis

Add Upstash Redis through the Vercel Marketplace integration and connect it to the project for all environments. This sets REDIS_URL.
Set the environment variables

Configure the production and preview environments. Add variables individually with the Vercel CLI:
Terminal window
```
vercel env add CTP_CLIENT_ID production
```
Or bulk-sync the allowlisted variables from your local .env (pulled from 1Password) with the included helper:
Terminal window
```
node scripts/vercel-env-sync.ts
```
Run it with --check to report drift between .env and the Vercel project without writing anything.
Add the registry token

The build installs the private @evolve-framework/* packages, so add the registry token as a build-time secret:
Terminal window
```
vercel env add EVOLVE_NPM_TOKEN production preview
```

Deploy

Deploy the stack
Terminal window
```
task vercel:deploy
```
This generates the gateway’s deploy-time supergraph and then runs vercel deploy --prod. Vercel builds the storefront natively, the gateway, and the domain services, and rolls them out as one atomic deployment.

Pushing to main deploys to production, and opening a pull request creates a full-stack preview deployment.

Verify the deployment

# storefront
curl -sf "$DEPLOY_URL/api/healthcheck"

# gateway, through the public rewrite
curl -sf "$DEPLOY_URL/graphql" \
  -H 'content-type: application/json' \
  --data '{"query":"{ __typename }"}'

The domain services are private and are not reachable directly.

After a schema change

The gateway ships a composed supergraph as a build artifact. After changing a subgraph’s schema, regenerate it so the gateway build stays in sync:

task vercel:supergraph

Local development

The local development workflow with pnpm dev is unchanged. To run the Vercel topology locally with binding environment variables injected, use vercel dev -L (requires Docker).