How to Integrate Bolt.new with PyCharm

Before writing any code, it is worth taking two minutes to understand the architectural relationship between Bolt.new and PyCharm in this workflow. Bolt's WebContainer runs Node.js inside a browser tab using WebAssembly — it executes JavaScript, TypeScript, and can run any npm package that does not require native C extensions. Python is not installed in the WebContainer and cannot be installed. When you see a command like 'pip install' in Bolt's terminal, it will fail. There is no workaround for this within the Bolt environment itself. This is a feature, not a bug — Bolt is designed to be a frictionless browser-based frontend development environment, not a general-purpose server. For the vast majority of web apps (React + Supabase/Firebase backend), you never need Python and Bolt handles everything perfectly. Python becomes necessary when your use case specifically requires Python's ecosystem: machine learning with PyTorch or TensorFlow, scientific computing with NumPy or pandas, Django's mature ORM and admin interface, or Python-specific APIs (like some financial data libraries that only have Python SDKs). The architecture you are building has two separate processes that run side-by-side on your local machine after exporting from Bolt: Process 1 is the React development server (npm run dev, typically on port 5173 for Vite or 3000 for Next.js) serving your Bolt-generated frontend. Process 2 is the Python web server (uvicorn for FastAPI, python manage.py runserver for Django, or flask run for Flask) serving your API endpoints (typically on port 8000). The React frontend makes fetch() calls to the Python backend using localhost:8000 during development. In production, both services deploy separately — the React app builds to static files and deploys to a CDN or your Python server's static file handler, while the Python backend deploys to a Python-capable hosting service. PyCharm Professional supports this multi-service architecture with its built-in Run Configurations — you can start both servers simultaneously with a single click using a Compound Run Configuration. Community edition users run both servers manually in separate terminal tabs.

To get your Bolt project onto your local machine, you have two options: download as a ZIP file or push to GitHub. The GitHub approach is better for ongoing development because it sets up version control you will want as the project grows. The ZIP approach is faster if you just want to evaluate the workflow. For the GitHub approach: In Bolt.new, click the GitHub icon in the top-right area of the interface. If you have not connected GitHub yet, click 'Connect GitHub' and complete the OAuth flow. Once connected, click 'Push to GitHub,' name your repository, and click Create. Bolt pushes all project files to a new GitHub repository under your account. Now, in PyCharm, go to File → New Project from VCS, paste your GitHub repository URL, choose a local directory, and click Clone. PyCharm clones the repository and opens it as a project. For the ZIP approach: In Bolt.new, click the three-dot menu in the top-right area and select 'Download Project' or look for a download/export button in the file explorer. This downloads a ZIP file of all project files. Unzip it to a directory on your local machine (e.g., ~/projects/my-bolt-app). In PyCharm, go to File → Open, navigate to the unzipped directory, and click OK to open it as a project. Once the project is open in PyCharm, you will see the React frontend files — package.json, src/, public/, vite.config.ts or next.config.ts. PyCharm will detect that it is a JavaScript/TypeScript project and may prompt you to install Node.js dependencies. Click 'Run npm install' or open PyCharm's terminal (Alt+F12 / Option+F12) and run npm install manually. After installation, confirm the frontend works by running npm run dev in the terminal. If Bolt generated a working app, you should see it running at localhost:5173 or localhost:3000 in your browser.

With the React frontend running in PyCharm, you will now add a Python backend alongside it in the same project directory. The conventional approach is to create a backend/ subdirectory at the project root — this keeps frontend and backend code in the same repository (a monorepo) while maintaining clear separation. In PyCharm's Project view on the left side, right-click the project root and select New → Directory. Name it 'backend'. Inside the backend/ directory, you will create a Python virtual environment and a FastAPI application. FastAPI is the recommended choice for new Python APIs due to its speed (comparable to Node.js, faster than Django), automatic OpenAPI documentation, TypeScript-friendly JSON schema validation, and async support. Open a new terminal in PyCharm (or use the existing one) and navigate to the backend directory. Create a virtual environment with: python3 -m venv venv. Activate it on macOS/Linux: source venv/bin/activate. On Windows: .\venv\Scripts\activate. The terminal prompt will change to show (venv) indicating the virtual environment is active. Install FastAPI and Uvicorn: pip install fastapi uvicorn[standard]. Create a requirements.txt for reproducibility: pip freeze > requirements.txt. Create the main FastAPI application file at backend/main.py. At minimum, a FastAPI app for a React frontend needs: the FastAPI instance, CORS middleware configured to allow requests from localhost:5173 (or wherever the React dev server runs), and at least one API endpoint to verify everything works. The CORS configuration is critical — without it, your React fetch() calls to the Python backend will be blocked by the browser's same-origin policy. To start the FastAPI server, run in the backend terminal (with venv activated): uvicorn main:app --reload --port 8000. The --reload flag restarts the server automatically when you save Python files, similar to Vite's HMR for the frontend. With both servers running (frontend on 5173, backend on 8000), you can test the connection by making a fetch call from React to http://localhost:8000/api/hello.

