Back to blog
One-Click Vercel Deployments: How It Works Under the Hood — CloudCode blog

One-Click Vercel Deployments: How It Works Under the Hood

6 min readDeep Dive

Clicking Deploy in CloudCode kicks off a chain of events — deployment-type detection, file preparation, upload, and a readiness check. We walk through every step.

What Actually Happens When You Click Deploy

The Deploy button in CloudCode looks simple. You click it, a progress indicator runs, and your project is live on a Vercel URL. You don't need a Vercel account, a token or the Vercel CLI — deploys go through CloudCode's own Vercel integration. But between your click and that live URL, a sequence of steps takes place. Understanding that sequence will help you debug deployments when they fail and make better decisions about how you structure your projects.

Step 1 — Choosing a Deployment Type

When you deploy from the preview toolbar, CloudCode asks what kind of deployment you want: a Static Site or a Node.js App. It pre-selects Node.js App when it finds an 'index.js', 'server.js' or 'app.js' containing an Express or Node http server ('require("express")', 'app.listen', 'createServer'). The dialog also lists any files a static deploy will leave out, so there are no surprises.

You can also deploy from Project Dashboard → Deploy, where you pick an environment (Development, Staging or Production) and a source: all files, the project root, or a single workspace. Production deploys ask for confirmation first.

Step 2 — Preparing Your Files

Next, CloudCode prepares the file set it will send. For a Static Site, it drops 'package.json' and any detected server entry file, generates a minimal 'index.html' if you don't have one, and adds a single-page-app fallback so unknown paths route to 'index.html'. For a Node.js App, it deploys the detected entry file as a Vercel serverless function and routes every request to it.

In both modes CloudCode writes its own 'vercel.json' (which allows the deployment to be embedded in the Live preview) and injects a small logger script into each HTML page so the Live preview can show console output and fetch requests.

Step 3 — Project Registration

Dashboard deploys use your project name as the Vercel project name, with the environment and workspace appended, so Development, Staging and Production each live in their own Vercel project. Deploys from the preview toolbar always target production.

Step 4 — File Upload

We upload the prepared files to Vercel's deployment API, and Vercel serves them from its global network.

Step 5 — Waiting for Ready

CloudCode polls the Vercel API for up to three minutes until the deployment reports ready. If you deployed from the preview toolbar, the Preview tab switches to Live automatically so you can see the deployed site right away.

Step 6 — URL and Error Reporting

You get the deployment's unique '*.vercel.app' URL. If Vercel reports a failed deployment, the last lines of its error output are shown directly in CloudCode, so you can see what went wrong without switching to the Vercel dashboard.

Common Deployment Issues and How to Fix Them

A page looks different from the Dev preview. The Dev preview bundles your app in the browser with Sandpack; the deployment serves the files that were deployed. Open the Live preview's Console and Network drawers to see errors and failed requests from the deployed site.

Configuration is missing. The environment variable manager is a record of the configuration your app expects, but variables aren't injected into one-click deployments. Put public, browser-safe values (an API base URL, a Supabase URL and anon key) in a config module in your code, and keep real secrets server-side.

You need your own domain or your own Vercel project. Push the project to GitHub and import the repository into your own Vercel account. From there you can add a custom domain and set environment variables in Vercel.

Deployment History

In the Deploy panel you can see your deployment history for each environment — status, deployment URL and time for every deploy. To go back to an earlier version, restore the files you want (from a file's version history or a GitHub pull) and deploy again.