Getting a Bolt.new project export-ready before conversion

Vite / React / Astro (varies per project)

Bolt.new projects vary in framework. The converter fingerprints the stack automatically, but a clean export makes the difference between a good and an excellent result.

Quick answer

Use the Download button in the Bolt.new editor to get the full project ZIP, then upload that ZIP directly — do not unpack it.

Fidelity score 88–96Success rate 93%Vite / React / Astro (varies per project)

Where do I find the ZIP?

Open your project in bolt.new
Click the Download / Export icon in the top toolbar of the editor
Bolt packages the whole StackBlitz workspace as a ZIP
Upload the ZIP as-is; alternatively push to GitHub from Bolt and paste the repository URL

What your upload should contain

package.json
index.html or app entry
src/ or app/
Config file (vite.config, astro.config, next.config)

Bolt.new troubleshooting

The build fails on missing environment variables

Placeholder values are injected automatically, but committing a .env.example with the expected keys makes the build deterministic.

Only a blank shell renders

Bolt SPAs sometimes need a runtime render pass. The engine retries with a headless browser; make sure the app runs locally with npm run dev first.

Dependencies fail to install

Remove the lockfile mismatch by running npm install locally once and re-downloading the project.

Best practices before exporting

Ask Bolt to finish the build before downloading — a broken build converts poorly
Remove sample data and demo routes
Keep environment variables out of the project; use placeholders
Verify all pages render in the Bolt preview first

How to export

Method 1 — Download project ZIP (best result)

Open the project in Bolt.new
Use the Download / Export project button in the file panel
Save the ZIP without unpacking
Upload the ZIP to the converter

Method 2 — Push to GitHub

Connect Bolt to GitHub and push the project
Copy the repository URL
Paste it into the converter

Method 3 — Static build output

Run the project's build command locally
Zip dist/ or build/
Upload it to convert the rendered output directly

Accepted input

ZIP archive
GitHub repository
Static export
Source project
Build output

Not recommended

Old build folders from a previous version of the project
Incomplete exports that are missing package.json or index.html
Screenshots, Figma files, PSD files or design mockups
node_modules — always exclude it, it makes uploads slow and adds nothing

Supported features

React and Astro pages
Tailwind and plain CSS
Static assets
Client-side routing
Forms

Unsupported features

Server routes and API handlers
Database-backed pages
Auth flows

Common mistakes

Downloading while the build is still failing
Leaving required environment variables undefined
Including node_modules in the ZIP

Conversion tips

Ask Bolt to remove any API routes before export
Keep the project to a single framework — mixed setups reduce fidelity

Readiness checklist

Navigation — Use real anchor links with readable labels. Menus built purely from JavaScript state are harder to map to WordPress menu locations.
Images — Reference images from your project folder (imports or /public). Images loaded from a temporary preview host may not be reachable at conversion time.
Assets — Fonts, icons and CSS should live inside the project. Locally hosted assets are copied into the theme automatically.
Forms — Standard form markup is converted to Contact Form 7 or WPForms. Custom JavaScript submit handlers are replaced by the WordPress form handler.
Routing — Every route you want as a WordPress page must be reachable from the navigation, a sitemap or a route manifest.
Animations — CSS animations and common libraries survive. Heavy scroll-timeline or canvas effects may render differently in WordPress.
SEO — Titles, meta descriptions and canonical tags are extracted per page and mapped into the theme and your SEO plugin.
Responsive — Breakpoints are preserved as-is. Check mobile before exporting — the converter never fixes a layout that was already broken.

Bolt.new FAQ

Can I upload source code from Bolt?

Yes. The source project ZIP is the preferred input — we build and render it in a sandbox.

Why did my Bolt export fail?

Almost always a failing build or missing environment variables. Fix the build in Bolt, re-export and try again.

Which framework does Bolt use?

It varies per project — Vite + React, Astro or Next.js. The converter detects the framework automatically.

Do Bolt backend routes convert?

No. API routes and server actions are dropped; the frontend is converted.

Can I upload the StackBlitz link?

No, upload the downloaded ZIP or a GitHub repository URL.

Do I need to install anything to convert a Bolt.new project?

No. Everything runs server-side. You upload a ZIP or paste a repository URL and receive a WordPress theme ZIP plus a live preview in the browser.

Should I remove node_modules before uploading?

Yes, always. node_modules is reinstalled during conversion, so including it only makes the upload slow and can push you over the size limit.

Can I preview the result before paying?

Yes. The WordPress preview is free for every conversion. Payment is only required when you download the theme ZIP.

What happens to my forms?

Standard HTML form markup is mapped to Contact Form 7 or WPForms shortcodes. Custom JavaScript submit handlers are replaced by the WordPress form handler.

Will my SEO titles and meta descriptions survive?

Yes. Titles, meta descriptions and canonical tags are extracted per page and written into the theme templates so your SEO plugin can take over.