Deploy to Vercel

Overview

Vercel is the recommended deployment target for Next Starter. It provides native Next.js support, automatic preview deployments per pull request, and a dashboard for managing environment variables and custom domains.

Import from GitHub

1. Push your project to a GitHub repository (or GitLab / Bitbucket).
2. Go to vercel.com/new and click Import.
3. Select your repository.
4. Vercel detects Next.js automatically. Leave the framework preset as Next.js and keep the build settings at their defaults.
5. Add all required environment variables before clicking Deploy. The build script runs prisma migrate deploy as part of pnpm build, so DATABASE_URL must be present at build time, not just at runtime.
6. Click Deploy.

Environment Variables

Open your project in the Vercel dashboard, then go to Settings > Environment Variables.

Add each variable from your .env file. The minimum required for a working production deployment:

# Database
DATABASE_URL="postgresql://user:password@host:5432/dbname"
# Optional: if your provider uses a connection pooler (e.g. Neon, Supabase),
# store the direct (non-pooled) connection string here. Not consumed by default —
# prisma.config.ts only reads DATABASE_URL.
DIRECT_DATABASE_URL="postgresql://user:password@host:5432/dbname"

# Better Auth
BETTER_AUTH_SECRET="your-32-character-secret"
BETTER_AUTH_URL="https://yourdomain.com"
NEXT_PUBLIC_BETTER_AUTH_URL="https://yourdomain.com"

# App
PUBLIC_URL="https://yourdomain.com"
NEXT_PUBLIC_APP_NAME="Your App Name"

# Stripe
STRIPE_SECRET_KEY="sk_live_..."
STRIPE_WEBHOOK_SECRET="whsec_..."
STRIPE_PUBLISHABLE_KEY="pk_live_..."

# SMTP2Go
SMTP2GO_API_KEY="your-api-key"
SENDER_EMAIL="noreply@yourdomain.com"

# Cloudflare R2
STORAGE_S3_ENDPOINT="https://<account>.r2.cloudflarestorage.com"
STORAGE_S3_BUCKET="your-bucket"
STORAGE_S3_KEY="your-key-id"
STORAGE_S3_SECRET="your-secret"
STORAGE_S3_REGION="auto"
NEXT_PUBLIC_STORAGE_S3_CDN_URL="https://your-r2-cdn-domain.com"

# Google OAuth
GOOGLE_CLIENT_ID="your-google-client-id"
GOOGLE_CLIENT_SECRET="your-google-client-secret"

# reCAPTCHA (optional)
NEXT_PUBLIC_RECAPTCHA_SITE_KEY="your-site-key"
RECAPTCHA_SECRET_KEY="your-secret-key"

Set variables for the Production, Preview, and Development environments as appropriate. You can use different Stripe test keys and a separate database for Preview environments.

After adding or changing variables, redeploy for the changes to take effect.

Triggering a Redeploy

Any push to your main branch triggers a new production deployment automatically. To redeploy without a code change, go to Deployments, find the latest deployment, and click Redeploy.

Custom Domain

1. In the Vercel dashboard, go to Settings > Domains.
2. Enter your domain name and click Add.
3. Vercel displays the DNS records to add, typically a CNAME for www or an A record for the apex domain.
4. Add those records in your DNS provider's dashboard.
5. Vercel provisions an SSL certificate automatically via Let's Encrypt once DNS propagates.

After the domain is active, update BETTER_AUTH_URL, NEXT_PUBLIC_BETTER_AUTH_URL, and PUBLIC_URL to match your custom domain.

Preview Deployments

Every pull request gets its own preview URL at your-project-git-{branch}-{username}.vercel.app. Use this to review changes before merging to production.

To prevent preview deployments from sending real emails or charging real Stripe customers, set the Preview environment scope to use test credentials:

• Set STRIPE_SECRET_KEY to a sk_test_... key for Preview.
• Point DATABASE_URL at a separate staging database for Preview.
• Use a non-production SMTP2Go sender address.

Recommended Settings

Build & Development Settings

The pnpm build script expands to prisma generate && prisma migrate deploy && next build. Prisma migrations run on every deploy, so DATABASE_URL must be set as a build-time environment variable in Vercel.

Performance

• Enable Edge Network caching. Vercel handles this automatically for static assets.
• Next Starter uses output: "standalone" in next.config.ts. Vercel does not use the standalone output directly; it runs its own optimized build pipeline. This setting exists for Docker deployments and does not interfere with Vercel.

Functions

Next Starter's API routes run as Vercel Serverless Functions by default. If you need longer execution times (for example, large file processing), configure maxDuration in individual route files:

export const maxDuration = 60; // seconds

Stripe Webhooks on Vercel

After deploying, register your production webhook endpoint with Stripe:

1. Go to the Stripe Dashboard > Webhooks.
2. Click Add endpoint.
3. Set the endpoint URL to https://yourdomain.com/api/auth/stripe/webhook.
4. Select the events your app handles. At minimum: customer.subscription.* and invoice.*.
5. Copy the Signing secret and set it as STRIPE_WEBHOOK_SECRET in Vercel.

Redeploy after updating the webhook secret.