StarterApp Docs
Deployment

Overview

Production deployment strategies

The framework supports multiple deployment platforms: Vercel, Netlify, and AWS. Each platform offers different tradeoffs between simplicity and control.

Pro Tip

Run pnpm validate before deploying. This catches TypeScript errors, test failures, and build issues locally before pushing to production.

Pre-Deployment Validation

Critical Step

Always run full validation before deployment. Skipping this step leads to runtime failures that are harder to debug in production environments.

The framework provides comprehensive validation before deployment:

pnpm validate

This runs all quality gates: formatting (Ultracite), TypeScript type checking, unit tests (Vitest), and production build.

# Lint and format
pnpm lint

# Type check across workspace
pnpm typecheck

# Run test suite
pnpm test

# Build for production
pnpm build

Platform Selection

Deploy to Vercel

Fastest path to production with Git integration, automatic scaling, and instant preview deployments.

Deploy to Netlify

Feature-rich platform with edge functions, form handling, and Next.js optimization plugins.

Deploy to AWS

Enterprise control via Amplify, ECS, or Lambda with full infrastructure customization.

Platform Comparison

PlatformSetupMonorepo SupportBest For
VercelEasyExcellentNext.js apps, rapid iteration
NetlifyModerateGoodEdge functions, forms
AWS AmplifyAdvancedManualEnterprise, compliance needs

Environment Configuration

Production Secret Management

Never commit production secrets to version control. Use platform environment variable dashboards and sync to Convex via CLI for hosted runtime execution.

Production deployments require proper environment variables for database connections, authentication, and third-party services. The framework validates these configurations during deployment, preventing runtime errors from missing variables.

Required Environment Variables

Platform Environment Variables

Configure in your deployment platform dashboard:

# Core Application
APP_BASE_URL=https://your-production-domain.com
DASHBOARD_BASE_URL=https://dashboard.your-domain.com
NEXT_PUBLIC_DASHBOARD_BASE_URL=https://dashboard.your-domain.com

# Authentication (BetterAuth)
BETTER_AUTH_SECRET=<generate with: openssl rand -base64 32>
GOOGLE_CLIENT_ID=<from Google Cloud Console>
GOOGLE_CLIENT_SECRET=<from Google Cloud Console>

# Database (Convex)
NEXT_PUBLIC_CONVEX_URL=https://your-project.convex.cloud
CONVEX_DEPLOYMENT=<production deployment name>

# Billing (UseAutumn)
AUTUMN_SECRET_KEY=am_sk_<your-secret-key>

# Security
ALLOWED_WEB_ORIGINS=https://your-domain.com,https://www.your-domain.com
ENABLE_HSTS=1
HSTS_PRELOAD=0  # Set to 1 only after HSTS preload submission

Convex Runtime Environment

Mirror critical credentials into Convex so BetterAuth and billing run inside the hosted runtime:

npx convex env set APP_BASE_URL https://your-production-domain.com
npx convex env set DASHBOARD_BASE_URL https://dashboard.your-domain.com
npx convex env set ALLOWED_WEB_ORIGINS https://your-domain.com,https://www.your-domain.com
npx convex env set BETTER_AUTH_SECRET <same-value-as-platform>
npx convex env set GOOGLE_CLIENT_ID <same-value-as-platform>
npx convex env set GOOGLE_CLIENT_SECRET <same-value-as-platform>
npx convex env set AUTUMN_SECRET_KEY <same-value-as-platform>

Run these commands for every environment (staging, preview, production) to maintain consistency.

OAuth Provider Configuration

Update your OAuth provider redirect URIs with production domains:

Google Cloud Console:

https://your-domain.com/api/auth/callback/google

GitHub OAuth App:

https://your-domain.com/api/auth/callback/github

Build Configuration for Monorepo

The StarterApp uses a pnpm workspace monorepo with Turbo for build orchestration. Platform-specific configurations:

// vercel.json (optional, auto-detected)
{
  "buildCommand": "cd ../.. && pnpm turbo run build --filter=marketing",
  "installCommand": "pnpm install --frozen-lockfile",
  "framework": "nextjs"
}

Root Directory: apps/marketing or apps/dashboard

# netlify.toml
[build]
  base = "apps/marketing"
  command = "cd ../.. && pnpm turbo run build --filter=marketing"
  publish = "apps/marketing/.next"

[build.environment]
  NODE_VERSION = "20.18.1"
  NPM_FLAGS = "--frozen-lockfile"
# amplify.yml
version: 1
applications:
  - frontend:
      phases:
        preBuild:
          commands:
            - cd ../..
            - npm install -g pnpm@9.12.0
            - pnpm install --frozen-lockfile
        build:
          commands:
            - pnpm turbo run build --filter=marketing
      artifacts:
        baseDirectory: apps/marketing/.next
        files:
          - '**/*'
      cache:
        paths:
          - node_modules/**/*
          - .turbo/**/*
      appRoot: apps/marketing

Post-Deployment Verification

Learn More

Deploy to Vercel

Git-integrated deployment with automatic previews and production optimization.

Deploy to Netlify

Edge functions and form handling with Next.js Essential plugin.

Deploy to AWS

Amplify, ECS, or Lambda deployment with full AWS service integration.

AI-Assisted Deployment

Interactive deployment guidance via AI agent with platform recommendations.

Release Checklist

Security and configuration review before production deploys.

Analytics

Product insights and user behavior tracking with PostHog integration.

AI-Assisted Deployment

Using AI agents for deployment configuration and troubleshooting

On this page

Pre-Deployment ValidationPlatform SelectionPlatform ComparisonEnvironment ConfigurationRequired Environment VariablesPlatform Environment VariablesConvex Runtime EnvironmentOAuth Provider ConfigurationBuild Configuration for MonorepoPost-Deployment VerificationLearn More