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:.
| Key | Permissions | Where you store it | What uses it |
|---|---|---|---|
| Deploy-only key | Only deployment:deploy | Vercel, as CONVEX_DEPLOY_KEY, Production only | convex deploy in every production build |
| Key for admin tasks | Can set environment variables and run functions | .env.local of a separate checkout on your machine | Step 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:
- Make a separate checkout of your repository and install the dependencies.
Do not use your working checkout: its
.env.localselects your development deployment. Create
.env.localin that checkout with only the key. Never commit this file:.env.local CONVEX_DEPLOY_KEY=prod:your-deployment|your-keySet 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:
{
"$schema": "https://openapi.vercel.sh/vercel.json",
"framework": "nuxtjs",
"buildCommand": "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 buildThe 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
- Import the repository in Vercel. Vercel reads
vercel.jsonand uses the Nitrovercelpreset. The build command invercel.jsonreplaces the build command in the project settings. When you click Deploy, Vercel starts a production build. This first build fails, becauseCONVEX_DEPLOY_KEYdoes not exist yet. The script stops before the Convex deploy, so nothing is released. Step 4 deploys again. - Add your domain,
app.example.com, under Domains. Redirect the*.vercel.appproduction domain to it, because sign-in works only onSITE_URL. - 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.
| Variable | Value | Notes |
|---|---|---|
CONVEX_DEPLOY_KEY | The deploy-only key | Production only. Mark it as Sensitive |
SITE_URL | https://app.example.com | The same value as in Convex |
NUXT_PUBLIC_CONVEX_URL | https://your-deployment.convex.cloud | From the Convex dashboard |
NUXT_PUBLIC_CONVEX_SITE_URL | https://your-deployment.convex.site | Required when you use a custom Convex domain |
BCN_AUTH_PROXY_IP_SECRET | The value from step 1 | Mark it as Sensitive |
BCN_AUTH_TRUSTED_CLIENT_IP_HEADER | x-real-ip | See 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:
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
- 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.
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:ensureSigningKeyin the Convex dashboard. Note the returnedkid. 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
- Open
https://app.example.com/api/auth/jwks. Check that it lists thekidfrom step 4. - Sign up, sign in, reload, and sign out on
https://app.example.com. - Open a page with a live query in two browsers. Change data in one and check that the other updates.
- 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.