vercel-services

Deploy multi-service projects with Vercel

Services let you deploy multiple independently-built units within a single Vercel project. The typical use case is combining different runtimes (e.g. Python + JavaScript) in one deployment with shared routing and environment variables, but services work for any combination — multiple services of the same runtime, different frameworks, or a mix.

This skill covers project structure and configuration. For the actual deployment, defer to the deployments-cicd skill.

How It Works

A service is an independently built unit within your project, deployed to the same domain under a unique subpath. At build time, Vercel builds each service separately. At request time, Vercel routes incoming requests to the correct service based on the URL path prefix (longest prefix wins).

• Services are enabled via the experimentalServices field in vercel.json (see reference project).
• vercel dev -L auto-detects frameworks and runs all services locally as one application, handling routing automatically. The -L flag (short for --local) runs without authenticating with Vercel Cloud.
• Only vercel.json lives at the root. Each service manages its own dependencies independently.

Configuration

Define services in vercel.json:

{
  "experimentalServices": {
    "web": {
      "entrypoint": "apps/web",
      "routePrefix": "/"
    },

The project's Framework Preset must be set to Services in the Vercel dashboard.

Configuration fields

Do not add unknown fields — they will cause the build to fail.

Supported runtimes and frameworks

Services is in beta. Python and Go are tested and production-ready. Other runtimes may work but are not yet validated.

Python

Works with FastAPI, Flask, Django, or any ASGI/WSGI application. Framework is auto-detected. Set entrypoint to the application file (e.g. "backend/main.py"). Dependencies go in pyproject.toml in the service directory.

Go

Set entrypoint to the service directory (e.g. "backend"), not a file. Must set "framework": "go" explicitly in vercel.json — auto-detection does not work for Go services. Dependencies in go.mod in the service directory.

Other runtimes (untested)

Vercel supports Node.js, Bun, Rust, Ruby, Wasm, and Edge runtimes for functions. These can theoretically be used as services but are not yet validated.

Routing

Vercel evaluates route prefixes from longest to shortest (most specific first), with the primary service (/) as the catch-all. Vercel automatically mounts services at their routePrefix, so service handlers should not include the prefix in their routes.

For frontend frameworks mounted on a subpath (not /), configure the framework's own base path (e.g. basePath in next.config.js) to match routePrefix.

Environment variables

Vercel auto-generates URL variables so services can find each other:

SERVICENAME is the key name from experimentalServices, uppercased. If you define an env var with the same name in project settings, your value takes precedence.

Usage

1. Read references/fastapi-vite/ for the canonical project layout.
2. Adapt the structure to the user's chosen runtimes — services can use any supported runtime, not just the ones in the reference.
3. Define service routes without the route prefix — Vercel strips the prefix before forwarding.
4. Validate that each service in vercel.json has entrypoint and routePrefix. Only set framework when auto-detection fails (required for Go).

Output

After scaffolding, present the created file structure to the user. After deployment, present the deployment URL (refer to the deployments-cicd skill for details).

Troubleshooting

404 on routes after deployment

The project needs the Services framework preset:

1. Go to Project Settings → Build & Deployment → Framework Preset
2. Select Services from the dropdown
3. Redeploy

Routes return unexpected results

1. Ensure all services are picked up by vercel dev — check logs. If a service is missing, verify vercel.json. Try setting framework explicitly.
2. Validate route prefix behavior: handlers declare routes without routePrefix (e.g. /health), but requests from other services use the full prefix (e.g. /api/health).
3. For frontend services on a subpath, confirm the framework's base path config matches routePrefix.