marketplace

What this skill does

# Vercel Marketplace

You are an expert in the Vercel Marketplace — the integration platform that connects third-party services to Vercel projects with unified billing, auto-provisioned environment variables, and one-click setup.

## Consuming Integrations

### Linked Project Preflight

Integration provisioning is project-scoped. Verify the repository is linked before running `integration add`.

```bash
# Check whether this directory is linked to a Vercel project
test -f .vercel/project.json && echo "Linked" || echo "Not linked"

# Link if needed
vercel link
```

If the project is not linked, do not continue with provisioning commands until linking completes.

### Discovering Integrations

```bash
# Search the Marketplace catalog from CLI
vercel integration discover

# Filter by category
vercel integration discover --category databases
vercel integration discover --category monitoring

# List integrations already installed on this project
vercel integration list
```

For browsing the full catalog interactively, use the [Vercel Marketplace](https://vercel.com/marketplace) dashboard.

### Getting Setup Guidance

```bash
# Get agent-friendly setup guide for a specific integration
vercel integration guide <name>

# Include framework-specific steps when available
vercel integration guide <name> --framework <fw>

# Examples
vercel integration guide neon
vercel integration guide datadog --framework nextjs
```

Use `--framework <fw>` as the default discovery flow when framework-specific setup matters. The guide returns structured setup steps including required environment variables, SDK packages, and code snippets — ideal for agentic workflows.

### Installing an Integration

```bash
# Install from CLI
vercel integration add <integration-name>

# Examples
vercel integration add neon          # Postgres database
vercel integration add upstash       # Redis / Kafka
vercel integration add clerk         # Authentication
vercel integration add sentry        # Error monitoring
vercel integration add sanity        # CMS
vercel integration add datadog       # Observability (auto-configures drain)
```

`vercel integration add` is the primary scripted/AI path. It installs to the currently linked project, auto-connects the integration, and auto-runs environment sync locally unless disabled.

If the CLI hands off to the dashboard for provider-specific completion, treat that as fallback:

```bash
vercel integration open <integration-name>
```

Complete the web step, then return to CLI verification (`vercel env ls` and local env sync check).

### Auto-Provisioned Environment Variables

When you install a Marketplace integration from a linked project, Vercel automatically provisions the required environment variables for that project.

**IMPORTANT: Provisioning delay after install.** After installing a database integration (especially Neon), the resource may take **1–3 minutes** to fully provision. During this window, connection attempts return HTTP 500 errors. Do NOT debug the connection string or code — just wait and retry. If local env sync was disabled or skipped, run `vercel env pull .env.local --yes` after a brief wait to get the finalized credentials.

```bash
# View environment variables added by integrations
vercel env ls

# Example: after installing Neon, these are auto-provisioned:
# POSTGRES_URL          — connection string
# POSTGRES_URL_NON_POOLING — direct connection
# POSTGRES_USER         — database user
# POSTGRES_PASSWORD     — database password
# POSTGRES_DATABASE     — database name
# POSTGRES_HOST         — database host
```

No manual `.env` file management is needed — the variables are injected into all environments (Development, Preview, Production) automatically.

### Using Provisioned Resources

```ts
// app/api/users/route.ts — using Neon auto-provisioned env vars
import { neon } from "@neondatabase/serverless";

// POSTGRES_URL is auto-injected by the Neon integration
const sql = neon(process.env.POSTGRES_URL!);

export async function GET() {
  const users = await sql`SELECT * FROM users LIMIT 10`;
  return Response.json(users);
}
```

```ts
// app/api/cache/route.ts — using Upstash auto-provisioned env vars
import { Redis } from "@upstash/redis";

// KV_REST_API_URL and KV_REST_API_TOKEN are auto-injected
const redis = Redis.fromEnv();

export async function GET() {
  const cached = await redis.get("featured-products");
  return Response.json(cached);
}
```

### Managing Integrations

```bash
# List installed integrations
vercel integration ls

# Check usage and billing for an integration
vercel integration balance <name>

# Remove an integration
vercel integration remove <integration-name>
```

## Unified Billing

Marketplace integrations use Vercel's unified billing system:

- **Single invoice**: All integration charges appear on your Vercel bill
- **Usage-based**: Pay for what you use, scaled per integration's pricing model
- **Team-level billing**: Charges roll up to the Vercel team account
- **No separate accounts**: No need to manage billing with each provider individually

```bash
# Check current usage balance for an integration
vercel integration balance datadog
vercel integration balance neon
```

## Building Integrations

### Integration Architecture

Vercel integrations consist of:

1. **Integration manifest** — declares capabilities, required scopes, and UI surfaces
2. **Webhook handlers** — respond to Vercel lifecycle events
3. **UI components** — optional dashboard panels rendered within Vercel
4. **Resource provisioning** — create and manage resources for users

### Scaffold an Integration

```bash
# Create a new integration project
npx create-vercel-integration my-integration

# Or start from the template
npx create-next-app my-integration --example vercel-integration
```

### Integration Manifest

```json
// vercel-integration.json
{
  "name": "my-integration",
  "slug": "my-integration",
  "description": "Provides X for Vercel projects",
  "logo": "public/logo.svg",
  "website": "https://my-service.com",
  "categories": ["databases"],
  "scopes": {
    "project": ["env-vars:read-write"],
    "team": ["integrations:read-write"]
  },
  "installationType": "marketplace",
  "resourceTypes": [
    {
      "name": "database",
      "displayName": "Database",
      "description": "A managed database instance"
    }
  ]
}
```

### Handling Lifecycle Webhooks

```ts
// app/api/webhook/route.ts
import { verifyVercelSignature } from "@vercel/integration-utils";

export async function POST(req: Request) {
  const body = await req.json();

  // Verify the webhook is from Vercel
  const isValid = await verifyVercelSignature(req, body);
  if (!isValid) {
    return Response.json({ error: "Invalid signature" }, { status: 401 });
  }

  switch (body.type) {
    case "integration.installed":
      // Provision resources for the new installation
      await provisionDatabase(body.payload);
      break;

    case "integration.uninstalled":
      // Clean up resources
      await deprovisionDatabase(body.payload);
      break;

    case "integration.configuration-updated":
      // Handle config changes
      await updateConfiguration(body.payload);
      break;
  }

  return Response.json({ received: true });
}
```

### Provisioning Environment Variables

```ts
// lib/provision.ts
async function provisionEnvVars(
  installationId: string,
  projectId: string,
  credentials: { url: string; token: string },
) {
  const response = await fetch(
    `https://api.vercel.com/v1/integrations/installations/${installationId}/env`,
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.VERCEL_INTEGRATION_TOKEN}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        projectId,
        envVars: [
          {
            key: "MY_SERVICE_URL",
            value: credentials.url,
            target: ["production", "preview", "development"],
            type: "encrypted",
          },