The Complete Guide to Vercel Services

Vercel Services lets you run multiple frontends and backends in a single Vercel project, each deployed to the same domain under its own path prefix. You can pair a Next.js frontend with a Python or Go backend in one repository and deploy them together with shared routing, environment variables, and a single domain, instead of splitting your monorepo into separate Vercel projects.

In this guide, you'll learn how Vercel builds and routes requests across the services in one project, how to define services in your vercel.json, and how to configure routing and cross-service communication. You'll also run your services locally during development and troubleshoot the most common routing and configuration problems.

Vercel Services run several independently built applications inside one project, each mounted at its own path on a shared domain. To a visitor, the whole project looks like a single site at a single URL, each service is built and deployed as its own unit.

A service moves through two phases:

• Build Time: each service is built separately, using that service's own framework, dependencies, and build step.
• Request Time: each incoming request is routed based on the URL path prefix.

Because each service builds on its own, a single project can combine different frameworks and runtimes. For example, one project might contain:

• A Next.js frontend at /
• A Python FastAPI backend at /svc/api
• A Go server at /svc/go

All of these services share the same deployment URL, so they can serve both the frontend and backend from a single domain without separate projects.

Use Vercel Services when you want to deploy more than one application from a single repository to a single domain. They fit two main cases:

• A polyglot monorepo: JavaScript frontend and a Python backend in the same repository that you want to deploy as one project.
• Multiple backends: several API services, each with its own framework requirements, dependencies, and build step.

You don't need services if your project uses a single framework, such as a Next.js app with API routes. In that case, deploy the project as usual. If your monorepo contains separate applications that you'd rather mount under separate domains, deploy them as separate projects in a monorepo instead.

Vercel Services is available in Beta on all plans. Because the feature is in Beta, the configuration uses the experimentalServices key in vercel.json, and the details may change before general availability.

Before you set up services, make sure you have:

• A Vercel project connected to a repository that contains more than one application, such as a frontend and a backend.
• The ability to set the project's framework to Services in your project settings.
• Vercel CLI installed (npm i -g vercel)

Define your services in vercel.json and set the project's framework to Services. New deployments then build each service separately and route requests by path prefix.

1. Set the project framework to Services:
   • In your project’s Build and Deployment settings, set the framework to Services. Projects only build as services when this setting is selected, and experimentalServices is present in vercel.json.
2. Add an experimentalServices block to vercel.json:
   • Define services with an entrypoint, and give each web service a routePrefix:
     vercel.json

     {
       "experimentalServices": {
         "frontend": {
           "entrypoint": "apps/web",
           "routePrefix": "/",
           "framework": "nextjs"
         },
         "backend": {
           "entrypoint": "backend/main.py",
           "routePrefix": "/svc/api",
           "framework": "fastapi"
         }
       }
     }

3. Match a subpath frontend's base path to its route prefix:
   • If a frontend is mounted on a subpath rather than at /, set the framework's base path to match its routePrefix.
   • For Next.js, set basePath in next.config.js to the same value.
   • Backends don't need this step, because Vercel mounts them at their routePrefix automatically.
4. Deploy your project as you normally would. Vercel builds each service separately and serves them all from one deployment URL.

Each entry under experimentalServices accepts the following fields:

Vercel merges all services' routes into a single routing table and routes each request to the service based on its route prefix. Vercel evaluates prefixes from longest to shortest, so the most specific prefix wins, and the primary service at / acts as the catch-all for anything that doesn't match a more specific prefix.

With a Next.js frontend at / and a FastAPI backend at /svc/api, requests to your project route like this:

Vercel doesn't strip the prefix before the request reaches a backend, so the backend receives the full path, including its routePrefix. Mount your backend routes under the same prefix you set in vercel.json.

When you set a routePrefix, Vercel mounts backend services at that base path automatically, so you don't need to configure a framework-specific root path for a backend. Frontend frameworks are the exception. A frontend mounted on a subpath still needs its own base path set (for example, basePath in next.config.js) to match its routePrefix.

Vercel automatically generates environment variables so your services can call each other without hardcoding URLs. For each web service, Vercel injects two variables:

For a project with a Next.js frontend service at / and a FastAPI backend service at /svc/api, Vercel generates:

Use the server-side {SERVICENAME}_URL variables for requests between services:

// Server-side code in the frontend service
const response = await fetch(`${process.env.BACKEND_URL}/users`);
const users = await response.json();

Use the NEXT_PUBLIC_{SERVICENAME}_URL variables for requests from the browser:

// Client-side code in a Next.js component
const response = await fetch(`${process.env.NEXT_PUBLIC_BACKEND_URL}/users`);
const users = await response.json();

Client-side variables resolve to relative paths (the route prefix only), so the browser sends them to the current origin. This avoids CORS issues and keeps them working across preview deployments and custom domains. If you define an environment variable with the same name in your project settings, your value takes precedence over the one Vercel generates.

Run all of your services together on your machine with vercel dev, adding the -L flag (short for --local) to start them without authenticating with the Vercel Cloud:

vercel dev -L

This builds and serves every service in your vercel.json locally, with the same path-prefix routing they use in production.

A project builds as services only when two conditions are both true: the project's framework is set to Services, and vercel.json contains an experimentalServices key. If either is missing, Vercel falls back to its default framework detection and ignores your services configuration. Confirm both, then redeploy.

Vercel mounts backends at their routePrefix automatically, but frontend frameworks need their own base path. If a frontend mounted on a subpath fails to load its routes or static assets, set the framework's base path to match the service's routePrefix. For Next.js, set basePath in next.config.js to the same value as routePrefix.

Vercel evaluates routePrefix values from longest to shortest, with / as the catch-all. If requests land on the wrong service, check that your prefixes don't overlap in a way that routes traffic to a broader prefix first. Give each backend a distinct, specific prefix, and reserve / for the primary service.

Vercel doesn't strip the route prefix before forwarding a request to a backend, so the backend receives the full path, including its routePrefix. If your backend returns 404s for routes you expect to work, mount those routes under the same prefix you configured. For example, define /svc/api/users rather than /users when the prefix is /svc/api.

Vercel injects {SERVICENAME}_URL and NEXT_PUBLIC_{SERVICENAME}_URL for each web service. If one of these holds a value you didn't expect, check whether you've defined an environment variable with the same name in your project settings, since your value takes precedence over Vercel's generated one. Remove or rename the conflicting variable to use the generated value.

For requests from the browser, use the NEXT_PUBLIC_{SERVICENAME}_URL variables rather than an absolute URL. These resolve to relative paths against the current origin, so the browser treats them as same-origin requests and avoids CORS errors.

Learn how to build on Services with these two step-by-step guides. Both create a real-time, full-stack app by pairing a frontend with a WebSocket backend within a single Vercel project that deploys to one domain.

• Read Services routing and communication for the full details on route prefixes, environment variables, and cross-service communication.
• Compare services with separate projects in a monorepo to choose the right structure for your repository.
• Review Vercel plans and release phases to understand Beta availability.
• Browse more backend guides for building and hosting APIs alongside your frontend.