Cursor deployment rescue

Cursor app works locally but will not deploy

Walkthrough

1. 01

   Audit what Cursor produced

   Cursor generates code based on your prompts but does not set up production build config, environment variables, or server infrastructure. Cursor may also generate platform-specific imports or dependencies that assume your local machine environment rather than a production server.

   • Check package.json for build and start scripts. Cursor may generate multiple scripts; identify which one is meant for production.
   • Confirm the Node version matches what the app expects. Check the engines field in package.json and verify it is available on the server.
   • List every environment variable the app reads from process.env by scanning the entire project for env references.
   • Check for absolute file paths or localhost references in the config files that will break on a different machine.
   • Review the generated tsconfig or build config for path aliases that may not resolve correctly in the production build.
2. 02

   Set up the production server

   The server needs dependencies installed, environment variables configured, and a process manager configured to keep the app alive. Cursor-built apps often use bleeding-edge framework versions that require specific system packages on the server.

   • Install all dependencies with the same package manager used locally. Use frozen lockfile for deterministic installs across environments.
   • Add environment variables to the server deploy panel or .env file outside the repository. Include every value the app reads at startup.
   • Set up a process manager (PM2, Docker, Docker Compose, or deploy panel) to restart the process on crash and on server reboot.
   • Install any system-level dependencies the app needs: Sharp for image processing, Puppeteer for browser automation, or Python build tools for native modules.
   • Configure the server firewall to allow traffic only on ports 80, 443, and any application-specific ports behind the reverse proxy.
3. 03

   Build, deploy, and test

   Run the production build and verify every integration works. Cursor apps frequently have integration points that work locally with emulators but fail in production because the real services behave differently.

   • Build the app on the server with production env vars loaded. Do not reuse the local build artifact.
   • Start the process and confirm it responds on the expected port with curl or a health check endpoint.
   • Test database connections, auth flows, file uploads, and any external API calls against the real production endpoints.
   • Verify the app handles errors gracefully by testing invalid inputs, missing parameters, and network timeouts.
   • Check the server resource usage during the first hour of operation to confirm the VPS has enough RAM and CPU for the Cursor-generated code.