Skip to main content
Vercel provides seamless deployment for Evidence apps with automatic builds, preview deployments, and global CDN distribution.

​
Prerequisites

  • An Evidence project in a Git repository (GitHub, GitLab, or Bitbucket)
  • A Vercel account
  • Your data sources configured and tested locally

​
Deployment Steps

1
Push Your Project to Git
2
Ensure your Evidence project is committed to a Git repository:
3
git init
git add .
git commit -m "Initial commit"
git remote add origin <your-repository-url>
git push -u origin main
4
Import to Vercel
5
  • Log in to Vercel
  • Click Add New > Project
  • Import your Git repository
  • Authorize Vercel to access your repositories
  • Select your Evidence repository
    • 6
    Configure Project Settings
    7
    Vercel will auto-detect your framework. Configure the build settings:
    8
    SettingValueFramework PresetOtherBuild Commandnpm run sources && npm run buildOutput DirectorybuildInstall Commandnpm install
    9
    vercel.json
    {
  "buildCommand": "npm run sources && npm run build",
  "outputDirectory": "build",
  "installCommand": "npm install"
}
    10
    Add Environment Variables
    11
    If your data sources require credentials:
    12
  • In Vercel, go to Settings > Environment Variables
  • Add your variables for all environments (Production, Preview, Development)
  • Use the EVIDENCE_ prefix for Evidence-specific variables
    • 13
    Example variables:
    14
  • EVIDENCE_SOURCE__[datasource]__host
  • EVIDENCE_SOURCE__[datasource]__database
  • EVIDENCE_SOURCE__[datasource]__user
  • EVIDENCE_SOURCE__[datasource]__password
    • 15
    Never commit credentials to Git. Always use environment variables for sensitive information.
    16
    Deploy
    17
    Click Deploy. Vercel will:
    18
  • Clone your repository
  • Install dependencies
  • Run npm run sources to query your data
  • Run npm run build to generate the static site
  • Deploy to Vercel’s global CDN

    • ​
    Configuration Options

    ​
    Custom Domain

    To add a custom domain:
    1. Go to Settings > Domains
    2. Click Add
    3. Enter your domain name
    4. Configure DNS records as instructed

    ​
    Build Settings Override

    Create a vercel.json file in your project root: 
    {
  "buildCommand": "npm run sources && npm run build",
  "outputDirectory": "build",
  "installCommand": "npm install",
  "framework": null,
  "env": {
    "NODE_OPTIONS": "--max-old-space-size=4096"
  }
}

    ​
    Redirects and Rewrites

    Add redirects to your vercel.json: 
    {
  "redirects": [
    {
      "source": "/old-page",
      "destination": "/new-page",
      "permanent": true
    }
  ],
  "headers": [
    {
      "source": "/(.*)",
      "headers": [
        {
          "key": "X-Frame-Options",
          "value": "DENY"
        }
      ]
    }
  ]
}

    ​
    Preview Deployments

    Vercel automatically creates preview deployments for:
    • Every push to a branch
    • Every pull request
    Preview URLs are unique and allow you to test changes before merging to production.

    ​
    Continuous Deployment

    Vercel automatically deploys your site when you push to your repository: 
    git add .
git commit -m "Update reports"
git push
    Monitor deployment status in the Vercel dashboard.

    ​
    Using Vercel CLI

    Deploy directly from your terminal:
    1
    Install Vercel CLI
    2
    npm install -g vercel
    3
    Deploy
    4
    # First deployment
vercel

# Production deployment
vercel --prod
    6
    vercel link

    ​
    Troubleshooting

    ​
    Build Fails with Memory Error

    Increase Node.js memory in vercel.json: 
    {
  "env": {
    "NODE_OPTIONS": "--max-old-space-size=8192"
  }
}
    Or set it in Vercel’s environment variables.

    ​
    Build Command Not Found

    Ensure your package.json includes: 
    {
  "scripts": {
    "sources": "evidence sources",
    "build": "evidence build",
    "dev": "evidence dev"
  }
}

    ​
    Environment Variables Not Working

    1. Verify variables are set for the correct environment (Production/Preview/Development)
    2. Check variable names match exactly (case-sensitive)
    3. Redeploy after adding new environment variables
    4. Review deployment logs for specific errors

    ​
    Data Source Connection Timeout

    • Ensure your database allows connections from Vercel’s IP ranges
    • Increase timeout values in your connection string
    • Consider using a connection pooler for serverless-friendly connections

    ​
    Build Exceeds Time Limit

    Optimize your build:
    • Use npm run sources -- --changed to build only modified queries
    • Reduce data volume in source queries
    • Pre-aggregate data in your database
    • Consider upgrading to a Vercel Pro plan for longer build times

    ​
    Advanced Configuration

    ​
    Monorepo Deployment

    For monorepos, specify the root directory: 
    {
  "buildCommand": "cd evidence-app && npm run sources && npm run build",
  "outputDirectory": "evidence-app/build",
  "installCommand": "cd evidence-app && npm install"
}

    ​
    SPA Mode

    To deploy as a Single Page Application: 
    {
  "env": {
    "VITE_EVIDENCE_SPA": "true"
  },
  "routes": [
    {
      "src": "/(.*)",
      "dest": "/index.html"
    }
  ]
}

    ​
    Next Steps

    Build docs developers (and LLMs) love

    Get started for freeTalk to us