Build Output API (v3) Feedback

[EndangeredMassa]

We have been working hard on the Build Output API (previously the File System API). Version 1 tested the waters, Version 2 exposed some pain points, and Version 3 is now ready for your feedback!

What is the Build Output API?

The Build Output API is an interface between framework builds and Vercel deployments that is serialized to and from the file system. It’s more of a concern of framework authors than app authors who deploy to Vercel.

If you are a framework author or a framework community member looking to integrate with Vercel, you can use the Build Output API to make deploys seamless for your framework.

All Vercel platform features are supported by the latest iteration of the Build Output API.

Version 1 (docs)

Version 1 supported static files and Node.js (only) serverless functions with some configuration options.

It did not completely support all of Vercel’s features. It was also a bit clunky to work with.

Version 2 (docs)

Version 2 was inspired by Next.js build outputs. It expanded on Version 1 to support more configuration options and Edge Functions. However, it ended up being harder to work with. Some framework authors preferred Version 1.

The documentation was greatly expanded to explain all the options.

Version 3 (docs)

Version 3 generalizes the interface further. It no longer bears a resemblance to Next.js’ build output. It is intended to be much easier to understand and implement.

We're also working on a new workflow where a build can be created locally with the vc build command, which creates .vercel/output in Build Output API format. You can inspect the result, then deploy it with vc deploy --prebuilt. This is great for debugging your build output (without having to deploy). It also allows users to deploy to Vercel without sending us their source code. Stay tuned for updates about this new CLI command!

Discussion

What feedback or suggestions do you have about Build Output API (v3)?

[magne4000]

After a first read, this is a lot easier to understand than the previous version! I'm going to migrate vite-plugin-vercel to this new version then give you some more feedback.
In the mean time, I noticed some inconsistencies in the doc:

• .vercel/output/functions/.func/.vc-config.json example mentions fields that are not described in the Configuration above it (launcherType, shouldAddHelpers and shouldAddSourcemapSupport).
• .vercel/output/config.json images field has no "Supported Properties" section, so we do not know which fields are authorized or required.
• As vercel.json routes configuration is legacy, it would be less confusing to create a "Supported Properties" section on the .vercel/output/config.json routes documentation (and existing doc is not explicit enough)
• Edge Middleware example references a middlewarePath property that is undocumented

[EndangeredMassa]

We're working on updates to the docs to explain these better.

[EndangeredMassa]

@magne4000 we just published more detailed documentation that I believe addresses all of your points (and more)! We'll continue iterating on it.

Note that the "legacy" label on routes is still accurate for non-Build Output API usage. So that will stay there.

https://vercel.com/docs/build-output-api/v3

[magne4000]

Spotted 2 small discrepancies in the .vc-config.json doc for Node.js:

• shouldAddHelpers type should be Boolean (in table)
• shouldAddSourcemapSupport type should be Boolean (in table)

[EndangeredMassa]

@magne4000 thanks! We'll get that updated.

[magne4000]

I'm not sure how to properly handle the following case. Let's say I have an endpoint /article/<article-slug> that renders blog articles:

