--- title: Overview description: Welcome to Vercel for Platforms documentation product: Vercel for Platforms type: overview summary: Choose between Multi-Tenant and Multi-Project approaches to build platforms that serve multiple customers on Vercel. related: - /docs/multi-tenant-platforms/concepts - /docs/multi-project-platforms/concepts - /docs/examples/multi-tenant-template - /docs/examples/oss-coding-agent --- # Overview Vercel for Platforms helps you build platforms that serve multiple customers. Choose from two distinct approaches depending on your use case. ## Choose your approach ### Multi-Tenant **Single codebase serving multiple tenants with their own domains.** Routing, data, and configuration are tenant-aware within one deployment. Use this when the content is unique, but the codebase is the same. **Examples**: Mintlify, Fern (documentation platforms), Hashnode, Dub (content platforms), Super (website builders) **Best for**: Documentation platforms, content platforms, website builders, SaaS dashboards where all customers share the same application structure. [Learn about Multi-Tenant →](/docs/multi-tenant-platforms/concepts) *** ### Multi-Project **Multiple unique codebases, each with its own Vercel project.** Each tenant has its own repository or deployment generated from a template. Use this when agents or users are deploying unique codebases. **Examples**: Spawn, Orchids (AI coding platforms), v0 (generative UI), Replit (code environments) **Best for**: AI coding platforms, per-customer isolated environments, user-generated applications, platforms where each tenant needs custom code. [Learn about Multi-Project →](/docs/multi-project-platforms/concepts) *** ## What you can build **Website builders**: Let customers create sites, connect domains, and publish instantly. **E-commerce platforms**: Spin up tenant stores from a template, connect headless APIs, and route custom domains. **AI coding platforms**: Create collaborative coding environments with real-time features, custom domain support, and integrated deployment options. **SaaS dashboards**: Serve tenant-aware dashboards from a single codebase with strict data boundaries. **Documentation and knowledge bases**: Multi-tenant docs with search and custom domains per workspace. **Developer platforms**: Provision apps from templates, enforce standards, and give teams routing and domain controls. ## How it works ### Multi-Tenant architecture With Multi-Tenant, you deploy a single Next.js application to Vercel. Your middleware identifies which tenant a request belongs to (by subdomain or custom domain), then loads that tenant's data and configuration. All tenants share the same codebase but see different content. You can offer: * Wildcard subdomains like `tenant1.yourapp.com`, `tenant2.yourapp.com` * Custom domains like `tenant1.com`, `tenant2.com` * Automatic SSL certificates for all domains ### Multi-Project architecture With Multi-Project, you programmatically create separate Vercel projects for each tenant using the Vercel SDK. Each project has its own codebase, deployments, and domains. This gives complete isolation between tenants. You can: * Create projects from templates * Deploy unique code per tenant * Manage deployments programmatically * Configure domains per project ## Getting started The fastest way to get started depends on your use case: **Multi-Tenant**: Clone the [Platforms Starter Kit](https://vercel.com/templates/next.js/platforms-starter-kit) and configure wildcard domains. **Multi-Project**: Use the [Vercel SDK](/docs/sdk) to programmatically create and deploy projects. ## Comparison table | Feature | Multi-Tenant | Multi-Project | | -------------------- | ------------------------------------- | ------------------------------------- | | **Architecture** | Single codebase, one deployment | Multiple codebases, multiple projects | | **Code sharing** | All tenants share code | Each tenant has unique code | | **Deployment** | Deploy once, affects all tenants | Deploy per tenant independently | | **Isolation** | Application-level (database, routing) | Complete (separate projects) | | **Custom domains** | ✓ Unlimited | ✓ Per project | | **Wildcard domains** | ✓ `*.yourapp.com` | ✓ Per project | | **Best for** | Same app, different content | Different code per tenant | | **Complexity** | Lower (one codebase) | Higher (manage multiple projects) | ## Which approach should I choose? ### Choose Multi-Tenant if: * All tenants use the same application structure * Content and branding differ, but functionality is the same * You want to deploy once and update all tenants simultaneously * You're building: documentation platforms, content platforms, website builders ### Choose Multi-Project if: * Each tenant needs custom code or unique functionality * Tenants deploy their own code (AI agents, user-generated apps) * Complete isolation is required between tenants * You're building: AI coding platforms, per-customer environments, template-based platforms ## Next steps Start letting your customers assign custom domains in minutes with our Ready-to-use components Quickly let your customers deploy code to an infinite amount of Vercel with our Actions Quickly let your customers deploy code to an infinite amount of Vercel Functions Start letting your customers assign custom domains in minutes --- title: Overview description: Welcome to Vercel for Platforms documentation product: Vercel for Platforms type: overview summary: High-level introduction to platforms and multi-tenant architecture on Vercel. related: - /docs/multi-tenant-platforms/concepts - /docs/multi-project-platforms/concepts --- # Overview ### Platforms vs Multi-tenant * **Platforms**: Apps that deploy many unique codebases. Each tenant often has its own repository or deployment generated from a template. Most common for usecases where Agents are deploying unique codebases to Vercels. [v0](https://v0.app) and [same.dev](https://same.dev) are examples of this. * **Multi-tenant**: A single codebase serving multiple tenants and domains. Routing, data, and configuration are tenant-aware within one deployment. Common for usecases where the content is unique, but the codebase is the same. [Mintlify](https://mintlify.com) and [Fern](https://buildwithfern.com) are examples of this. ### What you can build * **Website builders**: Let customers create sites, connect domains, and publish instantly. * **E-commerce platforms**: Spin up tenant stores from a template; connect headless APIs; route custom domains. * **SaaS dashboards**: Serve tenant-aware dashboards from a single codebase with strict data boundaries. * **Documentation and knowledge bases**: Multi-tenant docs with search and custom domains per workspace. * **Internal developer platforms**: Provision apps from templates; enforce standards; give teams routing and domain controls. * **Integration marketplaces**: Host integration UIs and webhooks per tenant with safe rollout and observability. Learn the core concepts Ready-to-use components Ready-to-use components --- title: Multi-Tenant Template description: Build SaaS applications that serve multiple domains from a single Next.js codebase product: Multi-Tenant type: guide summary: Build SaaS applications serving multiple domains from a single Next.js codebase using middleware and dynamic routing. prerequisites: - /docs/multi-tenant-platforms/concepts related: - /docs/multi-tenant-platforms/quickstart - /docs/multi-tenant-platforms/middleware-and-routing --- # Multi-Tenant Template Multi-tenant applications allow you to serve different customers with unique domains from a single codebase. This template demonstrates how to build a platform that dynamically routes requests based on the incoming domain, enabling you to create white-label solutions, SaaS platforms, and marketplace applications. Multi-Tenant Architecture Deploy the template directly: [vercel.com/templates/saas/platforms-starter-kit](https://vercel.com/templates/saas/platforms-starter-kit) ## What is Multi-Tenancy? Multi-tenancy is an architecture pattern where a single instance of an application serves multiple tenants (customers or organizations). Each tenant gets their own subdomain or custom domain while sharing the same underlying infrastructure and codebase. Common use cases include: * **White-label platforms** - Rebrandable applications for different clients * **SaaS marketplaces** - Multiple stores/sites under one platform * **Content management systems** - Publishing platforms with custom domains * **Agency portfolios** - Client websites managed from one codebase ## How It Works The multi-tenant template uses Next.js middleware to intercept incoming requests and route them based on the hostname: 1. **Request arrives** - A user visits `customer1.example.com` or `customer1.com` 2. **Middleware intercepts** - Extracts the hostname from the request headers 3. **Dynamic routing** - Rewrites the URL internally to include tenant context 4. **Tenant-specific content** - Renders customized content for that domain 5. **Response served** - User sees their branded experience ## Getting Started ### Step 1: Clone the Template Start by cloning the multi-tenant template: ```bash title="Terminal" git clone https://github.com/vercel/platforms cd platforms pnpm install ``` The template includes: * **Next.js App Router** for modern React architecture * **Middleware** for domain-based routing * **Tailwind CSS** for styling * **TypeScript** for type safety ### Step 2: Set Up Local Development For local development, you'll need to map custom domains to localhost. Add these entries to your hosts file: ```text title="/etc/hosts" 127.0.0.1 tenant1.localhost 127.0.0.1 tenant2.localhost 127.0.0.1 custom.localhost ``` Then start the development server: ```bash title="Terminal" pnpm dev ``` Visit different domains to see tenant-specific content: * [http://localhost:3002](http://localhost:3002) - Default home page * [http://tenant1.localhost:3002](http://tenant1.localhost:3002) - Tenant 1's site * [http://tenant2.localhost:3002](http://tenant2.localhost:3002) - Tenant 2's site ### Step 3: Configure Middleware The middleware is the heart of the multi-tenant system. It intercepts all requests and routes them appropriately: ```typescript title="middleware.ts" import { type NextRequest, NextResponse } from "next/server"; export function middleware(request: NextRequest) { const hostname = request.headers.get("host") || ""; // Add tenant context to the request and rewrite to /[domain] // if it starts with /domains, pass through if (request.nextUrl.pathname.startsWith("/domains")) { return NextResponse.next(); } const target = `${request.nextUrl.href}domains/${hostname}`; const response = NextResponse.rewrite(target); response.headers.set("x-tenant-domain", hostname); return response; } export const config = { matcher: ["/((?!api|_next/static|_next/image|favicon.ico).*)"], }; ``` ### Step 4: Create Tenant-Specific Pages Each tenant's content is served from a dynamic route that receives the domain as a parameter: ```tsx title="app/domains/[domain]/page.tsx" export default async function TenantPage({ params, }: { params: Promise<{ domain: string }>; }) { const { domain } = await params; // Fetch tenant-specific data const tenant = await getTenantByDomain(domain); // Render customized content return (

