Vercel Deployment

Vercel is the recommended hosting platform for Kit. It provides zero-configuration Next.js deployment, automatic preview environments for every pull request, built-in analytics, and edge network distribution — all optimized for the Next.js App Router that Kit uses.

Prerequisites

Before deploying, make sure you have:

A Vercel account (free tier works for getting started)
Your Kit repository pushed to GitHub
All external services configured (database, Clerk, Lemon Squeezy, etc.)

Complete your local setup and verify all features work with pnpm dev:boilerplate before deploying. Debugging configuration issues is significantly easier in your local environment than in production.

Create a Vercel Project

Connect your repository

Go to vercel.com/new
Select Import Git Repository and choose your Kit repository
Vercel auto-detects the Next.js framework

Configure build settings

Set the following build configuration:

Setting	Value
Framework Preset	Next.js
Build Command	`pnpm build`
Output Directory	`.next` (default)
Install Command	`pnpm install`
Node.js Version	20.x

If you are running Kit inside a monorepo, set Root Directory to apps/boilerplate. Vercel will scope the build to that directory and detect the correct framework.

Deploy

Click Deploy. Vercel runs the build command, bundles your application, and deploys it to a .vercel.app subdomain. The first deployment typically takes 2-3 minutes.

Environment Variables

Configure all required environment variables in the Vercel Dashboard under Settings > Environment Variables. Group them by service:

Core Services

Variable	Service	Required
`DATABASE_URL`	Supabase (pooled connection)	Yes
`DIRECT_URL`	Supabase (direct connection)	Yes
`NEXT_PUBLIC_SUPABASE_URL`	Supabase	Yes
`NEXT_PUBLIC_SUPABASE_ANON_KEY`	Supabase	Yes
`SUPABASE_SERVICE_ROLE_KEY`	Supabase	Yes
`NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY`	Clerk	Yes
`CLERK_SECRET_KEY`	Clerk	Yes
`CLERK_WEBHOOK_SECRET`	Clerk	Yes
`LEMONSQUEEZY_API_KEY`	Lemon Squeezy	Yes
`LEMONSQUEEZY_STORE_ID`	Lemon Squeezy	Yes
`LEMONSQUEEZY_WEBHOOK_SECRET`	Lemon Squeezy	Yes
`RESEND_API_KEY`	Resend	Yes
`RESEND_FROM_EMAIL`	Resend	Yes
`BLOB_READ_WRITE_TOKEN`	Vercel Blob	Yes
`UPSTASH_REDIS_REST_URL`	Upstash Redis	Yes
`UPSTASH_REDIS_REST_TOKEN`	Upstash Redis	Yes

Application Settings

Variable	Purpose	Example
`NEXT_PUBLIC_APP_URL`	Production domain	`https://yourdomain.com`
`ALLOWED_ORIGINS`	CORS whitelist	`https://yourdomain.com`
`CRON_SECRET`	Vercel cron authentication	Random 32+ char string
`COLOR_THEME`	UI color theme	`default`
`NEXT_PUBLIC_PRICING_MODEL`	Pricing mode	`credit_based` or `subscription`

AI Provider Keys (Optional)

Variable	Provider
`OPENAI_API_KEY`	OpenAI
`ANTHROPIC_API_KEY`	Anthropic
`GOOGLE_GENERATIVE_AI_API_KEY`	Google AI
`XAI_API_KEY`	xAI

Enable AI features with feature flags:

Flag	Feature
`NEXT_PUBLIC_AI_LLM_CHAT_ENABLED`	LLM Chat interface
`NEXT_PUBLIC_AI_RAG_CHAT_ENABLED`	RAG Chat with document upload

Vercel supports three environment scopes: Production, Preview, and Development. At minimum, set all variables for the Production scope. For Preview, you can use staging credentials to avoid test data polluting production databases.

Production Configuration

Kit includes two configuration files that Vercel reads automatically during deployment.

Cron Jobs

The vercel.json file defines scheduled tasks that run automatically:

vercel.json — Cron Job Configuration

{
  "crons": [
    {
      "path": "/api/cron/check-trials",
      "schedule": "0 2 * * *"
    },
    {
      "path": "/api/cron/expire-bonus-credits",
      "schedule": "0 3 * * *"
    }
  ]
}

Cron Job	Schedule	Purpose
`/api/cron/check-trials`	Daily at 2:00 AM UTC	Detects expired trial subscriptions and downgrades users
`/api/cron/expire-bonus-credits`	Daily at 3:00 AM UTC	Removes expired bonus credits from user accounts

Both endpoints verify the CRON_SECRET environment variable before executing. Set this to a random string of at least 32 characters in your Vercel environment variables.

