How to Use Bolt.new? Build Full-Stack Apps From Your Browser

TL;DR

Bolt.new turns natural language descriptions into working full-stack web applications — no local setup, no terminal, no IDE. You describe what you want in plain English, and within 60 seconds, Bolt scaffolds your project, installs dependencies, and launches a live dev server inside your browser tab. It runs on StackBlitz's WebContainer technology, which boots a complete Node.js environment directly in the browser sandbox. This guide covers everything from your first prompt to production deployment, prompt engineering strategies that actually work, token management, and when Bolt.new is (and isn't) the right tool.

Prerequisites

• A modern browser (Chrome, Edge, or Arc recommended; Firefox has WebContainer limitations)
• A Bolt.new account (free tier works; Google/GitHub sign-in)
• Basic understanding of what a full-stack web app is (frontend + backend + database awareness)
• No coding skills required — Bolt is designed for both developers and non-developers

What Is Bolt.new?

Bolt.new is an AI-powered web development agent built by StackBlitz, the company behind the popular instant dev environment platform. Released in late 2024 and rapidly iterated through 2026, Bolt.new combines three key technologies:

1. WebContainer: A browser-based Node.js runtime that executes real npm install, npm run dev, and file system operations entirely inside your browser tab. No remote VM spins up — everything runs locally in a secure sandbox.

2. AI Agent (LLM-powered): Bolt uses state-of-the-art language models to interpret your prompts, plan the project structure, generate code files, and iteratively fix bugs. The agent has access to the WebContainer filesystem, terminal, and browser preview.

3. Instant Deployment: Every Bolt project gets a shareable URL with one click. The built-in deployment uses StackBlitz's hosting infrastructure, so you go from prompt to live URL in minutes.

How WebContainer Works (Technical)

Unlike tools that spin up cloud VMs for each user, WebContainer runs entirely client-side. Here is what happens under the hood:

• The browser downloads a lightweight Node.js binary compiled to WebAssembly
• A virtual file system (memfs) stores your project files in memory
• npm runs inside a service worker with network access proxied through the browser
• A dev server (Vite, Next.js, Astro, etc.) binds to a virtual port accessible via an iframe in your Bolt tab
• The AI agent communicates with the WebContainer through a structured tool-calling API (read file, write file, run command, fetch error logs)

This architecture means Bolt.new has no cold starts for existing projects and can serve thousands of concurrent users without scaling server infrastructure.

Bolt.new vs. Other AI Builders

Step 1: Sign Up and Navigate the Interface

Go to bolt.new and sign in with Google or GitHub. The interface has three main areas:

1. Left sidebar — Chat panel: This is where you type prompts. Every message you send triggers the AI agent to take action. You can also upload images as design references or attach current screenshots for bug fixing.

2. Center — Code editor: Once Bolt generates files, a Monaco-based editor (same engine as VS Code) shows your project tree on the left and file contents on the right. You can manually edit any file, and the AI will respect your changes in subsequent iterations.

3. Right — Live preview: After the dev server starts, the preview pane shows your running app in real time. It refreshes automatically when files change. The preview URL is accessible from any device on your network.

Key buttons to know:

• Enhance Prompt (magic wand icon): Expands a short prompt into a detailed project brief before sending it to the AI. Use this when you are not sure how to describe your app.
• Publish (top-right): Deploys your app to a public URL. Free plan gives you one published project at a time; Pro gets unlimited.
• Fork/Remix: Creates a copy of any public Bolt project to use as a starting point.
• StackBlitz button (top-left): Opens your project in the full StackBlitz IDE for advanced editing and GitHub integration.

Step 2: Write Your First Effective Prompt

The quality of your Bolt.new output depends heavily on your initial prompt. Here is a proven template:

Build a [type of app] with the following features:

Tech Stack: [framework, styling library, database if needed]

Core Features:
1. [Feature 1 with specific behavior]
2. [Feature 2 with specific behavior]
3. [Feature 3 with specific behavior]

Design Requirements:
- [Visual style, color scheme]
- [Responsive? Mobile-first?]

Constraints:
- [Any specific requirements]

Prompt Example (Pet Name Generator)

Here is a real working prompt:

Build a Pet Name Generator web app with the following:

Tech Stack: React, Tailwind CSS, localStorage for saved names

Core Features:
1. A form where users select pet type (dog, cat, bird, fish) and personality traits (energetic, calm, playful, lazy)
2. A "Generate Names" button that uses a clever algorithm to combine prefixes and suffixes based on the selected traits to produce 5 unique name suggestions
3. A "Save Name" feature that stores favorites in localStorage with the pet type and date saved
4. A "Saved Names" page where users can view, filter by pet type, and delete saved names

Design Requirements:
- Playful, colorful with rounded corners
- Mobile-responsive
- Pet emoji decorations throughout

Constraints:
- No external API calls needed
- All name generation logic should be client-side

This prompt gives Bolt everything it needs to scaffold the right project, pick the right dependencies, and generate accurate code on the first try.

