Skip to main content
An unbranded vintage instant camera on an oak table against a lemon-yellow wall, pushing out a blank undeveloped print, a metaphor for Vercel instant deployments that go live without a build step
8 min readBy Carlos Aragon

Vercel Instant Deployments: 23 Tests, What Skips the Build

A Vercel instant deployment is a plain static folder deployed from the CLI or API that goes live without a build machine: no .js files, no vercel.json or package.json, at most 100 files and roughly 25 MB. Vercel added CSS, images and fonts to it two days ago. The docs list the main rules, but not all of them. This morning I deployed 23 throwaway sites to find the edges. A 404.html, a CNAME file or a .vercelignore each quietly put me back on a build machine.

Which Static Sites Skip the Build?

Every row is a fresh project deployed with vercel deploy <dir> --prod from Vercel CLI 66.5.0. The base site was an index.html, an about.html, a stylesheet, a PNG, an SVG, a WOFF2 font, a Markdown file and robots.txt. Each "+" row adds one thing to that base. I counted a deployment as instant when the API reported ready equal to createdAt and the build log was empty.

What the folder hadResultIn the docs?
HTML only (1 file)InstantYes
HTML + CSS, PNG, SVG, WOFF2, .md, robots.txtInstantYes
+ site.webmanifest and favicon.icoInstantYes
+ JSON feed and sitemap.xmlInstantYes
+ uppercase PHOTO.JPGInstantNot stated
+ .well-known/security.txtInstantNot stated
+ nested docs/index.html, blog/post/index.htmlInstantNot stated
+ inline <script> and external CDN <script src>InstantNot stated
100 filesInstantYes
25,164,266 bytes (24 MiB)InstantOver "25 MB" in decimal
+ .vercelignore that lists itselfInstantNo
+ assets/app.jsBuiltYes
+ package.jsonBuiltYes
+ vercel.json (just cleanUrls)BuiltYes
+ public/ folderBuiltYes
101 filesBuiltYes
27,265,418 bytes (26 MiB)BuiltYes
+ data/export.csvBuiltImplied
+ CNAME (no extension)BuiltImplied
+ style.css.mapBuiltImplied
+ 404.htmlBuiltNo
+ .vercelignore (excluding the .js file)BuiltNo
Build command set in project settingsBuiltYes (and it failed)

The rule that actually decides it is narrower than "static": every uploaded file needs an extension from Vercel's allowlist. The fast static deployments docs say JavaScript "or other unsupported files" disqualify you, and that phrase covers far more than it sounds like. A CSV export, a source map and a CNAME left over from GitHub Pages are all normal things to find in a static folder, and each one cost me the instant path.

JavaScript inside the HTML is fine, though. A page with an inline <script> and a third-party <script src> from a CDN stayed instant. Only a .js file in the upload counts.

How Much Time Does It Save?

Less than the "single-second" headline suggests, because a static build on Vercel was already fast. I redeployed the same two sites five times each, alternating: the base site (instant) and the base site plus one app.js (built). Timing is the full vercel deploy command from my Mac mini in Allen, Texas, upload included.

  • Instant: 2.18 to 2.70 s wall time, median 2.47 s. Zero seconds between created and ready.
  • Built: 3.87 to 4.76 s wall time, median 4.01 s. Median 2.16 s between created and ready.

So it saves about 1.5 seconds per deploy. You won't notice that on a landing page you ship twice a week. The bigger difference is what didn't happen. The built deployment of an HTML page and one script still booked a build machine to copy files:

Running build in Washington, D.C., USA (East) – iad1
Build machine configuration: 4 cores, 8 GB (Standard Build Machine)
Downloading 9 deployment files...
Running "vercel build"
Vercel CLI 66.2.0
Build Completed in /vercel/output [25ms]
Deploying outputs...
Deployment completed

The instant one had no build log at all. That matters if an agent publishes dozens of HTML reports or previews a day, and Vercel says that's the use case it built this for. It also lines up with the Nov 17 changelog moving standard builds to usage-based billing for new teams. I didn't check how instant deployments are billed, so don't read that as a pricing claim. All I can say is there was no build to bill.

One more number. The 100-file site took 10.6 seconds the first time, because the CLI uploaded 100 new files. The 101-file site right after it took 4.4 seconds, because Vercel deduplicates uploads by hash and 100 of them were already there. Upload time is usually the real cost.

Why Is My Static Site Still Building?

These are the four that surprised me, in the order I'd check them.

1. You have a 404.html

Adding a custom 404.htmlto the base site sent it to a build. The docs don't mention it. On the built deployment Vercel served my page for missing URLs. On the instant ones every missing URL got a plain-text 404. You pick one: a custom 404 page or the instant path.

2. You added vercel.json to get clean URLs

The older advice for plain HTML sites on Vercel is to drop in a vercel.json. A file holding nothing but {"cleanUrls":true} forces a build. Without it, /about returns 404 and only /about.html works, on both paths. The fix that keeps you instant is folders: docs/index.html served at /docs and /docs/ on the instant path. If you're using vercel.json for more than that, my vercel.toml vs vercel.json tests cover what the config files do. Just know either one costs you the instant path.

3. Your .vercelignore disqualifies itself

This one is my favorite. The natural fix for a stray app.js or CNAME is to ignore it. I did, and the deployment still built. The file list from the API showed why: the CLI uploaded .vercelignore itself, and a dotfile with no extension is an unsupported file. Adding one line fixed it:

