How to Export Bolt.new to GitHub and Deploy to Vercel (Step-by-Step Guide)

Ayush Tyagi • October 14, 2026

Building a full-stack web application inside Bolt.new feels like magic. With a few prompts, you can generate complete React interfaces, integrate Tailwind CSS, and wire up mock APIs in minutes. However, moving that prototype out of the browser and into production is where many developers hit unexpected roadblocks.

When deploying an exported Bolt.new codebase directly to Vercel, developers frequently encounter three frustrating issues: the dreaded blank white screen, 404 errors on page refresh, or failed builds caused by strict TypeScript checks. In this step-by-step guide, you will learn the exact pipeline to export clean code to GitHub, deploy to Vercel seamlessly, and apply the required configuration fixes for production stability.

[Bolt.new → GitHub → Vercel Deployment Pipeline]
Bolt.new In-Browser Prototype
  ├── Sync & Push to GitHub Repository
  └── Configure Local/Production Configs:
        ├── Add vercel.json (Prevents 404 Routing on Hard Refresh)
        ├── Patch package.json (Bypass Strict 'tsc -b' Failures)
        └── Inject VITE_* Environment Variables in Vercel Project Settings
            └── Auto-Trigger Vercel CI/CD → Live Production URL (.vercel.app)

Why Bolt.new Projects Break on Vercel

Bolt.new runs an ephemeral WebContainer inside your browser using Node.js via WebAssembly. While this allows instant hot-reloading, a true cloud deployment platform like Vercel executes a full production build via terminal runners (CI/CD). Three structural differences cause builds to fail:

  1. Single Page Application (SPA) Routing: Bolt applications are typically built on Vite + React. When users navigate to sub-routes (like /dashboard or /settings) and hit reload, Vercel looks for a static file that doesn't exist, returning a 404 error instead of routing through index.html.
  2. Vite Environment Variable Scoping: Client-side API keys (such as Supabase URLs or public credentials) must start with the VITE_ prefix to be bundled during compilation.
  3. Strict TypeScript Compilation (tsc): Bolt's AI engine frequently leaves behind minor unused imports or minor type mismatches. While Vite dev-mode ignores them, Vercel's standard build script enforces zero type errors and aborts deployment.

💡 Hit your Bolt token limit while refining your code? Learn how to extract your full prompt history and context in our guide: How to Transfer from Bolt.new to Claude (Without Losing Context).

Step 1: Export Your Bolt.new Project to GitHub

Bolt.new provides a native GitHub integration. Using it preserves version history and enables automatic redeployments whenever you push new changes.

  1. In the top right corner of your Bolt.new workspace, click the Export button (or GitHub icon).
  2. Select Push to GitHub.
  3. If you haven't connected your GitHub account yet, authorize the Bolt.new GitHub OAuth application.
  4. Choose an intuitive repository name (e.g., ai-portfolio-builder) and choose whether to make the repository Public or Private.
  5. Click Create Repository & Push. Within 10 to 20 seconds, your code will be committed to your GitHub account under the main branch.
Alternative (Download ZIP): If you do not want to use OAuth, click Download ZIP, extract the files locally on your machine, initialize Git with git init, commit the files, and push them to a newly created GitHub repository manually.

Step 2: Add the Missing 'vercel.json' SPA Rewrite File

This is the most critical fix for Vite apps on Vercel. Without this configuration, any nested link or hard page refresh on your live domain will return an immediate 404: NOT_FOUND error.

Inside your repository's root directory (at the same level as package.json), create a new file named vercel.json and add the following JSON rewrite rules:

{
  "rewrites": [
    {
      "source": "/(.*)",
      "destination": "/"
    }
  ]
}

This tells Vercel's edge server that whenever a user visits any sub-path (e.g., domain.com/app/dashboard), it should serve the central index.html file, letting the client-side router (such as React Router) handle URL parsing internally.

Step 3: Adjust the Build Script in 'package.json'

Open your project's package.json file. By default, most Vite templates generated by Bolt include the following build command:

"scripts": {
  "dev": "vite",
  "build": "tsc -b && vite build",
  "lint": "eslint .",
  "preview": "vite preview"
}

The tsc -b command executes a strict TypeScript compiler check across your entire codebase before building. If the AI generated unused parameters or minor interface type deviations, the build will crash on Vercel with exit code 1 or 2.

To ensure smooth deployments while debugging, update your build script to bypass the strict type halt:

