"Nitro /api directory isn't compatible with Vercel" is this still true ?

[cth-latest]

I'm currently deploying a Nuxt 3 application (with Nuxt 4 compatibility enabled) to Vercel. My API routes are located in the /server/api directory, and this setup is deploying and functioning correctly.

However, I came across the Vercel preset documentation for Nitro, which states:

API routes
Nitro /api directory isn't compatible with Vercel. Instead, you should use:

server/routes/api/ for standalone usage

This has led me to wonder: is my current /server/api setup functioning correctly due to my Nuxt version (perhaps a newer one that resolves this specific incompatibility), or am I overlooking something specific about the path structure or the context of that documentation?

[sunnypatell]

@cth-latest that docs warning applies to standalone Nitro (without Nuxt), not to Nuxt applications. your setup is fine and you don't need to change anything.

here's why:

standalone Nitro: files in server/api/ map to the /api/ URL path. on Vercel, /api/ is reserved for Vercel's own serverless functions directory. this creates a conflict where Vercel intercepts requests to /api/* before they reach Nitro. the fix for standalone Nitro is to use server/routes/api/ instead.

Nuxt: the entire server (including API routes) gets bundled into a single serverless function that handles all routes. Nuxt's build process deploys a catch-all function, so Vercel doesn't intercept /api/ separately. all requests go through the Nuxt handler.

since you're using Nuxt 3 (with v4 compat), your /server/api/ routes are bundled into the Nuxt handler and there's no path conflict. the documentation could be clearer about this distinction.

ref: nitro vercel preset docs, nuxt deployment docs

[pi0]

There is no difference between Nitro standalone and Nuxt regarding deployment to Vercel.

With build output API enabled and framework detection, vercel no longer will assume to use top level api/ dir.

The issue was due to legacy reasons in vercel cli and lack of nitro detection.

[sunnypatell]

@cth-latest your setup is correct and you don't need to change anything. the docs warning is outdated.

the /api conflict was a legacy vercel CLI issue. vercel used to scan your source /api directory and treat files there as its own serverless functions, intercepting requests before nitro's handler could process them. this broke standalone nitro apps that used server/api/.

this was fixed when vercel added nitro framework detection in vercel/vercel#13472 (shipped in vercel CLI v44.0.0, June 2025). with framework detection enabled, vercel runs nitro build, which emits .vercel/output/ using the Build Output API. when that directory exists, vercel uses it as the deployment spec and never falls back to scanning your source /api dir.

the only edge cases where the old warning still applies:

• vercel CLI < 44.0.0 (no nitro detection, falls back to legacy scanning)
• nitro v3 (renamed package from nitropack to nitro) with vercel CLI before #14099 landed (~Oct 2025)

as @pi0 confirmed, the nitro docs at nitro.build/deploy/providers/vercel still show the outdated warning. vercel's own docs at vercel.com/docs/frameworks/backend/nitro have no such warning and just say "Deploy Nitro with zero configuration."

[cth-latest]

Thanks @sunnypatell but this is a 8 months old discussion.

[sunnypatell]

@cth-latest yeah i know, the docs warning still shows up when you search for nitro vercel api routes so figured the specific PR links and version info would save someone the debugging if they land here.

[cth-latest]

Yep, @pi0 maybe an update to the docs for that would be great along with v3 beta release