Vercel adds vercel.toml project configuration with comments and flatter layout

What happened

Vercel projects can now be configured with a vercel.toml file, according to a changelog post on the Vercel blog. The new option is available to all projects and joins the existing vercel.json and vercel.ts formats.

According to Vercel, every configuration property that works in vercel.json also works in vercel.toml, so nothing is lost by switching. What changes is the ergonomics of the file: TOML allows inline comments, and it expresses configuration with less nesting than JSON.

What the new format buys you

Comments are the most obvious improvement. JSON has no comment syntax, which means teams configuring builds, rewrites, or headers in vercel.json have had to either document the reasoning behind a setting somewhere else or leave it unexplained. With vercel.toml, a note about why a particular rewrite or service setting exists can sit directly next to it.

The shallower layout comes from TOML's table syntax. Instead of deeply nested JSON objects, related settings are grouped under section headers such as [services.frontend], and repeated entries, like rewrite rules, are written as arrays of tables using the [[rewrites]] form. The result is a file that reads top to bottom rather than as one large nested object.

The example Vercel provided

The changelog post demonstrates the format with a project that runs two services: a Next.js frontend and a FastAPI backend. The file first points a "$schema" key at Vercel's OpenAPI specification, then defines each service in its own section. The frontend's root is set to frontend/, while the backend's root is backend/ with main:app as its entrypoint.

Two rewrite rules follow. Requests matching /api/(.*) are routed to the backend service, and everything else falls through to the frontend. Because the example is written in TOML, each block can carry a comment identifying what it configures, which is exactly the kind of annotation JSON cannot hold.

One configuration file per project

Vercel specifies a single constraint: a project should use exactly one configuration file, chosen from vercel.toml, vercel.json, or vercel.ts. Teams adopting the TOML format will need to remove any existing vercel.json rather than run the two side by side. The changelog post does not describe an automatic tool for converting existing JSON files to the new format.

Why it matters

Configuration files are read far more often than they are edited, and for anything beyond a trivial deployment — multiple services, rewrites, environment-specific settings — the ability to annotate a file is genuinely useful for the next person who opens it. The flatter structure also makes larger configurations easier to scan and to review in diffs.

There is a familiarity argument as well. TOML is already the configuration format used by Rust's Cargo, Python's pyproject.toml, and Netlify's netlify.toml, so many developers arriving at Vercel will have written this kind of file before. Bringing vercel.toml to parity with vercel.json costs existing teams nothing, since the old format keeps working, while giving new and growing projects a more maintainable place to keep their deployment settings.