Prompting Best Practices

1. Pin your tech stack in the first message. If you say "Build a to-do app," Bolt defaults to React + Tailwind. If you want Svelte + Panda CSS, say it explicitly.

2. Think app-brief, not component-request. Bolt treats your prompt as the full project spec. Instead of "Add a button that..." use the full template above.

3. Acknowledge browser constraints. Bolt runs in a WebContainer. No native binaries, no Docker, no system-level operations. If your app needs PostgreSQL, use a hosted database (Neon, Supabase) and connect via REST API or serverless driver.

4. Use "Enhance Prompt" iteratively. Write a rough idea, click Enhance Prompt, review the expanded brief, edit it, then send.

5. Upload screenshots for visual context. If you want the UI to look like a specific reference, upload a screenshot and Bolt will match the layout.

6. Be specific about state management. For React apps, mention whether you want Context API, Zustand, or Redux. For Next.js, clarify whether you need Server Components or client-side interactivity.

Step 3: Iterate — The Feedback Loop

The real power of Bolt.new is not the first generation — it is the iterative feedback loop. Here is the workflow that experienced Bolt users follow:

The Prompt → Review → Refine Cycle

1. Send your initial prompt — Bolt scaffolds the project, installs deps, and starts the dev server (~30-90 seconds)

2. Test the app in the preview pane — Click through every feature. Does the button work? Is data persisting? Are error states handled?

3. Report bugs conversationally — You do not need to open the code. Just type in chat:

   • "The save button doesn't work — nothing happens when I click it"
   • "The mobile layout is broken — the form overflows the screen on iPhone SE"
   • "Can you add loading states while the names generate?"
   • "The generate button should show a shuffle animation"

4. Bolt reads the error, finds the source, and fixes it — The agent has access to the terminal output, browser console, and file system. It diagnoses and patches in one step.

5. Repeat — Most projects take 3-8 iteration cycles to reach a polished state.

Pro Tip: The "Screenshot Debug" Trick

If the visual output is wrong (wrong colors, layout broken, spacing off), take a screenshot of the preview, circle the problem area, and upload it to the chat with a message like "Fix this section — the alignment is off." Bolt's vision-capable model can see your screenshot and understand the visual bug.

Step 4: Deploy Your App

Once satisfied, click the Publish button in the top-right corner. Bolt will:

1. Build your project for production
2. Deploy to StackBlitz hosting (free tier: 1 published project; Pro: unlimited)
3. Give you a shareable URL (format: your-project-name.stackblitz.io or custom)

Deployment checklist before publishing:

• Remove any console.log statements
• Set environment variables (click the settings gear → Environment Variables)
• Test on mobile and desktop viewports
• Check that all links work
• Verify that external API calls work from the deployed domain (CORS)

Custom domains: Bolt supports custom domains on Pro and Teams plans. Go to Settings → Domains → Add Custom Domain and follow the DNS verification steps.

Step 5: Manage Tokens and Costs

Bolt.new uses a token-based pricing model. Every AI interaction — generating code, fixing bugs, answering questions — consumes tokens. Here is what you need to know:

How Tokens Are Consumed

• A simple prompt ("Fix this button") with a small file change: ~2,000-5,000 tokens
• A full project scaffold (prompt + code generation): ~50,000-200,000 tokens
• A complex iteration with multiple file changes: ~20,000-80,000 tokens
• StackBlitz documentation features like docs import: token cost varies

Cost-Saving Strategies

1. Write detailed initial prompts. A 10-sentence prompt costs ~100 tokens. An iteration loop costs 20,000+. Invest in the prompt, save on iterations.

