Deploy Nuxt to Vercel: environments, secrets, and rollbacks

Deploying Nuxt to Vercel is easy to click through and hard to get right. The usual traps are secrets leaking to the client, preview builds showing up in Google, and a hotfix breaking checkout with no quick way back. Here is the deployment flow we use in our own Nuxt SaaS boilerplate to move from local to preview to production fast, with a clean rollback plan.

Set up environment variables and secrets correctly

Keep client and server config separate

Nuxt exposes variables prefixed with NUXT_PUBLIC_ to the browser. Everything else stays server side. Treat this as a hard rule.

• Client: NUXT_PUBLIC_APP_URL, NUXT_PUBLIC_STRIPE_PUBLISHABLE_KEY, NUXT_PUBLIC_SENTRY_DSN
• Server: DATABASE_URL, STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET, OAUTH_GOOGLE_CLIENT_SECRET, RESEND_API_KEY or SMTP_PASSWORD, S3_SECRET_ACCESS_KEY

Never expose API keys for payments, OAuth, or AI providers on the client. If you need a value in the browser, proxy it through an API route.

Use Vercel’s env scopes

Define variables separately for Development, Preview, and Production. Use test credentials in Preview and real credentials in Production. Typical sets:

• App URLs: NUXT_PUBLIC_APP_URL, NUXT_PUBLIC_API_URL
• Payments: Stripe publishable key, secret key, webhook signing secret
• Auth: OAuth client IDs and secrets for each provider
• Storage: S3 endpoint, bucket name, access key, secret
• Email: SMTP host, username, password or API key for your provider

CLI makes this safe and repeatable:

• vercel env add to create keys
• vercel env pull .env.local to sync to a local file per teammate

Do not commit any .env* files. Rotate secrets in all three scopes and redeploy when you change a key.

Configure Nuxt and Vercel to build the same way

Pin Node and package managers

Use an LTS Node that Vercel supports, and pin it so local, CI, and Vercel match. In package.json:

{
  "engines": { "node": "^18 || ^20" },
  "packageManager": "pnpm@9"
}

Use pnpm install --frozen-lockfile or npm ci to prevent surprise upgrades at build time.

Nuxt settings that avoid surprises

• SSR: Keep SSR on for SaaS. You need protected pages, cookie-based auth, and fast first render.
• Nitro preset: Vercel is auto-detected, but being explicit helps when debugging.

  // nuxt.config.ts
  export default defineNuxtConfig({
    nitro: { preset: 'vercel' }
  })
  

• Serverless awareness: The filesystem is ephemeral and functions can cold start. Store uploads on S3-compatible storage. Keep API handlers short. Offload heavy work to background jobs or scheduled functions.
• Edge vs serverless: Only run pure web APIs at the Edge. Anything using Node libraries, SDKs, or database drivers should run on serverless functions.

Production-like local dev

Use the same env var names locally that you use on Vercel. Run your app with NUXT_PUBLIC_APP_URL=http://localhost:3000 so callback URLs and email links mirror real flows.

Use Preview deployments for QA, payments, and i18n

Every pull request gets its own URL

Vercel creates a unique Preview URL per branch. Treat it like a staging site and run a checklist:

• Auth: sign up, sign in, sign out, password reset, OAuth callback
• Admin: view users, upgrade or cancel a test account, ban a spammer
• Payments: subscribe and cancel with Stripe test cards, verify webhooks end to end
• i18n: switch languages and confirm all strings translate, including emails
• Uploads: create, view, and delete a test file, confirm it lands in your bucket

Keep previews out of search

Block indexing on non-production. You can set an X-Robots-Tag header from server middleware based on Vercel’s environment:

// server/middleware/robots.ts
import { defineEventHandler, setHeader } from 'h3'
export default defineEventHandler((event) => {
if (process.env.VERCEL_ENV !== 'production') {
setHeader(event, 'X-Robots-Tag', 'noindex, nofollow')
}
})

Also disable sitemap generation outside Production. If you use a sitemap or SEO module, guard it with process.env.VERCEL_ENV === 'production'. When you ship to your real domain, publish correct titles, meta descriptions, Open Graph images, and a sitemap.

Verify analytics and email

Send a welcome email, a password reset, and a receipt from Preview. Check SPF, DKIM, and DMARC status in your email provider before launch day. For analytics, confirm page views, signups, and key events appear in your dashboard in both Preview and Production.

Promote to Production safely and keep SEO clean

Lock production settings before traffic

• Payments: swap to live keys and live webhooks in Vercel’s Production scope
• App URL: make sure NUXT_PUBLIC_APP_URL matches the primary domain
• Email: use a verified sending domain with valid SPF, DKIM, DMARC
• Domain: map the custom domain and confirm HTTPS on www and apex

Promote the exact build you tested

Use Vercel’s Promote to Production from a known-good Preview. That removes the risk of a fresh build changing dependencies. After traffic starts, smoke test auth, protected routes, and the admin area. Watch cold starts on first hits to dynamic routes.

Ship more than a landing page on day one

If you use a Nuxt SaaS starter kit, you can launch with auth, billing, i18n, an admin panel, SEO automation, analytics, emails, file storage, and scheduled jobs already wired. That lets you watch real users within hours and refine pricing or onboarding based on data, not guesses.

Monitor, roll back fast, and protect data

Logs, jobs, and user actions

Open Vercel logs right after each deploy. Track signups, activations, and core feature events. If you run scheduled jobs for reports or reminders, confirm they fire on time and complete within function limits.

Rollbacks that do not corrupt data

Rolling back code in Vercel is instant. Data is not. Treat migrations as forward only:

• Run migrations in Preview against a preview database before merging
• Deploy code that can read both old and new columns during the transition
• Use idempotent scripts to backfill data, and monitor them

If a Production deploy misbehaves, promote the last healthy deployment in Vercel and investigate with logs and error tracking before retrying.

Close the loop on revenue and support

Test checkout in Production with a small live plan, then cancel it. Check invoices, receipts, and proration. Ensure the admin can view accounts, issue credits, and ban abuse. After launch, improve your demo videos too. A clear subtitle track lifts retention on product tours. This Video SEO captions that boost watch time: a practical guide covers auto captions for TikTok and YouTube and shows how styled, burned-in subtitles from a web-based AI editor help viewers finish your videos.

Common pitfalls to avoid

• Leaking secrets to the client. Only expose variables with a NUXT_PUBLIC_ prefix.
• Ephemeral storage surprises. Never write user files to the server filesystem. Use S3-compatible storage.
• Indexing preview builds. Add an X-Robots-Tag noindex header and skip sitemaps outside Production.
• Node drift. Pin a single Node LTS across local, CI, and Vercel.
• Long-running AI calls. Add timeouts, retries, and move heavy generation to background jobs.
• One-way migrations. Test on a preview database and deploy in small steps.
• Assuming local equals SSR. QA cookies, protected routes, and OAuth on a real Preview URL.

Key takeaways

• Scope secrets per environment and only expose NUXT_PUBLIC_ vars to the browser.
• Pin Node and make Nuxt’s serverless boundaries explicit for uploads and long tasks.
• Use Vercel Previews to QA auth, payments, emails, i18n, and admin before you ship.
• Promote a tested Preview to Production and keep a known-good rollback target ready.
• Production-ready SEO, analytics, and emails let you learn from real users on day one.