vercel-to-createos

What this skill does

# Vercel → CreateOS Migration

This skill migrates a project currently deployed on Vercel to CreateOS. It reads the existing Vercel configuration, translates it into a CreateOS project, provisions environments and environment variables, and triggers the first deployment — all through the CreateOS MCP server.

---

## When to use this skill

Activate this skill when any of the following is true:

- The user explicitly asks to migrate, move, or deploy from Vercel to CreateOS.
- The user expresses intent to leave Vercel (pricing, reliability, security, ownership concerns).
- The repository contains a `vercel.json`, `.vercel/` directory, or `@vercel/*` dependencies in `package.json`.
- The user asks for a "Vercel alternative" or references the April 2026 Vercel security incident.

Do NOT use this skill when:

- The user is deploying a fresh project with no prior Vercel deployment — use the standard `createos` skill instead.
- The project is a pure Next.js application with heavy dependencies on Vercel-specific features (Edge Middleware, Vercel KV, Vercel Blob, Vercel Postgres). Surface compatibility notes before proceeding.

---

## Prerequisites

Before running any migration steps, confirm the user has:

1. A CreateOS account — if not, direct them to `https://createos.nodeops.network` to sign in via Email, GitHub, Google, or Wallet.
2. CreateOS MCP connected OR a `CREATEOS_API_KEY` environment variable set.
3. Access to their current Vercel project's environment variables (they may need to export these from the Vercel dashboard).
4. GitHub repository access for the project (CreateOS deploys from GitHub for VCS projects).

If the user does not have their Vercel environment variables accessible, pause the migration and provide these instructions:

> Export your Vercel environment variables by running `vercel env pull .env.vercel.backup` in your project directory, or download them from Project Settings → Environment Variables in the Vercel dashboard. Keep this file local and do not commit it.

---

## Migration workflow

Follow these steps in order. Do not skip steps. Report progress to the user after each completed step.

### Step 1: Inventory the Vercel project

Read the following files from the repository if they exist:

- `vercel.json` — build, routing, function, and header configuration
- `package.json` — detect framework, build scripts, and Node.js version
- `next.config.js` / `next.config.mjs` / `next.config.ts` — Next.js specific configuration
- `.nvmrc` — Node version pin
- Any `.env*` files for reference (do NOT read secrets; only note which keys exist)

Produce a short summary for the user:

```
Detected project:
- Framework: [Next.js 14 / Vite / Remix / etc.]
- Node version: [20.x]
- Build command: [npm run build]
- Output directory: [.next]
- Environment variables needed: [count, with names — NOT values]
- Vercel-specific features in use: [list any edge middleware, KV, blob, etc.]
```

### Step 2: Flag incompatibilities before proceeding

Check for Vercel-specific features that do not have direct CreateOS equivalents. If any are present, STOP and confirm with the user how they want to handle each before continuing.

| Vercel feature | CreateOS handling |
|---|---|
| Edge Functions / Middleware | Runs as standard Node runtime on CreateOS — confirm latency impact is acceptable |
| Vercel KV | Migrate to CreateOS Valkey (Redis-compatible managed service) |
| Vercel Postgres | Migrate to CreateOS managed PostgreSQL |
| Vercel Blob | Use any S3-compatible storage; CreateOS does not provide blob storage natively |
| Image Optimization | Next.js image optimization works on CreateOS but uses the standard Node adapter |
| ISR / On-demand revalidation | Supported via standard Next.js caching; confirm revalidation paths work |
| Cron jobs | Use CreateOS cronjob support (see `CreateCronjob` MCP tool) |
| Preview deployments | Map to CreateOS preview environments (one per branch) |

### Step 3: Create the CreateOS project

Use the CreateOS MCP to create a new VCS-type project. Note: CreateOS uses a nested shape — `source` carries the GitHub linkage and `settings` carries build/runtime config. The deployment branch is set on the project's **environment** (Step 3b), not on the project itself.

1. Call `ListConnectedGithubAccounts` to verify GitHub is connected. The response includes the `installationId` you need for the next call. If no accounts are connected, call `InstallGithubApp` and pause for user action.
2. Call `ListGithubRepositories(installationId)` and confirm the target repo with the user. Capture the repo's `id` — that is the `vcsRepoId`.
3. Call `CheckProjectUniqueName({uniqueName})` to validate the proposed project name. `uniqueName` must match `^[a-zA-Z0-9-]+$`, 4–32 chars.
4. Call `CreateProject` with the nested `source`/`settings` shape. Two valid patterns — pick one:

   **Pattern A — Build AI (recommended default).** Use this when you cannot derive exact `installCommand` / `buildCommand` / `runCommand` from `vercel.json` + `package.json` with high confidence. CreateOS auto-detects from the repo:

   ```json
   CreateProject({
     "uniqueName": "<derived from project name>",
     "displayName": "<human-friendly name>",
     "type": "vcs",
     "source": {
       "vcsName": "github",
       "vcsInstallationId": "<from step 1>",
       "vcsRepoId": "<from step 2>"
     },
     "settings": {
       "useBuildAI": true,
       "runtime": "<see runtime mapping below — required>",
       "port": 80
     }
   })
   ```

   **Pattern B — Explicit commands.** Use this when `vercel.json` gives you concrete commands and a known framework. All command fields, when included, must be non-empty strings — **omit fields entirely rather than passing `""`** (empty strings cause a 400):

   ```json
   CreateProject({
     "uniqueName": "<derived from project name>",
     "displayName": "<human-friendly name>",
     "type": "vcs",
     "source": {
       "vcsName": "github",
       "vcsInstallationId": "<from step 1>",
       "vcsRepoId": "<from step 2>"
     },
     "settings": {
       "framework": "<see mapping table below — omit if no slug fits>",
       "runtime": "<see runtime mapping below>",
       "port": 3000,
       "directoryPath": ".",
       "installCommand": "<from package.json or vercel.json installCommand>",
       "buildCommand": "<from vercel.json buildCommand or package.json build script>",
       "runCommand": "<framework default, e.g. 'npm start' for Next.js>",
       "buildDir": "<from vercel.json outputDirectory or framework default, e.g. '.next'>"
     }
   })
   ```

   **Required-in-practice fields** (the API rejects without them, even though some are marked optional in the schema):
   - `port` — always include. Use `80` for static-shaped sites, `3000` for Node app defaults, or whatever the app actually listens on.
   - `runtime` — always include unless `framework` is set (and even then, include it for safety).
   - Either `useBuildAI: true` OR a complete command set (`installCommand` + `buildCommand` + `runCommand`). Mixing partial commands with `useBuildAI: false` causes a 400.

3b. Call `CreateProjectEnvironment(project_id, body)` to create the `production` environment. **All five body fields below are required by the API** — `description`, `settings`, and `resources` are not optional even though the docs may suggest otherwise. The `resources` triplet is all-or-nothing: include `cpu`, `memory`, and `replicas` together or omit `resources` entirely.

   ```json
   CreateProjectEnvironment(project_id, {
     "displayName": "Production",
     "uniqueName": "production",
     "description": "Production environment migrated from Vercel",
     "branch": "main",
     "isAutoPromoteEnabled": true,
     "settings": { "runEnvs": {} },
     "resources": { "cpu": 200, "memory": 500, "replicas": 1 }
   })
   ```

   Without this call, the project has no environment to deploy to. Resource limits: `cpu` 200–500 millicores, `memory` 500–1024 MB,