Skip to main content

Deploy to Vercel

Run the Nuxt application on Vercel and deploy its Convex functions in the same production build.

This guide deploys a Nuxt application with Better Convex Nuxt and authentication to Vercel. Vercel runs Nuxt. Convex runs your functions and data. The example domain is https://app.example.com.

Every production build on Vercel deploys the Convex functions first and then builds Nuxt. If the Convex deploy fails, the build fails, and Vercel keeps the previous release. The frontend never goes live before its Convex functions.

Before you start, the application must sign in and sign out locally. Read Deployment for the general rules.

Convex keys

Create the keys in the Convex dashboard, in the settings of the production deployment. A production deploy key starts with prod:.

KeyPermissionsWhere you store itWhat uses it
Deploy-only keyOnly deployment:deployVercel, as CONVEX_DEPLOY_KEY, Production onlyconvex deploy in every production build
Key for admin tasksCan set environment variables and run functions.env.local of a separate checkout on your machineStep 1 (environment variables), step 4 (signing key)

A deploy-only key cannot set environment variables or run functions. Instead of the key for admin tasks, you can do steps 1 and 4 in the Convex dashboard.

1. Set the Convex environment variables

Set the auth values in the Convex production deployment before the first deploy, so that sign-in works as soon as the release is live. Use the dashboard, or use the key for admin tasks:

  1. Make a separate checkout of your repository and install the dependencies. Do not use your working checkout: its .env.local selects your development deployment.
  2. Create .env.local in that checkout with only the key. Never commit this file:

    .env.local
    CONVEX_DEPLOY_KEY=prod:your-deployment|your-key
  3. Set the values. Generate the proxy secret in this shell, because Vercel needs the same value:

    bash
    export BCN_AUTH_PROXY_IP_SECRET="$(openssl rand -base64 32)"
    pnpm exec better-convex-nuxt convex env set SITE_URL https://app.example.com
    printf '1:%s' "$(openssl rand -base64 32)" | pnpm exec better-convex-nuxt convex env set BETTER_AUTH_SECRETS
    printf '%s' "$BCN_AUTH_PROXY_IP_SECRET" | pnpm exec better-convex-nuxt convex env set BCN_AUTH_PROXY_IP_SECRET

In the dashboard, set the same three variables. Generate a separate value for each secret with openssl rand -base64 32. Enter BETTER_AUTH_SECRETS as 1: followed by its value. Keep the proxy secret, because Vercel needs the same value in step 3.

SITE_URL is your production domain, not a *.vercel.app URL. Convex sets CONVEX_SITE_URL itself as a built-in; do not set it. Add your social provider secrets now, if you use them. See Social sign-in.

2. Add the build script

Add these two files to your repository. vercel.json makes Vercel run the script instead of the default build command:

vercel.json
{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "framework": "nuxtjs",
  "buildCommand": "sh scripts/vercel-build.sh"
}
scripts/vercel-build.sh
#!/usr/bin/env sh
# Vercel build entry point. Production builds deploy the Convex functions
# before building Nuxt, so the frontend never ships ahead of its backend.
# Preview builds deploy no backend and only build the frontend.
#
# This calls the plain Convex CLI on purpose: `better-convex-nuxt convex deploy`
# reads its deployment only from .env.local, which does not exist on Vercel.
# The Convex CLI reads CONVEX_DEPLOY_KEY from the Vercel environment.
set -eu

if [ "${VERCEL_ENV:-}" = "production" ]; then
  case "${CONVEX_DEPLOY_KEY:-}" in
    prod:*) ;;
    *) echo "CONVEX_DEPLOY_KEY must be a production deploy key." >&2; exit 1 ;;
  esac
  pnpm exec convex deploy
fi

pnpm exec nuxt build

The script stops before the deploy when CONVEX_DEPLOY_KEY is not a production deploy key. convex deploy type-checks every file in convex/, tests included. Run tsc -p convex --noEmit in CI, so that a type error fails CI before it fails a production build. See the production checklist.

3. Create the Vercel project

  1. Import the repository in Vercel. Vercel reads vercel.json and uses the Nitro vercel preset. The build command in vercel.json replaces the build command in the project settings. When you click Deploy, Vercel starts a production build. This first build fails, because CONVEX_DEPLOY_KEY does not exist yet. The script stops before the Convex deploy, so nothing is released. Step 4 deploys again.
  2. Add your domain, app.example.com, under Domains. Redirect the *.vercel.app production domain to it, because sign-in works only on SITE_URL.
  3. Add the environment variables below in the project settings, under Environment Variables. There you select the environment of each variable.

