Deploy to Vercel

Vercel is the recommended platform for deploying Featul. This guide covers deployment setup, configuration, and optimization for production.

Prerequisites

Before deploying to Vercel:

Prepare Database

Provision a PostgreSQL database (recommended: Neon) and obtain the connection string. See Database Setup.

Configure Environment Variables

Prepare all required environment variables. See Environment Variables.

Test Build Locally

bun install
bun run build

Ensure the build completes without errors.

Create Vercel Account

Deployment Methods

Git Integration (Recommended)
Vercel CLI

Deploy automatically from your Git repository:

Connect Repository

Go to vercel.com/new
Import your Git repository (GitHub, GitLab, or Bitbucket)
Select the repository containing Featul

Configure Project

Vercel auto-detects Next.js settings:

Framework Preset: Next.js
Root Directory: apps/app
Build Command: cd ../.. && bun run build --filter=app
Output Directory: apps/app/.next
Install Command: bun install

Set Environment Variables

Add all environment variables from Environment Variables:

# Required
DATABASE_URL=postgresql://...
BETTER_AUTH_SECRET=your-secret-min-32-chars
NEXT_PUBLIC_APP_URL=https://app.yourdomain.com
AUTH_COOKIE_DOMAIN=yourdomain.com
AUTH_TRUSTED_ORIGINS=https://yourdomain.com,https://*.yourdomain.com

# Passkeys
PASSKEY_RP_ID=yourdomain.com
PASSKEY_RP_NAME=Your App Name
PASSKEY_ORIGIN=https://app.yourdomain.com

# Optional: Redis, OAuth, etc.
UPSTASH_REDIS_REST_URL=...
UPSTASH_REDIS_REST_TOKEN=...

Deploy

Click Deploy. Vercel will:

Clone your repository
Install dependencies with Bun
Build all packages in the monorepo
Deploy to production

Deploy from command line:

Install Vercel CLI

npm install -g vercel

vercel login

Configure Project

# From repository root
cd apps/app
vercel

Follow the prompts:

Link to existing project or create new
Set project name
Confirm settings

Set Environment Variables

# Add environment variables
vercel env add DATABASE_URL production
vercel env add BETTER_AUTH_SECRET production
vercel env add NEXT_PUBLIC_APP_URL production
# ... add all required variables

Deploy to Production

vercel --prod

Vercel Configuration

Featul includes a vercel.json configuration file:

{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "bunVersion": "1.x"
}

This tells Vercel to:

Use Bun 1.x for package installation (faster than npm/pnpm)
Follow the OpenAPI schema for validation

Project Settings

Recommended Vercel project settings:

Build Settings

Framework: Next.js
Node.js Version: 20.x
Package Manager: Bun
Build Command: cd ../.. && bun run build --filter=app

Performance

Edge Middleware: Enabled (for subdomain routing)
Image Optimization: Enabled
Caching: Default Next.js caching
Compression: Enabled

Domain Configuration

Featul requires wildcard subdomain support for multi-tenant workspaces.

Add Custom Domain

Add Root Domain

In Vercel project settings:

Go to Settings > Domains
Add your root domain: yourdomain.com
Vercel provides DNS records to configure

Configure DNS

Add these records to your DNS provider:

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

The wildcard * CNAME enables workspace subdomains:

workspace1.yourdomain.com
workspace2.yourdomain.com
etc.

Add Subdomains

In Vercel, add:

app.yourdomain.com (main application)
*.yourdomain.com (wildcard for workspaces)

SSL Certificates

Vercel automatically provisions:

SSL certificate for root domain
Wildcard SSL for *.yourdomain.com

Wait 24-48 hours for DNS propagation and SSL issuance.

Update Environment Variables

After adding custom domain, update:

NEXT_PUBLIC_APP_URL=https://app.yourdomain.com
AUTH_COOKIE_DOMAIN=yourdomain.com
AUTH_TRUSTED_ORIGINS=https://yourdomain.com,https://app.yourdomain.com,https://*.yourdomain.com
PASSKEY_RP_ID=yourdomain.com
PASSKEY_ORIGIN=https://app.yourdomain.com

Database Migrations

Run database migrations before first deployment:

Set Production DATABASE_URL

export DATABASE_URL="postgresql://user:password@host/db?sslmode=require"

Run Migrations

bun run db:migrate

Verify Schema

bun run db:studio

Check that all tables are created.

Migrations must be run manually before deployment. Vercel builds don’t automatically run migrations.

Automated Migrations (Optional)

To run migrations on every deployment, add a build hook:

Automatic migrations can cause issues if migrations fail. Test thoroughly before enabling.

Update package.json build script:

{
  "scripts": {
    "build": "bun run db:migrate && next build"
  }
}

Ensure DATABASE_URL is available at build time:
- Vercel: Add DATABASE_URL to environment variables
- Check “Expose to build” option

Environment-Specific Configuration

Configure different settings for Production, Preview, and Development:

Production
Preview (Staging)
Development

