X Openai Vercel Services 91ca38e

---
name: x-openai-vercel-services-91ca38e
description: Vercel Services — deploy multiple services within a single Vercel project. Use for monorepo layouts or when combining a backend (Python, Go) with a frontend (Next.js, Vite) in one deployment.
metadata:
  priority: '7'
  docs: '[''https://vercel.com/docs/services'']'
  sitemap: https://vercel.com/sitemap/docs.xml
  pathPatterns: '[''backend/**'', ''backend/main.py'', ''backend/main.go'', ''backend/go.mod'', ''backend/pyproject.toml'', ''backend/requirements.txt'', ''frontend/**'', ''apps/*/backend/**'', ''apps/*/frontend/**'', ''services/*/vercel.json'', ''*/pyproject.toml'', ''*/go.mod'']'
  bashPatterns: '[''\\bvercel\\s+dev\\b.*-L'', ''\\bpip\\s+install\\b.*fastapi'', ''\\buv\\s+(sync|pip|run)\\b'', ''\\bgo\\s+(run|build|mod)\\b'', ''\\bpython\\s+-m\\s+uvicorn\\b'', ''\\buvicorn\\b'']'
  importPatterns: '[''fastapi'']'
  promptSignals: '{''phrases'': [''services api'', ''vercel services'', ''multi-service'', ''python backend'', ''go backend'', ''fastapi'', ''deploy backend'', ''backend and frontend'', ''multiple services''], ''allOf'': [[''backend'', ''frontend''], [''python'', ''vercel''], [''go'', ''vercel''], [''backend'', ''deploy''], [''service'', ''monorepo''], [''fastapi'', ''deploy'']], ''anyOf'': [''backend'', ''monorepo'', ''service'', ''python'', ''golang''], ''noneOf'': [''turborepo cache'', ''turbo.json'', ''aws lambda'', ''docker compose''], ''minScore'': 6}'
---

### 导出副本边界与技能别名

迁移、安装、修复和经验回写只作用于当前加载的目标宿主技能副本。原 Codex 技能/MCP、下载的源码和 `original-skills` 均为来源材料，不因执行本副本而写入；只有用户另行明确要求配置 Codex 产品本身时，才按该产品流程处理指定目标。脚本需要安装目录或状态目录时，显式提供目标路径；不得从 `CODEX_HOME` 隐式推断写入位置。

跨技能名称可能沿用源库别名。先查 [技能别名表](../../skill-aliases.json)，优先选择同来源、同插件的条目，再使用其 `id` 调用或读取对应入口；不得假定旧 `$skill`、`superpowers:skill` 名称在新宿主直接注册。不能确定目标时先核对，不替换真实产品命令或 Shell 环境变量。

## 跨宿主使用约定

本副本供支持 Agent Skills 的客户端使用。先检查当前宿主实际提供的工具、权限和已连接服务，再执行正文工作流。原文中的宿主工具标识是能力参考；只有实际发现该工具时才可调用，其他宿主应使用经核验的等价 MCP、CLI 或 API。没有等价能力的步骤必须报告不可用，不能虚构调用或完成状态。

技能资源以本技能目录为基准；输出写入当前项目中用户指定的位置。通过技能名称或自然语言触发，具体快捷命令由宿主决定。涉及真实产品、模型 API、协议字段和官方网址的名称保持原意。授权、审批、隐私和工具范围限制在迁移后仍然有效；不得为兼容而扩大权限。具体依赖与迁移说明见同目录 `PORTABILITY.md`。

# 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`:

```json
{
  "experimentalServices": {
    "web": {
      "entrypoint": "apps/web",
      "routePrefix": "/"
    },
    "api": {
      "entrypoint": "backend/main.py",
      "routePrefix": "/server"
    }
  }
}
```

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

### Configuration fields

| Field          | Required | Description                                                |
|----------------|----------|------------------------------------------------------------|
| `entrypoint`   | Yes      | Path to the service entrypoint file or directory.          |
| `routePrefix`  | Yes      | URL path prefix for routing (e.g. `/`, `/api`, `/svc/go`). |
| `framework`    | No       | Framework slug. Pins detection; auto-detected if unset.    |
| `memory`       | No       | Max available RAM in MB (128–10,240).                      |
| `maxDuration`  | No       | Execution timeout in seconds (1–900).                      |
| `includeFiles` | No       | Glob patterns for files to include in the deployment.      |
| `excludeFiles` | No       | Glob patterns for files to exclude from the deployment.    |

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:

| Variable                        | Example value                            | Availability | Use case                              |
|---------------------------------|------------------------------------------|--------------|---------------------------------------|
| `{SERVICENAME}_URL`             | `https://your-deploy.vercel.app/svc/api` | Server-side  | Server-to-server requests             |
| `NEXT_PUBLIC_{SERVICENAME}_URL` | `/svc/api`                               | Client-side  | Browser requests (relative, no CORS)  |

`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`.