Bolt deployment rescue

Bolt.new app works in preview but deploy fails

Walkthrough

1. 01

   Capture what Bolt.new was doing

   Bolt.new handles install, build, and start automatically in its cloud environment. You need to replicate each of those settings on your server. Bolt.new uses a hidden build process that may include postinstall scripts, environment injection, and platform-specific configurations that are not visible in the exported code.

   • Find the package.json build and start scripts. Compare them with the commands Bolt.new actually runs by checking the build output log in the Bolt.new dashboard.
   • Note the Node version Bolt.new uses. Check package.json engines field, or infer from the platform dependencies in lock files.
   • List every environment variable the app references in code by searching for process.env.* across the entire codebase.
   • Check for a postinstall or prepare script in package.json that may run additional setup steps during deployment.
   • Identify the package manager (npm, yarn, pnpm) Bolt.new uses. Using a different one on the server can produce different dependency resolutions.
2. 02

   Recreate the build on your server

   Install dependencies and run the build with production env vars present. Bolt.new apps frequently depend on build-time environment variables that are auto-injected in their cloud environment but must be set manually on a VPS. A build that succeeds locally may still fail on the server due to architecture differences or missing system libraries.

   • Install all dependencies with the same package manager Bolt.new uses. Run install with the frozen lockfile flag to get deterministic builds.
   • Run the production build and fix any missing dependency or type errors. Pay special attention to native modules that may need compilation.
   • Load environment variables from the server deploy panel or a .env file outside the repo. Never commit .env files with production values.
   • Check for build-time environment variables like NEXT_PUBLIC_* or VITE_* that must be present during the build step, not just at runtime.
   • Run the build twice: once locally to confirm it passes, once on the server to catch environment-specific issues like missing system tools or memory limits.
3. 03

   Start the process and keep it alive

   A VPS needs a process manager. The app will not stay running on its own after you close the SSH session. Bolt.new apps are often single-process servers that crash silently when they hit unhandled promise rejections or memory limits.

   • Use PM2, Docker, Docker Compose, or your deploy panel to start the app as a managed service with auto-restart on crash.
   • Capture logs with journalctl, PM2 logs, or docker logs and confirm the app binds to the expected port without errors.
   • Add the A record for your domain, enable HTTPS via Certbot or Caddy, and run a full smoke test covering login, data writes, and API endpoints.
   • Set up a health check endpoint and configure your process manager to restart the app if it becomes unresponsive.
   • Configure log rotation to prevent the app logs from filling the server disk over time.