"scripts": {
  "dev": "vite",
  "build": "vite build",
  "lint": "eslint .",
  "preview": "vite preview"
}

Note: You can still run npm run lint locally or inspect type definitions later, but removing tsc -b from the primary build line ensures your production bundle compiles cleanly.

Step 4: Import the Repository into Vercel

Now that your GitHub repository contains both the code and the routing configuration, connect it to Vercel:

  1. Navigate to Vercel.com and sign in with your GitHub account.
  2. From the Vercel dashboard, click Add New... → Project.
  3. Locate your exported Bolt.new repository in the list and click Import.
  4. Verify the Project Name and ensure the Framework Preset is automatically identified as Vite.
  5. Check the Build and Output Settings:
    • Build Command: npm run build (or leave default override off)
    • Output Directory: dist
    • Install Command: npm install

Step 5: Set Up Environment Variables

If your Bolt.new project utilizes third-party APIs (such as OpenAI, Anthropic, Supabase, or Stripe), these keys will not be carried over via GitHub for security reasons. If they are missing, your app will load as a blank page due to runtime crashes.

  1. On the Vercel project configuration screen, expand the Environment Variables section.
  2. Look through your local .env.example or Bolt code to identify required variable names.
  3. Ensure all client-side variables follow Vite conventions starting with VITE_:
    • VITE_SUPABASE_URL
    • VITE_SUPABASE_ANON_KEY
    • VITE_API_BASE_URL
  4. Paste the corresponding production keys into the Value field and click Add.
  5. Click the blue Deploy button.

Vercel will clone your GitHub repository, install packages, run vite build, and provision dynamic SSL certificates across its Global Edge Network. Within 45 to 60 seconds, you will see the confetti celebration screen with your live production URL.

Troubleshooting Common Deployment Errors

Error Symptom Root Cause How to Fix
White / Blank Screen in Production Missing environment variables or uncaught JavaScript runtime exceptions. Open your browser's Developer Tools (F12) → Console. Check for missing undefined API client errors and verify your Vercel Environment Variables.
404 Page on Sub-Route Reload Missing SPA rewrite fallback on the edge host. Add the vercel.json file with the "destination": "/" rule in the project root directory.
Command 'tsc -b' exited with code 2 Unused imports or type discrepancies failing strict type checking. Change your build command in package.json from "tsc -b && vite build" to "vite build".
Package Lock Conflicts (npm / pnpm) Conflicting lockfiles in the repository. Ensure only one lockfile exists in your repo (either package-lock.json or pnpm-lock.yaml). Delete the extra one and redeploy.

Best Practices for Ongoing Development

Once your project is linked to GitHub and Vercel, you unlock continuous integration workflows:

  • Instant Staging Environments: Whenever you test new experimental features in a new Git branch, pushing it to GitHub automatically spins up a unique Preview Deployment URL on Vercel so you can verify changes before merging into production.
  • Custom Domain Mapping: Under your project's Settings → Domains in Vercel, add your custom root domain or subdomain. Vercel will provide standard CNAME and A-records that take under 5 minutes to verify in Cloudflare or Namecheap.
  • Database Migrations: If you are connecting backend databases like Supabase, avoid running raw schema edits directly in production. Utilize Supabase migration files or an integrated SQL editor before deploying new UI features that expect updated table columns.
Adding User Login & Database Tables to Your Bolt App? Avoid the dreaded Error 42501 with our copy-paste SQL and environment config guide: How to Connect Bolt.new to Supabase: Auth, Database & RLS Policies (Without Errors).

Frequently Asked Questions (FAQ)

Do I need a paid Vercel plan to deploy Bolt.new apps?

No. Vercel's Hobby Tier is free for personal and non-commercial development projects. It includes unlimited deployments, automatic SSL certificates, global edge caching, and 100 GB of monthly bandwidth.

Can I export and deploy full-stack Node.js backends from Bolt.new?

Bolt.new generates client-side frontends or Vite-based applications. If your project includes an Express or Fastify server, you can deploy the backend separately via Vercel Serverless Functions (under the /api folder) or host it on platforms like Render or Railway.

Why are my environment variables not working after adding them in Vercel?

Remember that Vite bakes environment variables into the static JavaScript bundle at build time. After adding or modifying environment variables in the Vercel dashboard, you must trigger a new deployment (Redeploy) for the changes to take effect in your live code.

Comments (0)