1# backend/main.py
2from fastapi import FastAPI
3from fastapi.middleware.cors import CORSMiddleware
4from pydantic import BaseModel
5from typing import Optional
6import uvicorn
7
8app = FastAPI(title="My App API", version="1.0.0")
9
10# CORS configuration — allow requests from the React dev server
11app.add_middleware(
12    CORSMiddleware,
13    allow_origins=[
14        "http://localhost:5173",  # Vite dev server
15        "http://localhost:3000",  # Next.js dev server
16        "http://localhost:3001",  # Alternative port
17    ],
18    allow_credentials=True,
19    allow_methods=["*"],
20    allow_headers=["*"],
21)
22
23
24@app.get("/api/health")
25async def health_check():
26    return {"status": "ok", "service": "python-backend"}
27
28
29class AnalysisRequest(BaseModel):
30    data: list[float]
31    operation: Optional[str] = "mean"
32
33
34@app.post("/api/analyze")
35async def analyze_data(request: AnalysisRequest):
36    import statistics
37    if request.operation == "mean":
38        result = statistics.mean(request.data)
39    elif request.operation == "median":
40        result = statistics.median(request.data)
41    elif request.operation == "stdev":
42        result = statistics.stdev(request.data)
43    else:
44        result = sum(request.data)
45    return {"operation": request.operation, "result": result, "input_count": len(request.data)}
46
47
48if __name__ == "__main__":
49    uvicorn.run("main:app", host="0.0.0.0", port=8000, reload=True)

With both servers running, you need to configure the React frontend to call the Python backend API. There are two approaches: direct fetch calls with the full URL (http://localhost:8000/api/...) during development, or configuring a Vite proxy to forward /api requests to the Python server. The proxy approach is cleaner because it uses relative URLs in your React code (/api/...) that work the same way in development and production. For Vite projects, open vite.config.ts and add a proxy configuration under server.proxy. This tells Vite's dev server to forward any request starting with /api to your Python backend running on port 8000. Your React components then use relative URLs like fetch('/api/analyze') instead of hardcoded localhost addresses. For Next.js projects, add a rewrites configuration in next.config.ts that proxies /api/python routes to the Python server. This prevents Next.js API routes (which would otherwise handle /api/* requests) from conflicting with the Python backend. Once the proxy is configured, update the React frontend to call your new Python endpoints. In Bolt's AI chat (if you still have the Bolt project open) or directly in PyCharm's editor, add a simple service module that wraps the fetch calls. This module handles loading states, error handling, and TypeScript types for the response data. Test the connection: start both servers, open the React app in your browser, and verify that fetch calls to /api/health return the FastAPI health check response. Open browser DevTools → Network tab to confirm the requests are reaching the Python server and getting 200 responses. If you see CORS errors, double-check that the CORS middleware in main.py includes your React dev server's origin URL.

1// vite.config.ts — add proxy to forward /api requests to Python backend
2import { defineConfig } from 'vite';
3import react from '@vitejs/plugin-react';
4
5export default defineConfig({
6  plugins: [react()],
7  server: {
8    proxy: {
9      // Forward /api requests to the FastAPI Python server
10      '/api': {
11        target: 'http://localhost:8000',
12        changeOrigin: true,
13        // Optionally rewrite the path if Python routes use a prefix:
14        // rewrite: (path) => path.replace(/^\/api/, '/api')
15      },
16    },
17  },
18});

Deploying a project with both a React frontend and a Python backend requires a hosting service that supports Python runtime. The three most practical options for Bolt-generated projects with PyCharm-added backends are Render, Railway, and a traditional VPS (Hetzner, DigitalOcean Droplet). Render (render.com) is the simplest option. Create two services: a Static Site for the React frontend (build command: npm run build, publish directory: dist for Vite or .next for Next.js) and a Web Service for the Python backend (root directory: backend, build command: pip install -r requirements.txt, start command: uvicorn main:app --host 0.0.0.0 --port $PORT). Render handles SSL, custom domains, and automatic deploys from GitHub for both services. For the frontend, update the Vite proxy to point to the deployed Python backend URL in production. Use an environment variable: in production, the API calls should go to https://your-backend.onrender.com, not localhost:8000. The standard pattern is to use import.meta.env.VITE_API_URL in the React app and set VITE_API_URL to your Python backend's public URL in the hosting platform's environment variables. Alternatively, configure FastAPI to serve the built React static files directly. After running npm run build (which creates a dist/ folder), configure FastAPI's StaticFiles mount to serve the dist/ directory. This single-binary deployment approach means you only need one hosting service — the Python server handles both the API routes and static file serving. This is particularly convenient for Render and Railway's free tiers, which limit the number of free services.

1# backend/main.py — serve React static files from FastAPI
2from fastapi import FastAPI
3from fastapi.staticfiles import StaticFiles
4from fastapi.responses import FileResponse
5from fastapi.middleware.cors import CORSMiddleware
6import os
7
8app = FastAPI()
9
10# API routes must be registered BEFORE the static file mount
11@app.get("/api/health")
12async def health_check():
13    return {"status": "ok"}
14
15# Mount the React build output (dist/ for Vite, out/ for Next.js static export)
16DIST_DIR = os.path.join(os.path.dirname(__file__), '..', 'dist')
17
18if os.path.exists(DIST_DIR):
19    app.mount("/assets", StaticFiles(directory=os.path.join(DIST_DIR, 'assets')), name="assets")
20
21    @app.get("/{full_path:path}")
22    async def serve_react_app(full_path: str):
23        # Serve index.html for all non-API routes (React Router SPA)
24        index_path = os.path.join(DIST_DIR, 'index.html')
25        if os.path.exists(index_path):
26            return FileResponse(index_path)
27        return {"error": "Frontend not built"}