# .vercelignore
*.js
CNAME
.vercelignore   # without this line the file itself disqualifies the deploy

With that line the same folder deployed instantly and /assets/app.js returned 404, so the ignore rules still applied.

4. The project has a build command

Project settings count too. I set a build command of echo custom on a project whose last deploy had been instant, and redeployed the same folder. It went to a build machine and failed:

Error: [STATIC_BUILD_NO_OUT_DIR] No Output Directory named "public" found
after the Build completed. Configure the Output Directory in your Project Settings.

Clearing the build command brought the next deploy straight back to instant. The docs say a framework preset or other custom build settings do the same, so check project settings if a clean folder still builds.

Then there are the documented ones: deploying from Git, a package.json, a public/ folder or any .js file. Those behaved exactly as the docs say.

Is the Limit 25 MB or 25 MiB?

The docs say "up to 25 MB". I deployed 23,002,442 bytes, then 25,164,266 bytes, then 27,265,418 bytes. The 25.16 MB site stayed instant and the 27.27 MB one built. 25.16 MB is over 25 MB in decimal units but under 25 MiB (26,214,400 bytes). So the cap looks like 25 MiB. I didn't test between 25.16 and 27.27 MB, so the exact cutoff is a guess. Leave yourself some room either way.

The file count is exact: 100 files instant, 101 built. Hidden folders upload too. My .well-known/security.txtuploaded and was served, and it didn't break eligibility because .txt is on the list.

Does an Instant Deployment Serve Files Differently?

I compared the instant base site against its built twin (same files plus app.js) on eight paths. Same status codes and the same cache-control: public, max-age=0, must-revalidate. Same content types too: text/markdown for .md, font/woff2 for the font, text/css for the stylesheet. Markdown is served raw, not rendered. Apart from the 404 page, a visitor can't tell which path a site took.

To check which path a deployment took, ask the API instead of reading the CLI output:

# is this deployment instant? (VERCEL_TOKEN + team id in env)
D=my-site-abc123-myteam.vercel.app
curl -s -H "Authorization: Bearer $VERCEL_TOKEN" \
  "https://api.vercel.com/v13/deployments/$D?teamId=$TEAM" \
  | jq '{createdAt, buildingAt, ready, built: (.ready != .createdAt)}'

On every instant deployment createdAt, buildingAt and ready were the same millisecond, and /v3/deployments/<id>/events came back empty. If you run this from CI and the Vercel side surprises you in other ways, my notes on the Node 20 discontinued error cover another recent way Vercel deploys started failing.

Should You Restructure a Site for It?

For a human-built site, mostly no. Saving 1.5 seconds isn't worth losing a custom 404 page or clean URLs, and anything with a framework builds anyway. A Next.js app like the one behind my use cache tests was never a candidate.

For agent output, yes. If a coding agent writes an HTML report, a mockup or a dashboard snapshot and deploys it, make the agent write folders that pass the checks: HTML with inline JS, assets with allowed extensions, nested index.html instead of clean URLs, no config files, and under 100 files. Then have it confirm with the API call above, the same way it should check anything else it ships. For longer agent jobs that deploy as one step of many, the Workflow DevKit makes each step retryable.

Vercel Instant Deployment FAQ

What is a Vercel instant deployment?

It's a deployment of a plain static folder that Vercel serves without starting a build machine. In my tests the deployment was ready at the same millisecond it was created, with no build log, and the whole vercel deploy command took about 2.5 seconds.

Why is my Vercel static site still building?

Usually because of one file. A .js file, vercel.json, package.json, a public/ folder, a 404.html page, a .vercelignore file, a CNAME or other extensionless file, a source map or a .csv each sent my test sites back to a standard build. So did more than 100 files, about 26 MB of assets, a Git-triggered deploy, or a build command in project settings.

How do I tell if a Vercel deployment skipped the build?

Fetch it from the API with GET /v13/deployments/<url>. On an instant deployment createdAt, buildingAt and ready are the same timestamp and /v3/deployments/<id>/events returns an empty list. A built deployment shows a build machine line and about 2 seconds between creation and ready.

Can I use clean URLs or a custom 404 page with instant deployments?

Not through config. cleanUrls needs vercel.json and a 404.html file both force a build. Use folders with index.html files instead: /docs/index.html served at /docs on the instant path. Missing pages get Vercel's plain-text 404.

Do instant deployments serve files differently?

Not that I could measure. The instant and built versions of the same site returned the same status codes, the same content types (text/markdown for .md, font/woff2 for fonts) and the same cache-control header.

How I Tested

November 20, 2026, from a Mac mini in Allen, TX, with Vercel CLI 66.5.0 (npm latest) and a token on my own team. A Python script generated each folder, ran vercel deploy <dir> --yes --prod, timed it, then read GET /v13/deployments and the events endpoint. Each of the 23 variants got its own new project named zz-inst-*, so no project settings carried over. I added 10 alternating timing redeploys and 2 build-command redeploys, for 35 deployments in total, then deleted all 23 projects. Built deployments ran on a Standard Build Machine in iad1 with Vercel CLI 66.2.0 inside the build. Random bytes stood in for the large media files. I didn't test Git deploys, single-file deploys, --temporary or the REST API path, or which other extensions break eligibility. The results reflect the rollout on this date, and Vercel can change the rules without a CLI update.

Agents That Ship Their Own Work

I build agent pipelines that write, deploy and verify their own output on Vercel, with checks at each step. If you want one that publishes reports or previews without babysitting, let's talk.

Related Posts