Warning: Add CONVEX_DEPLOY_KEY to the Production environment only. A preview build runs the code of any branch. With this key, it could deploy that code to your production Convex deployment.

VariableValueNotes
CONVEX_DEPLOY_KEYThe deploy-only keyProduction only. Mark it as Sensitive
SITE_URLhttps://app.example.comThe same value as in Convex
NUXT_PUBLIC_CONVEX_URLhttps://your-deployment.convex.cloudFrom the Convex dashboard
NUXT_PUBLIC_CONVEX_SITE_URLhttps://your-deployment.convex.siteRequired when you use a custom Convex domain
BCN_AUTH_PROXY_IP_SECRETThe value from step 1Mark it as Sensitive
BCN_AUTH_TRUSTED_CLIENT_IP_HEADERx-real-ipSee the next section

Add the other variables for the Production environment. Vercel passes them to the build and to the server functions. The build needs them, because nuxt.config.ts reads SITE_URL and BCN_AUTH_TRUSTED_CLIENT_IP_HEADER. Vercel passes the variables directly, so the build does not need --dotenv .env.local.

Do not add BETTER_AUTH_SECRETS to Vercel. Only Convex needs it.

Your nuxt.config.ts passes the values to the module:

nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@lupinum/better-convex-nuxt'],
  convex: {
    auth: {
      origin: process.env.SITE_URL,
      trustedClientIpHeader: process.env.BCN_AUTH_TRUSTED_CLIENT_IP_HEADER,
    },
  },
})

Trusted client IP header

Better Auth limits sign-in attempts per client IP. The auth proxy reads the IP from the header in trustedClientIpHeader, signs it, and sends it to Convex. The header must contain exactly one IP address, and clients must not be able to set it.

On Vercel, use x-real-ip. Vercel sets it to the IP address of the client and replaces any value that the client sends. Requests cannot reach your Vercel functions without passing through Vercel, so clients cannot bypass it.

Warning: If you put another proxy or CDN in front of Vercel, x-real-ip contains the address of that proxy. Then every user shares one rate limit. Use the client IP header of that proxy instead, and block requests that do not come through it.

Without the variable, the build fails with auth.trustedClientIpHeader is required outside exact loopback development origins.

4. Deploy and create the signing key

  1. Redeploy the production branch, so that the build reads the new variables. The build log shows the Convex deploy first and the Nuxt build after it.
  2. Create the signing key once, before the first user signs in. Use the key for admin tasks in the separate checkout from step 1:

    bash
    pnpm exec better-convex-nuxt convex run auth:ensureSigningKey '{}'

    You can also run the internal function auth:ensureSigningKey in the Convex dashboard. Note the returned kid. Running the function again returns the same key.

Later releases need no manual step: each production build deploys the changed Convex functions before Nuxt.

5. Check the release

  1. Open https://app.example.com/api/auth/jwks. Check that it lists the kid from step 4.
  2. Sign up, sign in, reload, and sign out on https://app.example.com.
  3. Open a page with a live query in two browsers. Change data in one and check that the other updates.
  4. If you use MCP, connect a host as described in Connect ChatGPT and Claude.

Do not turn on ISR or swr route rules for pages that render signed-in data. A shared cache would show one user's page to another user.

Preview deployments

Preview builds only build Nuxt. The build script deploys Convex only when VERCEL_ENV is production, and CONVEX_DEPLOY_KEY exists only in the Production environment. A preview never deploys to your production Convex deployment.

Every Vercel preview gets its own URL. Better Auth accepts requests only from the exact SITE_URL, so sign-in does not work on a preview URL that differs from it. Choose one of these setups:

A stable staging domain with auth. Assign a domain such as staging.example.com to a staging branch in Vercel. Create a separate Convex project for staging. Deploy its functions from a separate checkout with pnpm exec better-convex-nuxt convex deploy and a production deploy key of the staging project. In Vercel, add Preview environment variables for the staging branch: SITE_URL=https://staging.example.com, the staging Convex URLs, a separate BCN_AUTH_PROXY_IP_SECRET, and BCN_AUTH_TRUSTED_CLIENT_IP_HEADER=x-real-ip. In the staging Convex deployment, set the same SITE_URL, a separate BETTER_AUTH_SECRETS, and the same proxy secret.

Other previews without sign-in. Point their Preview variables at the staging Convex deployment and staging SITE_URL. Pages render, but sign-in fails on those URLs. Protect them with Vercel Deployment Protection.

Never point a preview at the production Convex deployment, and never reuse production secrets. The build script and better-convex-nuxt convex deploy accept only a production deploy key, so use a separate Convex project for staging instead of Convex preview deployments.