• ✔️ I create a .vercel/output/functions/article.func folder with the necessary config underneath
• I create a .vercel/output/functions/article.prerender-config.json file for handling prerendering:
  • ❓ Does this handle /article/*, like /article/my-article? What If I want to have an endpoint for /article and another for /article/*?
  • ❓ If it handles /article/*, and I generate some SSG files at build time (let's say /article/article-1 and /article/article-2), where should they be generated on the file system and how do I link those files to the prerender-config?
• ❓ Bonus: What happens if I also create a .vercel/output/functions/article/my-article.func folder with necessary files? Which serverless/prerender function have precedence?

[EndangeredMassa]

@magne4000 Thanks for pointing this out! We're going to make this actually optional soon.

[magne4000]

If I understand correctly, /blog/one and /blog/two will never expire, correct? This means that contrary to v2 where statically generated files could expire, in this v3 they cannot?

In the output structure of that Prerender example, ya that's correct. /blog/one and /blog/two will never expire for that Deployment, as they were generated to be static files at "build time". The { handle: "filesystem" } route that comes before the catch-all route that points to the Prerender function means that those static files will be considered for serving before falling back to the Prerender.

@TooTallNate Just to be sure, outside this example alone, there is no way to have both behaviors? (perhaps with conditional routes with specific headers?)

[magne4000]

Or could I simlink multiple .vercel/output/functions/<name>.func to .vercel/output/functions/isr.func?

Yes, you should create a symlink. Indeed you can create multiple symlinks to the same underlying Serverless Function and they each can have their own <name>.prerender-config.json configuration.

I have a difference in behavior when using symlinks vs. copy:

• ✔️ When using copy: Routing works as intended, and my .prerender-config.json are applied
• ❌ When using symlinks: Routing is unpredictable. See details below

Here is what my FS looks like:

.vercel
└── output
    ├── config.json
    ├── functions
    │   ├── api
    │   │   ├── page.func
    │   │   │   └── index.js
    │   │   └── post.func
    │   │       └── index.js
    │   ├── pages
    │   │   ├── catch-all-FaYYFKNPYi-MIDZKlMiJG.func
    │   │   │   └── index.js
    │   │   ├── catch-all-FaYYFKNPYi-MIDZKlMiJG.prerender-config.json
    │   │   ├── function-OUwJlNi_mO8JN_C-fTaOj.func
    │   │   │   └── index.js
    │   │   ├── function-OUwJlNi_mO8JN_C-fTaOj.prerender-config.json
    │   │   ├── isr-WGplyCi0LaJu9dX2aLiIF.func
    │   │   │   └── index.js
    │   │   ├── isr-WGplyCi0LaJu9dX2aLiIF.prerender-config.json
    │   │   ├── named-NYSd4LkKVQMjIjXMtbxg5.func
    │   │   │   └── index.js
    │   │   └── named-NYSd4LkKVQMjIjXMtbxg5.prerender-config.json
    │   └── ssr_.func
    │       └── index.js
    └── static
        [...truncated]
        ├── catch-all
        │   └── a
        │       ├── b
        │       │   └── c.html
        │       └── d.html
        ├── function
        │   └── a.html
        ├── index.html
        ├── isr.html
        ├── manifest.json
        ├── named
        │   ├── id-1.html
        │   └── id-2.html
        ├── static.html
        └── vite-plugin-ssr.json

And the differences between our 2 cases:

• symlinks: .vercel/functions/pages/*.func are each a symlink to ../ssr_.func
• copy: .vercel/functions/pages/*.func are each a copy of ../ssr_.func

And here is the config.json in use for both cases:

{
  "version": 3,
  "routes": [
    {
      "src": "^/(?:(.+)/)?index(?:\\.html)?/?$",
      "headers": {
        "Location": "/$1"
      },
      "status": 308
    },
    {
      "src": "^/(.*)\\.html/?$",
      "headers": {
        "Location": "/$1"
      },
      "status": 308
    },
    {
      "handle": "filesystem"
    },
    {
      "src": "(/catch-all/(.+?))",
      "dest": "/pages/catch-all-FaYYFKNPYi-MIDZKlMiJG/?__original_path=$1"
    },
    {
      "src": "(/isr)",
      "dest": "/pages/isr-WGplyCi0LaJu9dX2aLiIF/?__original_path=$1"
    },
    {
      "src": "(/named/([^/]+?))",
      "dest": "/pages/named-NYSd4LkKVQMjIjXMtbxg5/?__original_path=$1"
    },
    {
      "src": "(/.*)",
      "dest": "/ssr_/?__original_path=$1"
    }
  ],
  "overrides": {
    "index.html": {
      "path": ""
    },
    "catch-all/a/b/c.html": {
      "path": "catch-all/a/b/c"
    },
    "catch-all/a/d.html": {
      "path": "catch-all/a/d"
    },
    "function/a.html": {
      "path": "function/a"
    },
    "named/id-1.html": {
      "path": "named/id-1"
    },
    "named/id-2.html": {
      "path": "named/id-2"
    },
    "isr.html": {
      "path": "isr"
    },
    "static.html": {
      "path": "static"
    },
    "404.html": {
      "path": "404"
    }
  }
}

When I try to access /function/b, I should match the last route { "src": "(/.*)" ... }:

• ✔️ copy: works
• ❌ symlinks: page is routed to /pages/named-NYSd4LkKVQMjIjXMtbxg5 (even if I remove the { "src": "(/named/([^/]+?))" ... } rule 🤨)

[TooTallNate]

Are you on the Vite Discord server? I'd like to chat more about your setup here to get a better understanding (and possibly some zip files to take a closer look).

[magne4000]

Was this issue fixed somehow since the APiv3 is now flagged as stable?

[chiyuki0325]

I just want to ask how to downgrade to build output V2 :(

A few days ago, Vercel seems to have made some "changes" to my account that when deploying a serverless function, vercel build appeared in the logs (this seems to be the new version), and the build output was very huge (just index.php, the output size was exceeds the 50MB limit), resulting in failure of normal deployment.

Is there a way to exit the "canary" or V3 version?

[zzy-ac]

ERROR
{"error":{"code":"not_found","message":"Deployment not found"}}https://api.vercel.com/v11/deployments/dpl_2wCd1egRZ3BedqguuETDiivBF3eD

I don't know if such information is useful, but it's probably the way it is.

[EndangeredMassa]

@zzy-ac What framework are you using? Can you try specifying one in your project settings?

[zzy-ac]

I am a php program deployed with other framework.

[foxdodo]

Thanks @YidaozhanYa @marctaule. We've disabled this for your account while we investigate those two issues.

Same issue on my site. May I have a rollback too?

[EndangeredMassa]

@zzy-ac @foxdodo we rolled out some fixes for this. Can you try again?

[happy124578]

Well I got this problem,too.
Is ther anyway to downgrade it to v2?

[TooTallNate]

Hey @happy124578. Would you mind elaborating? What is the error that you are experiencing?

[SaKongA]

Hey @happy124578. Would you mind elaborating? What is the error that you are experiencing?

Bro， i have the same error,i need downupgrade to v2, thank u,my site is

[SaKongA]

Hey @happy124578. Would you mind elaborating? What is the error that you are experiencing?

My username is zhcnpanda

[SaKongA]

Hey @happy124578. Would you mind elaborating? What is the error that you are experiencing?

Bro， i have the same error,i need downupgrade to v2, thank u,my site is

Like this

[EndangeredMassa]

@happy124578 @ZhcnPanda we rolled out some fixes for this. Can you try again and let us know if you still have an issue?

[JuanM04]

This versions feels easier to work with. Amazing work!

Btw, I saw an example of a serverless function with a node_modules/ folder inside. Is there any documentation on how to achieve this? I've tried with @vercel/nft but I had a hard time with pnpm symlinks

[EndangeredMassa]

Thanks!

You can use the readFile hook in nft to make it follow symlinks. Example: https://github.com/vercel/vercel/blob/2dc0dfa572c7d02b8ca3cbf7401df7dbeb7f93f6/packages/node/src/index.ts#L184-L212

[JuanM04]

Thank you, that helped! Another question related to that: can node_modules/ be used with Edge functions? Or do I need to bundle everything?

[TooTallNate]

You can place node_modules inside an Edge Function directory, but note that if they use Node.js-specific functionality then they probably won't work. The modules need to be more or less "pure JS".

[swamidass]

Good step forward.

I do have a question: how does one specify multiple prerender paths for a function? I looked closely at the documentation, and some of the prior response, but couldn't see a clear answer.

[TooTallNate]

Hey there @swamidass. Take a look at this Prerender Functions example. Specifically, there's a route configuration in that example that will direct all /blog/* requests to go through the prerender function.

Let me know if that answers your question 😄

[swamidass]

Thanks, but that seems to only work for a fixed path. What about a case where a single function is dynamically mapping to several paths?

[TooTallNate]

I might not be fully understanding your question, but it sounds like you could use multiple different route objects (possibly using wildcard / RegExp syntax for dynamic paths) in the routes configuration in the config.json file that point to the Prerender function.

[magne4000]

Another question, this time regarding routes rewrites.
Let's take the following config.js file:

{
  "version": 3,
  "routes": [
    { "handle": "filesystem" },
    { "src": "/blog/(?<slug>[^/]*)", "dest": "/blog/post?slug=$slug" }
  ],
}

If I call /blog/article-1 it will be rewritten to /blog/post?slug=article-1 and will be the value of request.url on the server.
Is there a way to retrieve the original url (i.e. /blog/article-1) on the server? Or is there a way to write a routes rule that would keep the original request.url?

Use case

I want to rewrite specific URLs to a file generated at build time. In this particular case the src regex cannot always match filesystem routing, or is really hard to infer. Let's take an example:

Let's take a framework that handles routing internally, with routes declared as such: export default '/film/:filmId'.
For this particular case, generating a serverless function in .vercel/ouput/functions/film.func is doable.

But what if I have a more complex case, like 2 routes: export default '/film/:filmId'/abc and export default '/film/:filmId'/def with 2 different handlers?
I cannot generate an only function .vercel/ouput/functions/film.func anymore, so I generate .vercel/ouput/functions/film_abc.func and .vercel/ouput/functions/film_def.func. Now automatic routing is broken.
And if I write a route rule like { "src": "/film/([^/]+?)/abc", "dest": "/film_abc/$1" }, the request.url on the server is /film_abc/something, which doesn't match any of my framework routes.

[magne4000]

Answering my own question:
I suppose I could write a rule that look like { "src": "(/film/([^/]+?)/abc)", "dest": "/film_abc/__original_path=$1" } and use the __original_path query parameter instead of the request.url

[magne4000]

OK, I tried and found an issue:

• ✔️ It works when no .prerender-config.json is present for the dest
  • e.g. resulting url: /film_abc/__original_path=...
• ❌ Query is empty if .prerender-config.json is present. Toying with allowQuery has no impact
  • e.g. resulting url: /film_abc

[EndangeredMassa]

In general: Yes, we'd like to add a mechanism for the original url to be available to the handler when a route rewrite is used, perhaps a header like x-matched-path. We're discussing this internally, but for now you can use the workaround you identified.

Pre-render Config: This is a consequence of how prerender routing works. You could get the original url from the x-now-route-matches header, like in this example.

Does that give you a path forward for now?

[magne4000]

Indeed this does help, thanks! Is x-now-route-matches header considered stable?

[EndangeredMassa]

@magne4000 That specific header is not considered stable at this moment, no. We're discussing changing how that works. If it changes, there will be a clear announcement about how to implement this use case.

[magne4000]

🔥 First beta version of vite-plugin-vercel released (starting from 0.1.0), with early support for vite-plugin-ssr. It lacks some detailed documentation for now, but it will come as things stabilize.

[magne4000]

Why does vercel build (Vercel CLI 24.2.5) command executes it's own build pipeline when a custom "BUILD COMMAND" is provided?
Is there a way to disable this behaviour? I want to compile all files myself, and not rely on vercel build for that

I just noticed this, but by looking at my first builds with API v3, it seems that it already happened back then.

EDIT: It seems to trigger the internal build steps because I have a /api folder with some TS file in it (but they are already compiled by my script)

[EndangeredMassa]

This won't work right now because api is a special Vercel directory. We're looking into ways to allow this behavior, but for now, you'd have to use a different directory name.

[noskovvkirill]

Hi! I'm trying to get any parameters from middleware built on Build Output API. For some reason, the request object is always empty. I couldn't find any examples in the folder utilizing those properties 🫤
Might be related vercel/next.js#35519
Any ideas why?

[EndangeredMassa]

The properties should be there, but if you log the object directly, you will see an empty result because the properties are not enumerable.

console.log(request); // {}
console.log(request.url); // 'https://my-vercel-project.vercel.app/?some=param'

To grab a query param, you can:

const url = new URL(request.url);
const some = url.searchParams.get('some');
console.log('some: ', some);

If that doesn't work, please let us know and we'll dig into it.

[noskovvkirill]

@EndangeredMassa Thank you! That worked as expected. I was trying to log _request.nextUrl by looking at Next.js docs on Middleware 😬

[frandiox]

Hi! I've successfully updated our Hydrogen example to v3 🎉

Some comments:

• If .vercel/output/config.json is wrong, it might throw cryptic errors. Perhaps some validation would be convenient. For example, I used routes: {...} instead of routes: [...] and only got e.map is not a function in the logs.
• ReadableStream constructor seems to be bugged. Perhaps it's still running on an old CFW version? It just hangs and times out. To workaround this, I had to polyfill it:

  import {ReadableStream} from 'web-streams-polyfill/ponyfill';
  Object.assign(globalThis, {ReadableStream});

• I see the global cache and cache.default are not available. Is there any alternative planned?

[TooTallNate]

Very cool! We will definitely add some validation for the various configuration files, it's on our list already. I'll have someone from the Edge Functions team comment regarding your other two points.

[EndangeredMassa]

Cache: This is something we're looking into, but there are no immediate plans to implement.

[bambooom]

I'm not sure is it right place to ask question here.

But I've got this error:

I searched and guess maybe it's about this buid output API. Since I would like to deploy a express.js app with /api folder for some requests, and I added a vercel.json which uses the rewrites feature like this:

{
  "rewrites": [{ "source": "/api/(.*)", "destination": "/api" }]
}

I followed the guide here.

I'm not sure why the error shows. And how should I config the json?

[EndangeredMassa]

We'll investigate and get back to you. Sorry for the trouble!

[scottmessinger]

I can't find a way to match a glob route and direct to a single serverless function. E.g., I want /my-route/can-be/nested?and=have-query-params to go to my serverless function my-route, but I can't find a way to do that. Is this possible in V3?

[amyegan]

You should be able to do something like in the build output api routes example with Path-to-RegExp syntax

[jmikrut]

Hey all, I'm trying to deploy Payload alongside of any existing Next app as a bunch of serverless functions, using the Build Output API.

I've got a simple example function deploying properly to Vercel, but the problem is that next dev does not pick up the endpoints that I've added with the build output API, and therefore local development with Payload + Next alongside of each other in the same repo becomes impossible.

Any thoughts here? Is something like this on the roadmap? I realize this is probably more of a Next issue vs. specifically related to the Build Output API so I'll likely go and open a corresponding discussion there.

Thanks!

[leerob]

Hey there, yeah this is a known opportunity for improvement. There currently isn't a great local iteration story. We'd like to make this better still 🙏

[eltigerchino]

Are the TypeScript schemas available as an npm package? or are we encouraged to create our own types.d.ts file with the schemas from the docs?

[EndangeredMassa]

There's no current type package to consume. We would like to add that in the future, though.

[lordofthecactus]

I’m trying to do an edge function deployment with the Build Output API v3.

I’m getting the following error on after building and deploying with —prebuilt.

‘the edge function ‘hydrogen’ is referencing unsupported modules’

Not sure how to solve this. Perhaps there is documentation missing for these errors?

[leerob]

Are you trying to deploy Hydrogen 2.0 with Remix it seems? We do have built-in support for Remix and Hydrogen 1.0, but I don't believe 2.0 works just yet.

[lordofthecactus]

Yes 💯 this is correct!

We have in the Hydrogen 2.0 repo multiple requests of devs wanting to deploy to Vercel. I was hoping to do a quick example with edge functions for them although I have been unable to.

As you mention, Hydrogen 2.0 does not work out of the box just yet. So I was trying to use what my teammate @frandiox did with Build Output v3. And this is the latest error I got.

Best case would be if Vercel had H2 out of the box 😄😉

[lordofthecactus]

Created an issue to track this. https://github.com/orgs/vercel/discussions/1605 hope that is alright 🙏

[anmonteiro]

The docs page seems to have formatting issues wrt the code snippets https://vercel.com/docs/build-output-api/v3.

[leerob]

Hey, thank you! This has been fixed.

[james-elicx]

Hello, could I please get some clarification about the Handler Route phases? From my understanding, each of these phases runs at different points during routing. This is the flow that I believe takes place and I would appreciate some clarification as to whether this is accurate or not.

1. source routes not under a handler route are processed.
2. filesystem -> occurs if the pathname was not found in .vercel/output/functions or .vercel/output/static.
   • if check is true on the route, skip to the rewrite phase with the value from dest, then check the filesystem phase with the rewritten path.
3. resource -> ???
4. miss -> occurs if the filesystem phase resulted in a miss.
   • if check is true on the route, skip to the rewrite phase with the value from dest, then check the filesystem phase with the rewritten path.
5. rewrite -> always occurs.
   • check the new pathname exists.
6. hit -> always occurs if the final pathname exists.
7. process the route's default entry and get the response object.
8. error -> occurs if the response object has a status code that matches its routes.
9. return response.

I'm not sure if I'm understanding how the flow for the routes array from the build output works. Any guidance and clarification would be very much appreciated - a flowchart/diagram could also be cool.