2. Use Enhance Prompt before sending. It is free (doesn't count against your token limit) and produces better first-shot results.

3. Batch changes in one message. Instead of "Add a header" then "Now add a footer," say "Add a header with nav links and a footer with social icons."

4. Manually edit small changes. The code editor is fully functional. Change a color, tweak a margin, or fix a typo yourself — free.

5. Monitor your usage. Your token count is visible in the bottom-left settings panel. Check it before starting large sessions.

Step 6: Advanced Workflows

Importing Existing Projects

Bolt.new can import projects from:

• GitHub repos: Paste a repo URL in the chat and say "Import this project"
• StackBlitz projects: Open any StackBlitz URL directly in Bolt
• Local files: Drag and drop a folder into the Bolt interface (Pro plan)

Using StackBlitz Docs

Bolt has a special feature for reading and applying documentation. Type @stackblitz-docs in your prompt to load official docs for frameworks like Next.js, Astro, SvelteKit, and more. Example:

@stackblitz-docs Next.js App Router
Build a blog with dynamic routes, MDX support, and ISR

This gives the AI context from the actual documentation, dramatically improving accuracy for framework-specific features.

Connecting External Databases

Bolt.new does not run a database server in the browser. To add persistence to your app:

1. Supabase (recommended): Create a free Supabase project, grab your anon key and project URL, and add them as environment variables in Bolt. Use @supabase/supabase-js in your code.

2. Neon (serverless Postgres): Same pattern — connection string as an env var, @neondatabase/serverless package.

3. Upstash Redis: For caching and rate limiting. Add the Redis URL as an env var.

4. Firebase: Works with Bolt via the Firebase JS SDK. Add config as env vars.

Security note: Always use environment variables for API keys and secrets. Never hardcode credentials in your Bolt project — they are visible if you share the project URL or publish it.

Exporting to GitHub

On the Pro plan, you can export any Bolt project to GitHub:

1. Click the StackBlitz icon (top-left) to open in full IDE
2. Connect your GitHub account
3. Push to a new or existing repository
4. From there, you can deploy to Vercel, Netlify, or any other hosting

Step 7: Common Pitfalls and How to Avoid Them

Pitfall 1: Vague Prompts = Vague Apps

The problem: "Build me a CRM" produces a generic table with columns.

The fix: Specify exactly what your CRM should do: "Build a CRM for freelancers with client list, project tracking with status (lead/active/completed/dead), invoice generation with PDF export, and a dashboard showing monthly revenue. Tech stack: React, Tailwind, Supabase for database."

Pitfall 2: Token Burn on Broken Iterations

The problem: The AI fixes one bug but introduces two more. You keep prompting and burning tokens.

The fix: If you hit 3 iterations without progress, use the "nuclear option" — ask Bolt to "Restart this feature from scratch. Here is the spec..." and paste your original requirements. Sometimes regenerating is cheaper than patching.

Pitfall 3: Ignoring Browser Limitations

The problem: You ask Bolt to run a Python backend or install a system dependency. It fails silently.

The fix: Remember the WebContainer constraint. Bolt runs JavaScript/TypeScript on Node.js. For Python, Rust, or Go backends, use an external API or move to Replit Agent. For system-level packages (ImageMagick, ffmpeg), use a SaaS API wrapper instead.

Pitfall 4: Skipping the Publish Checklist

The problem: You publish an app with hardcoded API keys or console.log statements visible in production.

The fix: Always run through the deployment checklist in Step 4 before publishing. Check Settings → Environment Variables, scan your codebase for exposed keys, and test the deployed URL.

Pitfall 5: Not Using the Fork Ecosystem

The problem: You start every project from scratch, reinventing common patterns.

The fix: Browse bolt.new/explore for community projects. Fork a similar app as your starting point. Bolt's community has shared thousands of templates — landing pages, dashboards, e-commerce stores, SaaS starters.

Step 8: When Bolt.new Is (and Isn't) the Right Tool

Use Bolt.new When:

• You need a working prototype or MVP in hours, not weeks
• You are building browser-based full-stack JS apps (React, Next.js, SvelteKit, Astro, Vue/Nuxt)
• You want to test an idea without setting up a local dev environment
• You are a designer or product manager who needs functional demos
• You want to learn how full-stack apps work by watching the AI build them

Use Something Else When:

• You need a Python/Django/Rails backend → Use Replit Agent or GitHub Copilot locally
• You only need polished UI components → Use v0 by Vercel (generates copy-paste React/Tailwind components)
• You need production-grade security and infrastructure → Build locally with Cursor or Claude Code, deploy via Vercel/AWS
• You are working in a regulated industry → Replit Teams (SOC 2 Type II) or local development
• You need offline development → Bolt.new requires an internet connection (the AI agent runs server-side)

Troubleshooting

The preview won't load" / "Blank white screen

1. Check the terminal tab (bottom panel) for build errors
2. Look for red error markers in the file tree (syntax errors)
3. Try a hard refresh: click the refresh button in the preview toolbar
4. If the dev server crashed, type "Start the dev server" in chat

Token limit exceeded

1. Your free plan has a 300K daily limit. Wait until tomorrow or upgrade to Pro.
2. Check if you have an active bug-fix loop — see Pitfall 2 above.
3. Switch to manual editing for the rest of the session.

The AI keeps making the same mistake

1. Try rephrasing your request as a specific instruction: "In file src/components/Header.tsx, line 24, change the flex to flex-col"
2. Manually make the fix yourself in the editor — Bolt respects manual edits
3. Upload a screenshot of the problem for visual context
4. Use the StackBlitz button to open in full IDE for advanced debugging

API keys not working in production

1. Go to Settings → Environment Variables and verify keys are set
2. Ensure you are using process.env.MY_VAR (Vite) or import.meta.env.MY_VAR (other bundlers) — not hardcoded strings
3. Redeploy after changing environment variables (they are baked at build time)

My project is slow after adding many features

1. Large Bolt projects can slow down the WebContainer. Export to GitHub and continue in a local IDE.
2. For Next.js projects, ensure you are using Server Components where possible to reduce client bundle size.
3. Type "Optimize the bundle size — remove unused imports and split code" in chat.

Related Tutorials

• Aider AI Pair Programming Terminal Guide
• How to Use Cursor AI for Coding? Complete Guide
• Claude Code CLI Tutorial: Setup and Best Practices