How to download a Bolt.new project and run it locally
Step by step: download or clone your Bolt.new project, install Node.js, add environment variables, start it on your computer and send changes back to Bolt.
Leer en español →
To run a Bolt.new project on your own computer, download it (click the project title, then Download), unzip it, install Node.js, open a terminal in the project folder and run npm install && npm run dev. The terminal prints a local address, usually http://localhost:5173 for Vite projects, which you open in your browser. If the app needs keys for Supabase or other services, put them in a .env file first.
The rest of this guide covers what to install, whether to use the ZIP download or GitHub, how to handle environment variables and the database, the errors people hit on the first run and how to get local changes back into Bolt.
What do I need on my computer?
- Node.js, LTS version, from nodejs.org. It includes
npm, the tool that installs your project's packages. Bolt's own documentation lists Node.js as the requirement for running a downloaded project. - A code editor, such as VS Code, so you can read and change the files.
- A terminal: Terminal on macOS, PowerShell or Windows Terminal on Windows. Most editors include one.
- Git, only if you go the GitHub route below.
Check the install with node -v and npm -v. Both should print a version number.
ZIP download or GitHub: which one should I use?
| ZIP download | GitHub | |
|---|---|---|
| Setup | Two clicks | Connect GitHub once, then clone |
| History of changes | None, just a snapshot | Every change Bolt makes becomes a commit |
| Sending local edits back to Bolt | Manual and awkward | Push to the repo; Bolt pulls changes made outside it |
| Best for | A quick look, a backup, a one-off handoff | Working locally and in Bolt over time |
For anything beyond a quick look, use GitHub. To connect, click the GitHub icon in the top-right of the project, authorize the Bolt app and create a repository (it starts private, on main). Then clone it:
git clone https://github.com/<you>/<repo>.git
cd <repo>How do I start the project?
- Get the code: unzip the download, or clone the repository.
- Open a terminal in the project folder, the one that contains
package.json. - Install packages:
npm install. The first run takes a minute or two and creates anode_modulesfolder. - Add environment variables (next section), or the app may open on a blank page.
- Start the dev server:
npm run dev. - Open the address it prints. For Vite it's usually
http://localhost:5173; for Next.js,http://localhost:3000.
If the project is a mobile app built with Expo, the command is usually npx expo start. It shows a QR code you scan with the Expo Go app on your phone.
What about environment variables and the database?
Front-end code reads its settings from a .env file in the project root. Files starting with a dot are hidden by default; in the macOS Finder, Cmd+Shift+. shows them. Look for one before you create one. If it's missing or incomplete, ask Bolt in Plan mode: List every environment variable the application requires and where each value can be found.
A typical Vite and Supabase project needs something like:
VITE_SUPABASE_URL=https://<project-ref>.supabase.co
VITE_SUPABASE_ANON_KEY=<publishable or anon key>Three things to keep in mind:
- Your local app talks to the same database as the Bolt preview and, often, the live site. Anything you create or delete locally is real. Use a test account and test data.
- Secret keys don't belong in this file. Values for server functions (an OpenAI key, a Stripe secret key) live in Bolt's Secrets settings and are used by server-side code, not by the browser. See our guide to environment variables in Bolt.new.
- Never commit
.envto GitHub. Check that.gitignorelists it before your first push.
Server functions keep running in the cloud. Your local front end calls the deployed versions, so a change you make to a function's code locally has no effect until it's deployed again.
Why won't it start? Common first-run errors
| Error | What it means | Fix |
|---|---|---|
command not found: npm or 'npm' is not recognized | Node.js isn't installed or the terminal was opened before installing it | Install Node.js LTS and open a new terminal |
Cannot find module '...' | Packages weren't installed | Run npm install |
npm warn EBADENGINE | A package expects a different Node version | Use the version the project expects, often listed in package.json under engines |
ERESOLVE unable to resolve dependency tree | Packages that don't agree on versions | See our guide to npm dependency errors in Bolt.new |
EADDRINUSE | Another program is using the port | Stop the other server, or let Vite pick another port |
Blank page, console says supabaseUrl is required. | Missing environment variables | Fill in .env and restart npm run dev |
Restart the dev server after editing .env. Vite reads it only when it starts.
How do I get my local changes back into Bolt?
With GitHub connected, commit and push your changes. Bolt checks GitHub every 30 seconds and pulls in updates made outside it. Two rules keep this calm:
- Don't edit the same project in both places at once. Bolt's documentation warns that if Bolt and GitHub change at almost the same moment, Bolt keeps its own version and overwrites the GitHub one.
- Use a branch for bigger local work. Bolt can switch branches from the GitHub menu, but merging happens on GitHub, not inside Bolt.
With a ZIP download, there's no automatic route back. Bolt documents a manual restore through StackBlitz, which creates a new project from your files. That works for a one-time move, not for daily work.
Is it worth running the project locally?
Usually, once the app matters. Locally you can run a production build (npm run build) before you publish, use a debugger, add automated tests and let a developer review the code without screen sharing. It's also the natural next step when a project outgrows Bolt's context window, as described in our post on Bolt projects that get too large. If you're handing the project to someone, our guide to handing off an AI-built project to a developer lists what to include.
Quick answers
Will downloading the project change anything in Bolt? No. It's a copy. The project in Bolt stays as it was.
Do I need to know how to code? To start it, no: two commands are enough. To change it safely, some familiarity helps, or an AI editor working on the local files.
Can I keep using Bolt afterwards? Yes. With GitHub in the middle, you can switch between Bolt and your editor.
Why does the local app show real customer data? Because it points at the same database. If that's a problem, point your local .env at a separate test database instead of the live one.
Want a developer to take it from here?
If you'd like someone to set up a proper local and staging workflow, our Bolt app rescue and custom software development work both start from your GitHub repository. Run the free health check on the live app first, or get in touch.