Without CRON_SECRET, the cron endpoints reject all requests. Generate a secure value with openssl rand -base64 32 and add it to your Vercel environment variables.

Next.js Configuration

The next.config.mjs includes production-critical settings that apply automatically:

next.config.mjs — Core Production Settings

const nextConfig = {
  pageExtensions: ['js', 'jsx', 'ts', 'tsx'],
  reactStrictMode: true,
  swcMinify: true,

reactStrictMode — Catches common bugs during development, zero overhead in production
swcMinify — Uses the SWC compiler for minification (faster than Terser)
image formats — Serves AVIF and WebP automatically based on browser support

next.config.mjs — Security Headers

// Security Headers
  async headers() {
    return [
      {
        source: '/:path*',
        headers: [
          {
            key: 'X-DNS-Prefetch-Control',
            value: 'on',
          },
          {
            key: 'X-Frame-Options',
            value: 'SAMEORIGIN',
          },
          {
            key: 'X-Content-Type-Options',
            value: 'nosniff',
          },
          {
            key: 'X-XSS-Protection',
            value: '1; mode=block',
          },
          {
            key: 'Referrer-Policy',
            value: 'strict-origin-when-cross-origin',
          },
          {
            key: 'Permissions-Policy',
            value: 'camera=(), microphone=(self), geolocation=(), interest-cohort=(), payment=(), usb=()',
          },
          {
            key: 'Content-Security-Policy',
            value: ContentSecurityPolicy.replace(/\s{2,}/g, ' ').trim(),
          },
        ],
      },
    ]
  },

These security headers are applied to all routes and include Content-Security-Policy, X-Frame-Options, X-Content-Type-Options, and Referrer-Policy. See the Security Overview for details on each header.

Preview Deployments

Every pull request automatically receives its own deployment URL. Vercel creates a unique preview environment with the PR's code, adds a comment to the PR with the preview link, and tears it down when the PR is closed.

Preview deployments are useful for:

Code review — Reviewers can test changes in a real environment before merging
QA testing — Test payment flows, auth flows, and AI features without affecting production
Stakeholder demos — Share a link with non-technical team members

Create a separate set of environment variables for the Preview scope using staging credentials. This prevents test signups, payments, and emails from reaching production services.

Custom Domain

Add your domain

Go to Settings > Domains in your Vercel project and add your domain (e.g., yourdomain.com).

Configure DNS

Add the DNS records Vercel provides. Typically:

Type	Name	Value
`A`	`@`	`76.76.21.21`
`CNAME`	`www`	`cname.vercel-dns.com`

Update environment variables

Set NEXT_PUBLIC_APP_URL to your production domain:

bash

NEXT_PUBLIC_APP_URL=https://yourdomain.com

Also update ALLOWED_ORIGINS to include your domain for CORS:

bash

ALLOWED_ORIGINS=https://yourdomain.com

Update external services

Point webhooks and callback URLs to your production domain:

Clerk — Update the sign-in/sign-up redirect URLs and webhook endpoint
Lemon Squeezy — Update the webhook URL to https://yourdomain.com/api/webhooks/lemonsqueezy
Resend — Verify your domain for email sending

Manual Deployment via CLI

For cases where you need to deploy outside of the GitHub integration (debugging, hotfixes), use the Vercel CLI:

bash

# Install Vercel CLI
pnpm add -g vercel@latest

# Login to Vercel
vercel login

# Deploy to preview
vercel

# Deploy to production
vercel --prod

The CI/CD pipeline uses --archive=tgz to compress files before upload, which avoids rate limits on projects with many files:

bash

vercel deploy --prebuilt --prod --archive=tgz --token=$VERCEL_TOKEN

Troubleshooting

Build fails with missing environment variables

Vercel builds run in a clean environment. Every variable your build process reads must be configured in the Vercel Dashboard. Check the build logs for undefined values and add the missing variables.

Cron jobs not running

Verify vercel.json is in the project root (or the Root Directory you configured)
Confirm CRON_SECRET is set in Production environment variables
Check the Cron tab in Vercel Dashboard to see execution history

Preview deployments not appearing

Ensure the Vercel GitHub integration has access to the repository. Go to Settings > Git in Vercel and verify the connected repository.

Prerequisites

Create a Vercel Project

Connect your repository

Configure build settings

Deploy

Environment Variables

Core Services

Application Settings

AI Provider Keys (Optional)

Production Configuration

Cron Jobs

Next.js Configuration

Preview Deployments

Custom Domain

Add your domain

Configure DNS

Update environment variables

Update external services

Manual Deployment via CLI

Troubleshooting

Build fails with missing environment variables

Cron jobs not running

Preview deployments not appearing

Related