Your AI-built app already deploys on Vercel. A coding agent keeps adding route rules to vercel.json, and six months later nobody remembers why they are there. Vercel announced on November 2, 2026 that every project can use vercel.toml. It supports the same configuration properties as vercel.json, but lets you add comments and use a flatter structure. The practical value is a configuration file a human can review before an agent changes deployment behavior.

Choose TOML for readability, not novelty

If your current file has three clear settings, migration may have no payoff. Vercel's documentation points to larger configurations, many rewrites, or multiple services in one project as better fits. A comment can explain why /api routes to a backend, why an old URL must redirect, or why a setting must not be removed. That context is especially useful when a coding agent proposes a clean-looking but incomplete edit.

The important constraint is one project configuration file at the repository root: vercel.toml, vercel.json, or vercel.ts. Do not add TOML beside an existing JSON file and assume precedence. Put the migration on a branch, keep the old version in Git history, and remove or rename the old file in the same change.

A copyable static-app example

Suppose npm run build generates a static site in dist. Put this file at the project root. Do not copy outputDirectory = "dist" into a Next.js or other framework project without checking what its build actually emits: this is a deliberately narrow static-app example.

"$schema" = "https://openapi.vercel.sh/vercel.json"

# The static app writes output to dist/
buildCommand = "npm run build"
outputDirectory = "dist"
cleanUrls = true

buildCommand runs the build, outputDirectory locates its output, and cleanUrls removes .html extensions from eligible URLs. The property names follow Vercel's own example. The comment is a claim about your app, so check package.json and the actual build output. If the files land somewhere else, change the path before deploying.

Syntax validation is only the first test

1. Parse the file. Python 3.11+ includes tomllib. On an older Python, install tomli and run python3 -c "import tomli,pathlib; print(tomli.loads(pathlib.Path('vercel.toml').read_text()))". I parsed the example locally with tomli and checked its expected keys. That only establishes TOML syntax.
2. Compare the previous behavior. List routes, rewrites, redirects, headers, cron jobs, and build-related settings before migrating. A valid file can still drop a rule your app needs.
3. Deploy to preview. Open the homepage, an inner page, and every important API route. Compare responses and build logs with the previous configuration. Promote the change only after those checks pass.

A prompt that makes an agent's migration reviewable

If you ask a coding agent to do the conversion, give it an auditable boundary. Try: “Read the current project config and package.json. Propose one equivalent vercel.toml. Preserve every route, rewrite, redirect, and build setting. Add comments only to explain decisions. Do not modify environment variables or secrets. Return a table mapping each old property to its new location and flag anything you could not verify. Run the local build and parse the TOML, but do not deploy to production.” The mapping table lets you notice a missing rule while it is still a pull-request diff.

After reviewing that diff, run npm run build locally and confirm dist exists for this example. If the preview breaks a route, revert the configuration commit and compare it with the previous JSON; avoid patching production blindly. Keep your test URLs in the PR so the next configuration change has a repeatable checklist rather than relying on memory.

Vercel confirms availability and configuration-property parity. I did not deploy this example to a Vercel account. The local check covered TOML syntax and keys, not your framework's deployment semantics. If your project uses Services, complex rewrites, or dynamic vercel.ts, start with Vercel's documented Services example and verify a preview before replacing the existing file.