{tenant.name}

{/* Tenant-specific content */}
); } ``` ## Core Components ### Domain Resolution The system identifies tenants through their domain: ```typescript title="middleware.ts" function extractSubdomain(request: NextRequest): string | null { const url = request.url; const host = request.headers.get('host') || ''; const hostname = host.split(':')[0]; // Local development environment if (url.includes('localhost') || url.includes('127.0.0.1')) { // Try to extract subdomain from the full URL const fullUrlMatch = url.match(/http:\/\/([^.]+)\.localhost/); if (fullUrlMatch && fullUrlMatch[1]) { return fullUrlMatch[1]; } // Fallback to host header approach if (hostname.includes('.localhost')) { return hostname.split('.')[0]; } return null; } // Production environment const rootDomainFormatted = rootDomain.split(':')[0]; // Handle preview deployment URLs (tenant---branch-name.vercel.app) if (hostname.includes('---') && hostname.endsWith('.vercel.app')) { const parts = hostname.split('---'); return parts.length > 0 ? parts[0] : null; } // Regular subdomain detection const isSubdomain = hostname !== rootDomainFormatted && hostname !== `www.${rootDomainFormatted}` && hostname.endsWith(`.${rootDomainFormatted}`); return isSubdomain ? hostname.replace(`.${rootDomainFormatted}`, '') : null; } ``` ### Domain Configuration Configure domains in your Vercel dashboard: 1. **Wildcard subdomain** - `*.yourdomain.com` * Captures all subdomains automatically * Perfect for user-generated sites 2. **Custom domains** - Add individually * Each tenant's custom domain * Requires DNS configuration per domain ## Use Cases ### SaaS Platforms Build software that serves multiple organizations with isolated data and custom branding. ### E-commerce Marketplaces Create platforms where vendors get their own storefronts with unique domains. ### Content Publishing Enable creators to publish content on their custom domains while using your platform. ### Agency Solutions Manage multiple client websites from a single codebase with individual customizations. *** The multi-tenant template provides a solid foundation for building platforms that serve multiple customers from a single codebase. By leveraging Next.js middleware and dynamic routing, you can create scalable SaaS applications that offer custom domains, personalized experiences, and efficient resource utilization. Whether you're building a white-label solution, a marketplace platform, or a content management system, this architecture pattern enables you to grow from one to thousands of tenants without infrastructure complexity. --- title: OSS AI Vibe Coding Platform description: Build and deploy your own AI-powered coding platform with Vercel Sandboxes product: Multi-Project type: guide summary: Build an AI-powered coding platform with Vercel Sandboxes that generates, executes, and deploys applications. prerequisites: - /docs/multi-project-platforms/concepts related: - /docs/multi-project-platforms/quickstart - /docs/platform-elements/actions/deploy-files --- # OSS AI Vibe Coding Platform The AI Vibe Coding Platform represents a new paradigm in development environments where AI doesn't just assist with code completion, but actively generates entire applications based on natural language descriptions. This open-source platform enables developers to create their own AI-powered coding environments that can generate, execute, and deploy full applications in isolated, secure sandboxes. OSS AI Vibe Coding Platform Check out the live demo at [oss-vibe-coding-platform.vercel.app](https://oss-vibe-coding-platform.vercel.app/) ## What Makes It a "Vibe" Platform? The term "vibe" captures the essence of natural, conversational development. Instead of writing code line by line, developers describe the vibe of what they want to build, and AI translates that vision into working code. It's about capturing intent and transforming it into implementation through the power of modern language models. ## How It Works When you describe what you want to build, the platform: 1. **Creates an isolated sandbox** - A secure container for your application 2. **Generates application code** - AI writes all necessary files and configuration 3. **Executes the build** - Installs dependencies and runs your application 4. **Provides instant preview** - See your running application immediately 5. **Enables deployment** - Deploy to Vercel with a single click ## Getting Started ### Step 1: Clone and Set Up the Platform Start by [cloning the project](https://vercel.com/new/clone?demo-description=A+full-stack+coding+platform+built+with+Vercel%27s+AI+Cloud%2C+AI+SDK%2C+and+Next.js.\&demo-image=https%3A%2F%2Fassets.vercel.com%2Fimage%2Fupload%2Fv1754588832%2FOSSvibecodingplatform%2Fscreenshot.png\&demo-title=Vibe+Coding+Platform\&demo-url=https%3A%2F%2Fvercel.fyi%2Fvibes\&project-name=Vibe+Coding+Platform\&repository-name=vibe-coding-platform\&repository-url=https%3A%2F%2Fgithub.com%2Fvercel%2Fexamples%2Ftree%2Fmain%2Fapps%2Fvibe-coding-platform\&from=vibe-coding-platform-app) and installing dependencies. The platform is built with Next.js and uses modern tools like: * **Vercel AI SDK** for streaming AI responses * **Vercel Sandboxes** for secure code execution * **SWR** for data fetching and caching * **Tailwind CSS** for styling ### Step 2: Configure Your Environment Variables You'll only need one environment variable locally to run the project: ```text title=".env.local" AI_GATEWAY_API_KEY="" ``` This variable is used to authenticate with the AI Gateway and is sorted out for you when deployed to Vercel. ### Step 3: Run the Development Server Launch your local vibe coding platform locally with: ```bash title="Terminal" pnpm dev ``` Open [http://localhost:3000](http://localhost:3000) to see your platform running. You'll see: * **Chat Interface** - Where you describe what you want to build * **File Explorer** - Browse generated files in real-time * **Live Preview** - See your application as it's being built * **Logs Console** - Monitor build output and debugging information ### Step 4: Build Your First Application Now for the fun part - let's build something! Try these example prompts: **Simple React App:** ```text title="Prompt" "Create a todo list app with React that lets me add, complete, and delete tasks. Make it look modern with nice styling." ``` **API with Database:** ```text title="Prompt" "Build a REST API with Express that manages a book library. Include endpoints for CRUD operations and use SQLite for storage." ``` **Interactive Game:** ```text title="Prompt" "Make a simple memory card game where players match pairs of cards. Include a timer and score tracking." ``` The platform will: 1. Generate all necessary files 2. Set up the project structure 3. Install dependencies 4. Run the development server 5. Provide you with a live preview URL ## Core Components ### The Sandbox System Each user session gets its own isolated sandbox: ```typescript title="ai/tools/create-sandbox.ts" export const createSandbox = async ({ timeout, ports }) => { // ... const sandbox = await Sandbox.create({ timeout: timeout ?? 600000, ports, }); return ( `Sandbox created with ID: ${sandbox.sandboxId}.` + `\nYou can now upload files, run commands, and access services on the exposed ports.` ) } ``` ### File Generation The AI generates files directly into the sandbox: ```typescript title="ai/tools/generate-files.ts" export const generateFiles = tool({ description: 'Generate multiple files for the application', execute: async ({ files, sandboxId }) => { const sandbox = getSandbox(sandboxId); for (const file of files) { await sandbox.writeFile(file.path, file.content) } return `Generated ${files.length} files` } }) ``` ### Command Execution Run build commands and start servers in the sandbox: ```typescript title="ai/tools/run-command.ts" export const runCommand = tool({ description: 'Execute shell commands in the sandbox', execute: async ({ command, sandboxId }) => { const sandbox = getSandbox(sandboxId) const result = await sandbox.runCommand({ cmd: command }) return result.stdout; } }) ``` ## Key Features ### Real-time Streaming Watch as AI generates your application in real-time: ```tsx title="app/chat.tsx" export function Chat() { const { messages, append, isLoading } = useChat({ api: '/api/chat', onResponse: (response) => { // Stream updates to UI as code is generated } }) return ( {messages.map((message) => ( ))} ) } ``` ### Multi-Model Support The platform supports all models supported by the AI Gateway. ```typescript title="app/api/models/route.tsx" import { SUPPORTED_MODELS } from '@/ai/constants' import { getAvailableModels } from '@/ai/gateway' import { NextResponse } from 'next/server' export async function GET() { const allModels = await getAvailableModels() return NextResponse.json({ models: allModels.filter((model) => SUPPORTED_MODELS.includes(model.id)), }) } ``` *** The AI Vibe Coding Platform democratizes application development by allowing anyone to build software through natural conversation. Whether you're a seasoned developer looking to prototype quickly or someone new to coding wanting to bring ideas to life, this platform provides the tools to make it happen. By combining the power of modern AI models with secure sandbox environments, we're entering a new era where the barrier between idea and implementation is just a conversation. --- title: Platform Template description: The wall-to-wall reference for building an AI app builder on Vercel. Sandboxes, AI Gateway, deployments, Sign in With Vercel, and project transfers --- # Platform Template The Platform Template is the wall-to-wall reference for building an AI app builder on Vercel. It covers every layer of the stack: running AI agents in sandboxes, routing LLM calls through AI Gateway, previewing apps live, deploying to Vercel, and transferring project ownership to users via Vercel Apps and claim deployments. Check out the live demo at [platform-template.labs.vercel.dev](https://platform-template.labs.vercel.dev/) and the [GitHub source](https://github.com/vercel-labs/platform-template) ## What This Covers This template shows every Vercel platform primitive working together end-to-end: * **Vercel Sandbox** - agents write code and run dev servers allowing for app previews * **AI Gateway** - secure LLM access via OIDC, proxied from sandboxes that can't hold credentials * **Vercel Deployments** - deploy sandbox contents to production with the Vercel SDK * **Vercel Apps** - OAuth flow that installs an app in the users Vercel account during the claim flow allowing for continued updating * **Project Transfers** - allow users to get their websites deployed and then later take ownership of them ## Architecture Overview The template is a Next.js application with five major subsystems: ## How It Works ### 1. User sends a prompt The user types a prompt in the chat interface. The frontend calls `rpc.chat.send` - a streaming oRPC procedure that orchestrates the entire flow. ### 2. Sandbox is created and set up If this is a new session, a Vercel Sandbox is provisioned. The setup process installs bun, scaffolds the chosen template (Next.js, Vite, or TanStack Start), installs the agent CLI, and starts the dev server: ```typescript title="lib/sandbox/setup.ts" export async function* setupSandbox( sandbox: Sandbox, options: SetupOptions, ): AsyncGenerator { yield { stage: "installing-bun", message: "Installing bun..." }; await run(sandbox, { cmd: "sh", args: ["-c", "curl -fsSL https://bun.sh/install | bash && ..."], sudo: true, }, "bun install"); // Run template-specific setup (create-next-app, create-vite, etc.) for await (const progress of template.setup(sandbox)) { yield { stage: progress.stage, message: progress.message }; } // Install agent CLI and wait for dev server in parallel yield { stage: "installing-agent", message: "Installing agent..." }; await Promise.all([agentInstallPromise, devServerPromise]); yield { stage: "ready", message: "Sandbox ready" }; } ``` ### 3. Agent executes inside the sandbox Native agent coding CLIs like Codex and Claude Codex are run inside of the sandbox ```typescript title="lib/agents/claude-agent.ts" const env = { ANTHROPIC_BASE_URL: proxyConfig.baseUrl, // Points to our proxy ANTHROPIC_API_KEY: proxyConfig.sessionId, // Short-lived session ID }; const cmd = await sandbox.runCommand({ cmd: "sh", args: ["-c", `claude --print --verbose --output-format stream-json ...`], cwd: SANDBOX_BASE_PATH, env, detached: true, }); for await (const log of cmd.logs()) { // Parse NDJSON and convert to unified StreamChunk format } ``` ### 4. LLM calls go through AI Gateway The agent CLI's base URL is configured to the platform's proxy route, which acts as a provider endpoint. The proxy validates the session, attaches a Vercel OIDC token, and forwards the request to AI Gateway. If you wanted to implement things like tracking token spend per user this is where you're able to implement it: ```typescript title="app/api/ai/proxy/[[...path]]/route.ts" // 1. Extract session ID from x-api-key or Authorization header const data = await redis.get(`session:${sessionId}`); if (!session) return new Response("Invalid session", { status: 401 }); // 2. Get OIDC token from the Vercel deployment const gatewayToken = await getVercelOidcToken(); // 3. Forward to AI Gateway with only allowed headers headers.set("authorization", `Bearer ${gatewayToken}`); const response = await fetch(`${AI_GATEWAY_URL}${apiPath}`, { method: request.method, headers, body: await request.arrayBuffer(), }); ``` ### 5. User previews and deploys The sandbox dev server is exposed via an iframe. When the user clicks Deploy, the platform reads all files from the sandbox and creates a Vercel deployment: ```typescript title="lib/rpc/procedures/deploy.ts" const { client, teamId, ownership } = await getDeploymentClient(projectId); const files = await readFilesForDeploy(sandbox, filePaths); await vercel.deployments.createDeployment({ name, files, target: "production", project: projectId ?? undefined, }); ``` ### 6. User claims the deployment For signed-out users, the deployment lives on the partner team. The user can sign in with Vercel to claim it: 1. Platform creates a transfer request via the Vercel API, getting a `transferCode` 2. OAuth URL includes `transfer_code` - Vercel transfers the project during authorization 3. Post-OAuth callback stores per-project tokens (JWE-encrypted) in Redis 4. Future deploys use the stored tokens to deploy directly to the user's account ## AI Gateway Proxy Pattern Sandboxes cannot hold secrets. The proxy pattern solves this with short-lived capability tokens: **Security properties:** * Sandbox never sees the real OIDC token or any API key * Proxy sessions are stored in Redis with a 1-hour TTL * Only `accept`, `content-type`, and `anthropic-version` headers are forwarded * CORS checks reject cross-origin requests ## Deployment Authorization Model The template implements three tiers of deployment authorization: | Tier | When | Token Source | Deploys To | | ----------- | --------------- | --------------------------------- | -------------- | | **Partner** | Signed-out user | `VERCEL_PARTNER_TOKEN` env var | Partner team | | **User** | Signed-in user | OAuth session cookie | User's account | | **Project** | Post-claim | Stored per-project tokens (Redis) | User's account | Priority order: project tokens > user session > partner token. This means once a user claims a project, all subsequent deploys go to their account even if they're on a different browser session, because the platform stored the tokens during the claim flow. ## Sign in With Vercel + Claim Flow The claim flow combines OAuth authorization with project transfer in a single redirect: 1. User clicks "Claim" on a partner-owned deployment 2. Platform calls `projects.createProjectTransferRequest()` to get a `transferCode` 3. User is redirected to Vercel OAuth with `transfer_code` in the URL 4. User authorizes - Vercel transfers the project and returns an auth code 5. Callback exchanges the code for tokens, stores them (JWE-encrypted) in Redis 6. User is redirected back with `?sandboxId=xxx` to restore their session State recovery is seamless: the sandbox ID is encoded in the redirect URL, and `usePersistedChat()` restores messages, preview URL, and deployment state from Redis. ## Getting Started ### Step 1: Clone and Set Up ```bash title="Terminal" git clone https://github.com/vercel/platform-template cd platform-template pnpm install ``` The template is built with: * **Next.js 16** with App Router * **oRPC** for type-safe streaming RPC * **Vercel Sandbox** for secure code execution * **Vercel SDK** for deployments and project management * **Zustand + SWR** for state management * **Upstash Redis** for session persistence ### Step 2: Configure Environment Variables ```text title=".env.local" # Required for AI Gateway proxy PROXY_BASE_URL="http://localhost:3000/api/ai/proxy" # Required for deployments (partner-tier) VERCEL_PARTNER_TOKEN="" VERCEL_PARTNER_TEAM_ID="" # Required for Sign in With Vercel VERCEL_CLIENT_ID="" VERCEL_CLIENT_SECRET="" SESSION_SECRET="" # Required for session persistence UPSTASH_REDIS_REST_URL="" UPSTASH_REDIS_REST_TOKEN="" ``` ### Step 3: Run the Development Server ```bash title="Terminal" pnpm dev ``` Open [http://localhost:3000](http://localhost:3000) to see the platform. You'll see: * **Chat interface** - describe what you want to build * **Agent selector** - choose between Claude Code and Codex * **Template selector** - pick Next.js, Vite, or TanStack Start * **Live preview** - watch your app being built in real-time * **File explorer** - browse generated files * **Deploy button** - deploy to Vercel with one click ### Step 4: Build Something Try a prompt like: ```text title="Prompt" "Build a dashboard with a sidebar navigation, a main content area showing some charts, and a dark mode toggle. Use shadcn/ui components." ``` The platform will create a sandbox, set up the template, run the agent, and show you a live preview as the code is being written. ## Key Patterns ### Unified Stream Protocol Both Claude Code and Codex produce vastly different output formats. The harness layer normalizes them into a single `StreamChunk` protocol that the UI consumes. This means adding a new agent (e.g., Gemini CLI, OpenCode) requires no UI changes - just implement the `AgentProvider` interface and parse the CLI output. ### oRPC Generator Streaming The RPC layer uses `async function*` generators for streaming. The client gets typed chunks as they're yielded: ```typescript title="lib/rpc/procedures/chat.ts" export const sendMessage = os.input(schema).handler(async function* ({ input }) { yield { type: "sandbox-id", sandboxId: sandbox.sandboxId }; for await (const progress of setupSandbox(sandbox, options)) { yield events.sandboxStatus(sandbox.sandboxId, ...); } for await (const chunk of agent.execute({ prompt, sandboxContext, proxyConfig })) { yield chunk; } }); ``` ### Template System Each template implements a setup generator and provides framework-specific agent instructions: ```typescript title="lib/templates/types.ts" interface Template { id: TemplateId; name: string; devPort: number; instructions: string; // System prompt for the agent setup(sandbox: Sandbox): AsyncGenerator; } ``` Templates handle all scaffolding: `create-next-app`, `create-vite`, installing shadcn, configuring Tailwind, and starting the dev server. The agent receives framework-specific instructions so it generates idiomatic code. *** The Platform Template demonstrates what's possible when you combine Vercel's infrastructure primitives - sandboxes, AI Gateway, deployments, and project transfers - into a cohesive product experience. It's the reference architecture for building platforms where AI writes code, users preview it live, and deploy it to production with a single click. --- title: Domain connect description: How to implement domain connect product: Multi-Tenant type: guide summary: Implement domain connect for your multi-tenant platform. prerequisites: - /docs/multi-tenant-platforms/concepts related: - /docs/multi-tenant-platforms/configuring-domains - /docs/platform-elements/blocks/custom-domain --- # Domain connect # Domain connect Content coming soon... --- title: Next.js App Router description: Using Next.js App Router with Vercel Platforms product: Multi-Tenant type: guide summary: Use Next.js App Router with Vercel Platforms for multi-tenant applications. prerequisites: - /docs/multi-tenant-platforms/concepts related: - /docs/multi-tenant-platforms/middleware-and-routing - /docs/examples/multi-tenant-template --- # Next.js App Router # Next.js App Router Content coming soon... --- title: Concepts description: Understanding the core concepts of multi-project architecture helps you build scalable platforms with isolated tenant environments. product: Multi-Project type: conceptual summary: Core concepts of multi-project architecture including projects, deployments, domains, and use cases. related: - /docs/multi-project-platforms/quickstart - /docs/multi-project-platforms/reference --- # Concepts ## Projects ### What is a project A Vercel project represents a single application with its own Git repository, environment variables, and deployment history. In multi-project architecture, each tenant gets their own dedicated Vercel project. **Key characteristics**: * Unique project ID * Independent configuration * Separate deployment history * Isolated builds and functions ### Programmatic creation Create projects using the Vercel SDK: ```ts title="create-project.ts" import { Vercel } from "@vercel/sdk"; const vercel = new Vercel({ bearerToken: "", }); const { value: project } = await vercel.projects.createProject({ teamId: "team_1234", requestBody: { name: `tenant-${tenantId}`, framework: "nextjs", }, }); ``` ### Project templates Generate projects from templates to ensure consistency: ```ts title="create-project-from-template.ts" import { Vercel } from "@vercel/sdk"; const vercel = new Vercel({ bearerToken: "", }); const { value: project } = await vercel.projects.createProject({ teamId: "team_1234", requestBody: { name: `tenant-${tenantId}`, gitRepository: { type: "github", repo: "your-org/tenant-template", }, }, }); ``` ## Deployments ### Isolated deployments Each project has independent deployments: * Separate build processes * Independent function execution * Isolated environment variables * Individual deployment URLs ### Deployment lifecycle 1. **Create**: Deploy code to project 2. **Build**: Vercel builds the application 3. **Preview**: Test deployment before promoting 4. **Production**: Promote deployment to production 5. **Rollback**: Revert to previous deployment if needed ### Preview vs production **Preview deployments**: * Generated for every Git push * Unique URL per deployment * Test changes before production **Production deployments**: * Live on project domains * Promoted from preview or direct deploy * Serves end users ## Domains ### Per-project domains Each tenant project can have its own domains: ```ts title="add-domain.ts" import { Vercel } from "@vercel/sdk"; const vercel = new Vercel({ bearerToken: "", }); await vercel.projects.addProjectDomain({ idOrName: project.id, requestBody: { name: "tenant1.com", }, }); ``` ### Automatic URLs Every project gets automatic Vercel URLs: * Production: `project-name.vercel.app` * Preview: `project-name-git-branch.vercel.app` ### Custom domains per project Configure custom domains independently for each tenant: * Add domain via SDK * Tenant configures DNS * Verify ownership * SSL certificate issues automatically ## Architecture ### Multiple projects vs single project **Multi-Project**: * Each tenant = separate Vercel project * Complete isolation * Independent scaling * Higher management overhead **Multi-Tenant** (single project): * All tenants = one Vercel project * Shared infrastructure * Lower management overhead * Application-level isolation ## Use cases ### When to use Multi-Project vs Multi-Tenant **Use Multi-Project when**: * Tenants deploy their own code * Each tenant needs custom functionality * Complete isolation is required (security, compliance) * AI agents are generating and deploying code * Users create applications from templates **Use Multi-Tenant when**: * All tenants use the same application * Content differs but code is the same * You want to deploy once, update all tenants * Lower operational overhead preferred ### AI coding platforms Perfect for platforms where: * AI generates unique code per tenant * Each tenant's app is different * Users can deploy custom logic * Examples: Spawn, Orchids, v0 ### Template-based platforms Ideal for: * Creating projects from templates * Customizing per tenant * Maintaining consistency * Rapid tenant onboarding ### User-generated applications Well-suited for: * Users creating their own apps * Hosting user-generated content * Platform controls infrastructure * Users focus on their code ## Next steps * [Quickstart](/docs/multi-project-platforms/quickstart): Get started with multi-project platforms * [Reference](/docs/multi-project-platforms/reference): API reference and troubleshooting --- title: Quickstart description: Programmically host code for user or AI generated applications product: Multi-Project type: guide summary: Integrate user-generated sites with Vercel through project creation, deployment management, and domain aliasing. prerequisites: - /docs/multi-project-platforms/concepts related: - /docs/multi-project-platforms/reference - /docs/platform-elements/actions/deploy-files --- # Quickstart Let's explore integrating user generated sites with Vercel, providing a system for creating preview environments for your customers. The integration involves project creation, deployment management, domain aliasing (with custom suffixes), and SSO protection to secure all deployments. Vercel's API endpoints handle project creation, deployment configuration, domain assignment, and security settings, enabling a seamless experience for your users to access and share their generated sites. The integration would involve the following integrations: 1. Creating a Project for each chat 2. Deploying each version of the Artifact to the Project on demand when the user wants to "Publish" 3. Auto-aliasing the `*.CUSTOM_SUFFIX.com` domain that you want, or a user provided domain. 4. **Optional** Pretecting all the deployments through a central proxy 5. **Optional** Configuring the sites as subpaths on a single domain ## Project Creation * We recommend one project per user chat, the user can subsequently deploy multiple versions of the artifact to the same project (while still allowing all versions to stay active). The project becomes the organizational primitive for a single chat however * [Create a project for each chat](https://vercel.com/docs/rest-api/reference/endpoints/projects/create-a-new-project) * Configure the name of the project to help yourself come back to it and keep your Vercel account organized. * Most common options to customize the behaviour of each tenant project: * `framework`: The framework the application is using (ie. Next.js, React ect.) * `serverlessFunctionRegion`: The region any of your compute runs in. (It will default to iad1 if not) * `passwordProtection`: Configure a password customers can use to protect their generations ```jsx title="create-project.ts" async function createProject() { const result = await vercel.projects.createProject({ teamId: "team_1a2b3c4d5e6f7g8h9i0j1k2l", slug: "my-team-url-slug", requestBody: { name: "a-project-name", }, }); console.log(result); } ``` ## Deployment * [Every project has one "Production" domain that points to the most recent version (while keeping previous versions) and infinite "Preview" deployments](https://vercel.com/docs/deployments/environments), for most applications it makes most sense to always deploy the version as a new "Production" deployment under the same project * [Create a new Deployment with this endpoint](https://vercel.com/docs/rest-api/reference/endpoints/deployments/create-a-new-deployment) * Most common options to customize the behaviour of each tenant project: * `files`: The set of AI Generated files you want to deploy * `target`: preview or production. Both are the same underlying infrastructure but this is a semantic identifier you can add Leverage our pre-configured [file deploy action](/docs/platform-elements/actions/deploy-files): ```jsx title="deploy-files.ts" import { deployFiles } from "@/actions/deploy-files" import type { InlinedFile } from "@vercel/sdk/models/createdeploymentop" // Example: Deploy a simple HTML site const files: InlinedFile[] = [ { file: "index.html", data: "

Hello from my platform!

" }, { file: "package.json", data: JSON.stringify({ name: "my-deployment", version: "1.0.0" }) } ] await deployFiles(files, { domain: "customer-site.com", deploymentName: "customer-deployment-1", projectId: "existing-project-id", // Optional: use existing project config: { framework: "nextjs", buildCommand: "npm run build", outputDirectory: ".next" } }) ``` ## Domain Aliasing * If you want deployments to have a custom suffix: `*.CUSTOM_SUFFIX.com`, you can: * Setup a [wildcard domain for your domain](https://vercel.com/docs/multi-tenant/domain-management#using-wildcard-domains) * Use either of these to auto-assign the `*.CUSTOM_SUFFIX.com` domain: * [Assign a single domain that maps to the most recent production domain of the Project](https://vercel.com/docs/rest-api/reference/endpoints/projects/add-a-domain-to-a-project) * [Alias a specific URL to only that one deployment in a project](https://vercel.com/docs/rest-api/reference/endpoints/aliases/assign-an-alias) * [Alternatively allow customers to bring in a domain they own elsewhere to assign to their sites](/docs/multi-tenant-platforms/configuring-domains) ## Protecting all deployments behind SSO or authentication, if you want central authentication (optional) 1. Create a Proxy site hosted in Vercel that all traffic will flow through that: 1. Checks x.ai SSO and asks the user to log in if not 2. Proxies back to the actual deployed application once authenticated 3. Includes a [Deployment Bypass](https://vercel.com/docs/deployment-protection/methods-to-bypass-deployment-protection/protection-bypass-automation) header, that will lock down direct access to the Vercel applications 2. Alias all domains to the proxy site instead so all traffic goes to it first 3. Ensure `ssoProtection` is configured to `all` when creating the project to lock down access 1. Configuring a bypass option on the deployment so the Proxy can still access it: [https://vercel.com/docs/rest-api/reference/endpoints/projects/update-protection-bypass-for-automation](https://vercel.com/docs/rest-api/reference/endpoints/projects/update-protection-bypass-for-automation) ## Configuring the sites to be subpaths instead of custom domains (optional) * To ensure all these deployments can only be accessed as subpaths `domain.com/customer_a` you would first configure the same Proxy setup as in 4. (with or without authentication, depending on your product requirements.) * This proxy would be [assigned the domain you want to share in it's Vercel project](https://vercel.com/docs/domains/working-with-domains/add-a-domain) * You can then create a [routing middleware](https://vercel.com/docs/routing-middleware) in the Proxy, to be able to rewrite the paths to the domains they are hosted in Vercel. * It can dynamically pull the data from your backend or you can make it faster by caching it in [Edge Config](https://vercel.com/docs/edge-config) --- title: Reference description: Common questions related to Multi Projet Platforms product: Multi-Project type: reference summary: Projects and deployments API reference, error codes, troubleshooting, and FAQ for multi-project platforms. prerequisites: - /docs/multi-project-platforms/concepts related: - /docs/multi-project-platforms/quickstart - /docs/platform-elements/actions/deploy-files --- # Reference ## Custom blocks Start with our Custom [Blocks](/docs/platform-elements/blocks/deploy-popover) and [Actions](/docs/platform-elements/actions/deploy-files) that speed up your usage of the Vercel API. ## Projects & Deployments API reference ### Create project Create a new Vercel project using the [create project API](https://vercel.com/docs/rest-api/reference/endpoints/projects/create-a-new-project). **SDK**: ```ts title="create-project.ts" import { Vercel } from "@vercel/sdk"; const vercel = new Vercel({ bearerToken: "", }); async function run() { const result = await vercel.projects.createProject({ teamId: "team_1a2b3c4d5e6f7g8h9i0j1k2l", slug: "my-team-url-slug", requestBody: { name: "a-project-name", }, }); console.log(result); } run(); ``` ### Deploy to project Create a deployment for a project using the [create deployment API](https://vercel.com/docs/rest-api/reference/endpoints/deployments/create-a-new-deployment). **SDK**: ```ts title="deploy-files.ts" import { Vercel } from "@vercel/sdk"; const vercel = new Vercel({ bearerToken: "", }); async function run() { const result = await vercel.deployments.createDeployment({ teamId: "team_1a2b3c4d5e6f7g8h9i0j1k2l", slug: "my-team-url-slug", requestBody: { deploymentId: "dpl_2qn7PZrx89yxY34vEZPD31Y9XVj6", files: [ { data: "", file: "folder/file.js", }, ], gitMetadata: { remoteUrl: "https://github.com/vercel/next.js", commitAuthorName: "kyliau", commitAuthorEmail: "kyliau@example.com", commitMessage: "add method to measure Interaction to Next Paint (INP) (#36490)", commitRef: "main", commitSha: "dc36199b2234c6586ebe05ec94078a895c707e29", dirty: true, ci: true, ciType: "github-actions", ciGitProviderUsername: "rauchg", ciGitRepoVisibility: "private", }, gitSource: { projectId: 987654321, ref: "main", sha: "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0", type: "gitlab", }, meta: { foo: "bar", }, name: "my-instant-deployment", project: "my-deployment-project", projectSettings: { buildCommand: "next build", installCommand: "pnpm install", }, target: "production", }, }); console.log(result); } run(); ``` ### List deployments Get deployments for a project using the [list deployments API](https://vercel.com/docs/rest-api/reference/endpoints/deployments/list-deployments). **SDK**: ```ts title="list-deployments.ts" import { Vercel } from "@vercel/sdk"; const vercel = new Vercel({ bearerToken: "", }); async function run() { const result = await vercel.deployments.getDeployments({ app: "docs", from: 1612948664566, limit: 10, projectId: "QmXGTs7mvAMMC7WW5ebrM33qKG32QK3h4vmQMjmY", projectIds: ["prj_123", "prj_456"], target: "production", to: 1612948664566, users: "kr1PsOIzqEL5Xg6M4VZcZosf,K4amb7K9dAt5R2vBJWF32bmY", since: 1540095775941, until: 1540095775951, state: "BUILDING,READY", teamId: "team_1a2b3c4d5e6f7g8h9i0j1k2l", slug: "my-team-url-slug", }); console.log(result); } run(); ``` ### Delete project Remove a project and all its deployments using the delete project API. **SDK**: ```ts title="delete-project.ts" import { Vercel } from "@vercel/sdk"; const vercel = new Vercel({ bearerToken: "", }); async function run() { const result = await vercel.deployments.deleteDeployment({ id: "dpl_5WJWYSyB7BpgTj3EuwF37WMRBXBtPQ2iTMJHJBJyRfd", url: "https://files-orcin-xi.vercel.app/", teamId: "team_1a2b3c4d5e6f7g8h9i0j1k2l", slug: "my-team-url-slug", }); console.log(result); } run(); ``` ### Error codes | Code | Description | Solution | | ------------------------ | -------------------------- | ------------------------------------------ | | `project_limit_exceeded` | Team project limit reached | Upgrade plan or clean up unused projects | | `invalid_name` | Project name is invalid | Use alphanumeric characters and hyphens | | `forbidden` | Insufficient permissions | Check API token has project creation scope | | `rate_limit_exceeded` | Too many requests | Implement exponential backoff | | `build_failed` | Deployment build failed | Check build logs for errors | ## Troubleshooting ### Deployment Failures **Problem**: Deployments failing with build errors. **Solution**: * Check build logs via SDK * Verify `package.json` dependencies * Ensure build command is correct * Check for environment variable issues * Verify Node.js version compatibility ### Project Creation Limits **Problem**: Cannot create more projects. **Solution**: * Check current project count against plan limit * Delete unused projects * Upgrade to higher tier plan * Contact sales for enterprise limits ### Domain Conflicts **Problem**: Domain already in use error. **Solution**: * Domain must be unique across Vercel * Remove domain from other project first * Use subdomain instead (`tenant1.yourdomain.com`) * Verify domain ownership if domain exists elsewhere ### Build Errors **Problem**: Builds timing out or failing. **Solution**: * Optimize build process * Check build time limits for your plan * Reduce dependencies * Use build caching * Split large builds into stages ### Resource Quota Issues **Problem**: Hitting function size or execution limits. **Solution**: * Review function sizes * Optimize bundle size * Check execution time limits * Consider upgrading plan * Split large functions ## FAQ ### What's the difference between Multi-Project and Multi-Tenant? **Multi-Project**: Multiple Vercel projects, each with unique code and isolated deployments. Complete separation between tenants. **Multi-Tenant**: Single project serving multiple tenants with different content. All tenants share the same codebase. Use Multi-Project when tenants need custom code. Use Multi-Tenant when tenants share functionality but have different content. ### How many projects can I create? Project limits depend on your plan: * **Hobby**: Limited projects per account * **Pro**: Higher limits * **Enterprise**: Custom limits based on needs Contact [sales](/contact/sales) for specific limits. ### How is pricing calculated per tenant? Each project is billed based on: * **Build minutes**: Time spent building deployments * **Function invocations**: Number of function calls * **Bandwidth**: Data transferred * **Edge requests**: CDN requests All usage follows standard Vercel pricing. See [pricing documentation](/pricing). ### Are there isolation guarantees? Yes, Multi-Project provides complete isolation: * **Build isolation**: Separate build environments * **Runtime isolation**: Independent function execution * **Data isolation**: No shared state between projects * **Configuration isolation**: Separate environment variables ### How does data retention work? When you delete a project: * Deployments are deleted immediately * Build logs are retained for 30 days * Environment variables are deleted * Domains are released Export any data you need before deleting projects. ### How can I monitor multiple projects? Monitor projects using: * **Vercel Dashboard**: View all projects per team * **SDK**: Query project and deployment status * **Webhooks**: Get real-time deployment notifications * **Analytics**: View usage and performance metrics ### Can I migrate from Multi-Tenant to Multi-Project? Yes, but it requires architectural changes: 1. Export tenant data from shared database 2. Create separate projects per tenant 3. Deploy tenant code to each project 4. Configure domains for each project 5. Update tenant routing in your application This is a significant migration. Consider carefully before switching. ### What are the rate limits? API rate limits for project operations: * **Create project**: 100 requests per hour * **Create deployment**: 1000 requests per hour * **Delete project**: 100 requests per hour * **Other operations**: Standard API limits See [API rate limits documentation](/docs/rest-api#rate-limits). ### How do I handle CI/CD per tenant? Each project can have its own CI/CD: * Connect to tenant's Git repository * Configure build settings per project * Set up deployment webhooks * Use GitHub Actions or other CI tools * Test and deploy independently ### Can tenants manage their own projects? No, programmatically created projects are managed by your team. Tenants cannot access the Vercel dashboard for their projects unless you add them as team members (not recommended for platforms). Instead, build your own interface for tenants to: * Trigger deployments * View deployment status * Configure environment variables * Monitor usage ## Next steps * [Concepts](/docs/multi-project-platforms/concepts): Understand multi-project architecture * [Quickstart](/docs/multi-project-platforms/quickstart): Get started with multi-project platforms * [Vercel SDK](https://vercel.com/docs/sdk): Complete SDK documentation --- title: Concepts description: Understanding the core concepts of multi-tenant architecture helps you build scalable platforms on Vercel. product: Multi-Tenant type: conceptual summary: Core concepts of multi-tenant architecture including tenants, domains, routing, and tenant context. related: - /docs/multi-tenant-platforms/quickstart - /docs/multi-tenant-platforms/configuring-domains - /docs/multi-tenant-platforms/middleware-and-routing --- # Concepts ## Tenants ### What is a tenant A tenant represents a customer, workspace, or organization within your multi-tenant application. Each tenant has its own data, configuration, and branding, but all tenants share the same codebase and deployment. **Examples**: * Blog platform: Each writer with their own blog is a tenant * Documentation platform: Each company with its own docs site is a tenant * E-commerce platform: Each store owner is a tenant ### Tenant identification strategies You can identify tenants using three approaches: **Subdomain-based**: Extract the tenant from the subdomain (`tenant1.yourapp.com`) ```ts title="middleware.ts" const hostname = request.headers.get("host"); const subdomain = hostname.split(".")[0]; // "tenant1" ``` **Custom domain-based**: Map custom domains to tenants (`tenant1.com` → Tenant 1) ```ts title="middleware.ts" // Map custom domain to tenant in database const tenant = await db.tenant.findFirst({ where: { customDomain: hostname }, }); ``` **Path-based**: Extract tenant from URL path (`/tenant1/dashboard`) ```ts title="middleware.ts" const pathname = request.nextUrl.pathname; const tenantSlug = pathname.split("/")[1]; // "tenant1" ``` ### Tenant data isolation Multi-tenant applications must isolate data between tenants: **Database-level**: Use tenant ID in all queries ```ts title="database.ts" const posts = await db.post.findMany({ where: { tenantId: tenant.id }, }); ``` **Application-level**: Middleware ensures requests can only access their tenant's data **Edge Config**: Store tenant configuration for fast lookups at the edge ## Domains ### Wildcard domains Wildcard domains let you automatically serve all subdomains from a single Vercel project: * Add `*.yourapp.com` to your project * Point your domain to Vercel's nameservers * Any subdomain (`tenant1.yourapp.com`, `tenant2.yourapp.com`) automatically routes to your app * Vercel issues SSL certificates for each subdomain on the fly **Requirements**: Must use Vercel's nameservers (`ns1.vercel-dns.com`, `ns2.vercel-dns.com`) ### Custom domains Custom domains let tenants bring their own domain: * Add `tenant1.com` to your Vercel project via SDK * Tenant configures DNS (CNAME or nameservers) * Verify domain ownership (TXT record) * Vercel issues SSL certificate automatically ### SSL certificate issuance Vercel automatically issues SSL certificates for all domains using Let's Encrypt: * Wildcard domains: Single wildcard certificate covers all subdomains * Custom domains: Individual certificate per domain * Automatic renewal before expiration * No configuration required ### Domain verification For domains already in use on Vercel, ownership verification is required: 1. Add domain to your project 2. Vercel generates a unique TXT record 3. Tenant adds TXT record to their DNS 4. Verify ownership via SDK or dashboard 5. Certificate issues once verified ## Routing ### How middleware resolves tenants Next.js middleware runs on every request before your pages render: ```ts title="middleware.ts" export async function middleware(request: NextRequest) { const hostname = request.headers.get("host"); // Get tenant from subdomain or custom domain const tenant = await resolveTenant(hostname); // Add tenant to request headers const response = NextResponse.next(); response.headers.set("x-tenant-id", tenant.id); return response; } ``` ### Request handling flow 1. User visits `tenant1.yourapp.com` 2. Request hits Vercel's edge network 3. Middleware extracts subdomain (`tenant1`) 4. Middleware looks up tenant in database or Edge Config 5. Middleware adds tenant context to request headers 6. Page component reads tenant from headers 7. Page renders with tenant-specific data ### Performance considerations **Edge Config**: Store tenant configuration at the edge for sub-10ms lookups ```ts title="edge-config.ts" import { get } from "@vercel/edge-config"; const tenant = await get(`tenant_${hostname}`); ``` **Caching**: Cache tenant lookups in middleware to reduce database queries **Connection pooling**: Use connection pooling for database queries to handle multiple tenants efficiently ## Architecture ### Single deployment serving multiple domains Multi-tenant architecture means: * One Next.js codebase * One Vercel deployment * Multiple domains (subdomains + custom domains) * Shared infrastructure and resources * Tenant-aware routing and data access ### Tenant context Pass tenant information through your application: **In middleware**: Set headers ```ts title="middleware.ts" response.headers.set("x-tenant-id", tenant.id); ``` **In server components**: Read headers ```ts title="server-component.ts" import { headers } from "next/headers"; const tenantId = headers().get("x-tenant-id"); ``` **In API routes**: Access request headers ```ts title="api-route.ts" const tenantId = request.headers.get("x-tenant-id"); ``` --- title: Configuring Custom Domains description: How to make deployments & projects use a custom domain product: Multi-Tenant type: guide summary: Configure wildcard domains, custom domains, domain verification, and redirects for multi-tenant deployments. prerequisites: - /docs/multi-tenant-platforms/concepts related: - /docs/multi-tenant-platforms/quickstart - /docs/platform-elements/blocks/custom-domain - /docs/platform-elements/blocks/dns-table --- # Configuring Custom Domains ## Using wildcard domains If you plan on offering subdomains like `*.acme.com`, add a wildcard domain to your Vercel project. This requires using [Vercel's nameservers](https://vercel.com/docs/projects/domains/working-with-nameservers) so that Vercel can manage the DNS challenges necessary for generating wildcard SSL certificates. 1. Point your domain to Vercel's nameservers (`ns1.vercel-dns.com` and `ns2.vercel-dns.com`). 2. In your Vercel project settings, add the apex domain (e.g., `acme.com`). 3. Add a wildcard domain: `.acme.com`. Now, any `tenant.acme.com` you create—whether it's `tenant1.acme.com` or `docs.tenant1.acme.com`—automatically resolves to your Vercel deployment. Vercel issues individual certificates for each subdomain on the fly. ## Offering custom domains You can also give tenants the option to bring their own domain. In that case, you'll want your code to: 1. Provision and assign the tenant's domain to your Vercel project. 2. Verify the domain (to ensure the tenant truly owns it). 3. Automatically generate an SSL certificate. ## Adding a domain programmatically You can add a new domain through the [Vercel SDK](https://vercel.com/docs/sdk). For example: ```ts title="add-domain.ts" import { VercelCore as Vercel } from "@vercel/sdk/core.js"; import { projectsAddProjectDomain } from "@vercel/sdk/funcs/projectsAddProjectDomain.js"; const vercel = new Vercel({ bearerToken: process.env.VERCEL_TOKEN, }); // The 'idOrName' is your project name in Vercel, for example: 'multi-tenant-app' await projectsAddProjectDomain(vercel, { idOrName: "my-multi-tenant-app", teamId: "team_1234", requestBody: { // The tenant's custom domain name: "customacmesite.com", }, }); ``` Once the domain is added, Vercel attempts to issue an SSL certificate automatically. ## Verifying domain ownership If the domain is already in use on Vercel, the user needs to set a TXT record to prove ownership of it. You can check the verification status and trigger manual verification: ```ts title="verify-domain.ts" import { VercelCore as Vercel } from "@vercel/sdk/core.js"; import { projectsGetProjectDomain } from "@vercel/sdk/funcs/projectsGetProjectDomain.js"; import { projectsVerifyProjectDomain } from "@vercel/sdk/funcs/projectsVerifyProjectDomain.js"; const vercel = new Vercel({ bearerToken: process.env.VERCEL_TOKEN, }); const domain = "customacmesite.com"; const [domainResponse, verifyResponse] = await Promise.all([ projectsGetProjectDomain(vercel, { idOrName: "my-multi-tenant-app", teamId: "team_1234", domain, }), projectsVerifyProjectDomain(vercel, { idOrName: "my-multi-tenant-app", teamId: "team_1234", domain, }), ]); const { value: result } = verifyResponse; if (!result?.verified) { console.log(`Domain verification required for ${domain}.`); // You can prompt the tenant to add a TXT record or switch nameservers. } ``` ## Handling redirects and apex domains ### Redirecting between apex and "www" Some tenants might want `www.customacmesite.com` to redirect automatically to their apex domain `customacmesite.com`, or the other way around. 1. Add both `customacmesite.com` and `www.customacmesite.com` to your Vercel project. 2. Configure a redirect for `www.customacmesite.com` to the apex domain by setting `redirect: customacmesite.com` through the API or your Vercel dashboard. This ensures a consistent user experience and prevents issues with duplicate content. ### Avoiding duplicate content across subdomains If you offer both `tenant.acme.com` and `customacmesite.com` for the same tenant, you may want to redirect the subdomain to the custom domain (or vice versa) to avoid search engine duplicate content. Alternatively, set a canonical URL in your HTML `` to indicate which domain is the "official" one. ## Deleting or removing domains If a tenant cancels or no longer needs their custom domain, you can remove it from your Vercel account using the SDK: ```ts title="remove-domain.ts" import { VercelCore as Vercel } from "@vercel/sdk/core.js"; import { projectsRemoveProjectDomain } from "@vercel/sdk/funcs/projectsRemoveProjectDomain.js"; import { domainsDeleteDomain } from "@vercel/sdk/funcs/domainsDeleteDomain.js"; const vercel = new Vercel({ bearerToken: process.env.VERCEL_TOKEN, }); await Promise.all([ projectsRemoveProjectDomain(vercel, { idOrName: "my-multi-tenant-app", teamId: "team_1234", domain: "customacmesite.com", }), domainsDeleteDomain(vercel, { domain: "customacmesite.com", }), ]); ``` The first call disassociates the domain from your project, and the second removes it from your account entirely. ## Troubleshooting common issues Here are a few common issues you might run into and how to solve them: ### DNS propagation delays After pointing your nameservers to Vercel or adding CNAME records, changes can take 24–48 hours to propagate. Use [WhatsMyDNS](https://www.whatsmydns.net/) to confirm updates worldwide. ### Forgetting to verify domain ownership If you add a tenant's domain but never verify it (e.g., by adding a `TXT` record or using Vercel nameservers), SSL certificates won't be issued. Always check the domain's status in your Vercel project or with the SDK. ### Wildcard domain requires Vercel nameservers If you try to add `.acme.com` without pointing to `ns1.vercel-dns.com` and `ns2.vercel-dns.com`, wildcard SSL won't work. Make sure the apex domain's nameservers are correctly set. ### Exceeding subdomain length for preview URLs Each DNS label has a [63-character limit](https://vercel.com/guides/why-is-my-vercel-deployment-url-being-shortened#rfc-1035). If you have a very long branch name plus a tenant subdomain, the fully generated preview URL might fail to resolve. Keep branch names concise. ### Duplicate content SEO issues If the same site is served from both subdomain and custom domain, consider using [canonical](https://nextjs.org/docs/app/api-reference/functions/generate-metadata#alternates) tags or auto-redirecting to the primary domain. ### Misspelled domain A small typo can block domain verification or routing, so double-check your domain spelling. Last updated on June 12, 2025 --- title: Configuring Custom Subpaths description: How to support custom subpaths for customers using a custom domain product: Multi-Tenant type: guide summary: Host platform content on custom subpaths of customer domains while maintaining a single Next.js application. prerequisites: - /docs/multi-tenant-platforms/concepts - /docs/multi-tenant-platforms/middleware-and-routing related: - /docs/multi-tenant-platforms/configuring-domains --- # Configuring Custom Subpaths Custom subpaths let customers host your platform content on any path of their existing domain, like `company.com/docs` or `startup.com/help`, while you maintain a single Next.js application and they host the rest of their site separately. ## Single app, multiple subpaths Use a catch-all route to handle all customer requests in one application: ```tsx title="app/sites/[...slug]/page.tsx" export default async function CustomerSite({ params, }: { params: { slug: string[] }; }) { const [customerSlug, ...contentPath] = params.slug; // Load customer config const customer = await getCustomer(customerSlug); if (!customer) return notFound(); // Load customer-specific content const content = await getContent(customer.id, contentPath.join("/")); return (

{customer.name}

{content}
); } ``` This handles requests like: * `yourapp.com/sites/acme/getting-started` * `yourapp.com/sites/startup/api-reference` ## Redirect subdomains to paths Redirect customer subdomains to path-based routes: ```ts title="proxy.ts" import { NextRequest, NextResponse } from "next/server"; export async function proxy(request: NextRequest) { const hostname = request.headers.get("host") || ""; const { pathname } = request.nextUrl; // Check if it's a customer subdomain const subdomain = hostname.split(".")[0]; if ( subdomain !== "www" && subdomain !== "app" && hostname.includes("yourapp.com") ) { // Rewrite vercel.yourapp.com/guide -> yourapp.com/sites/vercel/guide const rewriteUrl = new URL(`/sites/${subdomain}${pathname}`, request.url); rewriteUrl.host = "yourapp.com"; return NextResponse.rewrite(rewriteUrl); } return NextResponse.next(); } ``` ## Set unique asset prefix Configure Next.js to use a unique asset prefix to avoid conflicts: ```js title="next.config.js" /** @type {import('next').NextConfig} */ const nextConfig = { assetPrefix: "/your-platform-assets", async rewrites() { return [ { source: "/your-platform-assets/_next/:path*", destination: "/_next/:path*", }, ]; }, }; module.exports = nextConfig; ``` This ensures your CSS, JS, and images load from `/your-platform-assets/_next/...` instead of `/_next/...`. ## Customer domain setup Customers map two paths on their domain to your platform: **Content mapping:** ``` /docs/:path* -> https://yourapp.com/sites/customer-slug/:path* ``` **Asset mapping:** ``` /your-platform-assets/:path* -> https://yourapp.com/your-platform-assets/:path* ``` Example with Vercel [Proxy](https://nextjs.org/docs/app/getting-started/proxy): ```ts title="proxy.ts" import { NextRequest, NextResponse } from "next/server"; export async function proxy(request: NextRequest) { const { pathname } = request.nextUrl; // Route content requests if (pathname.startsWith("/docs/")) { const targetPath = pathname.replace("/docs/", "/sites/customer-slug/"); const targetUrl = `https://yourapp.com${targetPath}`; return NextResponse.rewrite(new URL(targetUrl)); } // Route asset requests if (pathname.startsWith("/your-platform-assets/")) { const targetUrl = `https://yourapp.com${pathname}`; return NextResponse.rewrite(new URL(targetUrl)); } return NextResponse.next(); } export const config = { matcher: ["/docs/:path*", "/your-platform-assets/:path*"], }; ``` ## Handle customer configuration Store customer settings and customize the experience: ```tsx title="app/sites/[...slug]/layout.tsx" export default async function CustomerLayout({ children, params, }: { children: React.ReactNode; params: { slug: string[] }; }) { const customerSlug = params.slug[0]; const customer = await getCustomer(customerSlug); return ( {customer.siteTitle}