NEXT_PUBLIC_APP_URL=https://app.yourdomain.com
AUTH_COOKIE_DOMAIN=yourdomain.com
PASSKEY_RP_ID=yourdomain.com
POLAR_SERVER=production

NEXT_PUBLIC_APP_URL=https://staging.yourdomain.com
AUTH_COOKIE_DOMAIN=staging.yourdomain.com
PASSKEY_RP_ID=staging.yourdomain.com
POLAR_SERVER=sandbox
DATABASE_URL=postgresql://staging-db...

Preview deployments get unique URLs for each branch/PR:

feature-branch-abc123.vercel.app

NEXT_PUBLIC_APP_URL=http://localhost:3000
AUTH_COOKIE_DOMAIN=localhost
PASSKEY_RP_ID=localhost
POLAR_SERVER=sandbox

Monitoring and Analytics

Vercel Analytics

Enable built-in analytics:

Go to Analytics tab in Vercel dashboard
Enable Web Analytics
Add to apps/app/app/layout.tsx:

import { Analytics } from '@vercel/analytics/react'

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <Analytics />
      </body>
    </html>
  )
}

Sentry Integration

Featul includes Sentry pre-configured in next.config.ts:

# Add to environment variables
SENTRY_AUTH_TOKEN=your-sentry-auth-token

Vercel automatically:

Uploads source maps during build
Tracks errors and performance
Links deployments to Sentry releases

Performance Monitoring

Vercel provides:

Speed Insights: Real user metrics (Core Web Vitals)
Logs: Runtime logs for API routes and functions
Real-time events: Live deployment and request logs

Access in Vercel dashboard under Monitoring.

Optimization Tips

Enable Edge Runtime for Middleware

Middleware (apps/app/src/middleware.ts) automatically runs on Vercel Edge for fast subdomain routing.

Use Incremental Static Regeneration

For public pages (marketing, changelog):

export const revalidate = 3600 // Revalidate every hour

Optimize Images

Vercel Image Optimization is pre-configured in next.config.ts:

images: {
  remotePatterns: [
    { protocol: 'https', hostname: 'lh3.googleusercontent.com' },
    // ... other allowed domains
  ],
}

Configure Caching Headers

For API routes:

export async function GET(request: Request) {
  return new Response(data, {
    headers: {
      'Cache-Control': 'public, s-maxage=60, stale-while-revalidate=120',
    },
  })
}

CI/CD Workflow

Vercel automatically deploys:

Production: Commits to main branch → app.yourdomain.com
Preview: Pull requests → Unique preview URL
Development: Other branches → Preview deployments

GitHub Integration Features

Deployment status checks on PRs
Preview deployment comments on PRs
Automatic rollbacks on failed deployments
Branch protection integration

Troubleshooting

Build Fails: “Command not found”

Error: bun: command not found

Solution: Ensure vercel.json specifies bunVersion:

{ "bunVersion": "1.x" }

Runtime Error: “DATABASE_URL not set”

Solution:

Verify environment variable is set in Vercel
Check it’s enabled for Production environment
Redeploy after adding variable

Subdomain Not Working

Solution:

Verify wildcard DNS record: CNAME * cname.vercel-dns.com
Add *.yourdomain.com in Vercel domains
Wait for DNS propagation (up to 48 hours)
Test with: dig workspace.yourdomain.com

OAuth Redirect Error

Error: redirect_uri_mismatch

Solution: Update OAuth provider callback URLs:

Google: https://app.yourdomain.com/api/auth/callback/google
GitHub: https://app.yourdomain.com/api/auth/callback/github

Next Steps

Environment Variables

Complete environment variable reference

Database Setup

Configure and migrate your database

Cloudflare Deployment

Alternative deployment to Cloudflare

Deployment

Configuration

​Prerequisites

​Deployment Methods

​Vercel Configuration

​Project Settings

Build Settings

Performance

​Domain Configuration

​Add Custom Domain

​Update Environment Variables

​Database Migrations

​Automated Migrations (Optional)

​Environment-Specific Configuration

​Monitoring and Analytics

​Vercel Analytics

​Sentry Integration

​Performance Monitoring

​Optimization Tips

​CI/CD Workflow

​GitHub Integration Features

​Troubleshooting

​Build Fails: “Command not found”

​Runtime Error: “DATABASE_URL not set”

​Subdomain Not Working

​OAuth Redirect Error

​Next Steps

Environment Variables

Database Setup

Cloudflare Deployment

Build docs developers (and LLMs) love

Prerequisites

Deployment Methods

Vercel Configuration

Project Settings

Domain Configuration

Add Custom Domain

Update Environment Variables

Database Migrations

Automated Migrations (Optional)

Environment-Specific Configuration

Monitoring and Analytics

Vercel Analytics

Sentry Integration

Performance Monitoring

Optimization Tips

CI/CD Workflow

GitHub Integration Features

Troubleshooting

Build Fails: “Command not found”

Runtime Error: “DATABASE_URL not set”

Subdomain Not Working

OAuth Redirect Error

Next Steps