marketplace

# 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", }, { key: "MY_SERVICE_TOKEN", value: credentials.token, target: ["production", "preview", "development"], type: "secret", }, ], }), }, ); return response.json(); } ``` ### Integration CLI Commands The `vercel integration` CLI supports these subcommands: ```bash # Discover integrations in the Marketplace catalog vercel integration discover vercel integration discover --category <category> # Get agent-friendly setup guide vercel integration guide <name> vercel integration guide <name> --framework <framework> # Add (install) an integration vercel integration add <name> # List installed integrations vercel integration list # alias: vercel integration ls # Check usage / billing balance vercel integration balance <name> # Open integration dashboard in browser (fallback when add redirects) vercel integration open <name> # Remove an integration vercel integration remove <name> ``` > **Building integrations?** Use `npx create-vercel-integration` to scaffold, then deploy your > integration app to Vercel normally with `vercel --prod`. Publish to the Marketplace via the > [Vercel Partner Dashboard](https://vercel.com/docs/integrations). ## Common Integration Categories | Category | Popular Integrations | Auto-Provisioned Env Vars | | --------------------- | --------------------------------------------- | --------------------------------------- | | Databases | Neon, Supabase, PlanetScale, MongoDB, Turso | `POSTGRES_URL`, `DATABASE_URL` | | Cache/KV | Upstash Redis | `KV_REST_API_URL`, `KV_REST_API_TOKEN` | | Auth | Clerk, Auth0, Descope | `CLERK_SECRET_KEY`, `AUTH0_SECRET` | | CMS | Sanity, Contentful, Storyblok, DatoCMS | `SANITY_PROJECT_ID`, `CONTENTFUL_TOKEN` | | Monitoring | Datadog, Sentry, Checkly, New Relic | `SENTRY_DSN`, `DD_API_KEY` | | Payments | Stripe | `STRIPE_SECRET_KEY` | | Feature Flags | LaunchDarkly, Statsig, Hypertune | `LAUNCHDARKLY_SDK_KEY` | | AI Agents & Services | CodeRabbit, Braintrust, Sourcery, Chatbase | varies by integration | | Video | Mux | `MUX_TOKEN_ID`, `MUX_TOKEN_SECRET` | | Messaging | Resend, Knock, Novu | `RESEND_API_KEY` | | Searching | Algolia, Meilisearch | `ALGOLIA_APP_ID`, `ALGOLIA_API_KEY` | | Commerce | Shopify, Swell, BigCommerce | `SHOPIFY_ACCESS_TOKEN` | ## Observability Integration Path Marketplace observability integrations (Datadog, Sentry, Axiom, Honeycomb, etc.) connect to Vercel's **Drains** system to receive telemetry. Understanding the data-type split is critical for correct setup. ### Data-Type Split | Data Type | Delivery Mechanism | Integration Setup | | ------------------ | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | **Logs** | Native drain (auto-configured by Marketplace install) | `vercel integration add <vendor>` auto-creates drain | | **Traces** | Native drain (OpenTelemetry-compatible) | Same — auto-configured on install | | **Speed Insights** | Custom drain endpoint only | Requires manual drain creation via REST API or Dashboard (`https://vercel.com/dashboard/{team}/~/settings/log-drains`) | | **Web Analytics** | Custom drain endpoint only | Requires manual drain creation via REST API or Dashboard (`https://vercel.com/dashboard/{team}/~/settings/log-drains`) | > **Key distinction:** When you install an observability vendor via the Marketplace, it auto-configures drains for **logs and traces** only. Speed Insights and Web Analytics data require a separate, manually configured drain pointing to a custom endpoint. See `⤳ skill: observability` for drain setup details. ### Agentic Flow: Observability Vendor Setup Follow this sequence when setting up an observability integration: #### 1. Pick Vendor ```bash # Discover observability integrations vercel integration discover --category monitoring # Get setup guide for chosen vendor vercel integration guide datadog ``` #### 2. Install Integration ```bash # Install — auto-provisions env vars and creates log/trace drains vercel integration add datadog ``` #### 3. Verify Drain Created ```bash # Confirm drain was auto-configured curl -s -H "Authorization: Bearer $VERCEL_TOKEN" \ "https://api.vercel.com/v1/drains?teamId=$TEAM_ID" | jq '.[] | {id, url, type, sources}' ``` Check the response for a drain pointing to the vendor's ingestion endpoint. If no drain appears, the integration may need manual drain setup — see `⤳ skill: observability` for REST API drain creation. #### 4. Validate Endpoint ```bash # Send a test payload to the drain curl -X POST -H "Authorization: Bearer $VERCEL_TOKEN" \ "https://api.vercel.com/v1/drains/<drain-id>/test?teamId=$TEAM_ID" ``` Confirm the vendor dashboard shows the test event arriving. #### 5. Smoke Log Check ```bash # Trigger a deployment and check logs flow through vercel logs <deployment-url> --follow --since 5m # Check integration balance to confirm data is flowing vercel integration balance datadog ``` Verify that logs appear both in Vercel's runtime logs and in the vendor's dashboard.