Concepts

Understanding the core concepts of multi-project architecture helps you build scalable platforms with isolated tenant environments.

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:

create-project.ts

import { projectsCreateProject } from "@vercel/sdk/funcs/projectsCreateProject.js";

const { value: project } = await projectsCreateProject(vercel, {
  teamId: "team_1234",
  requestBody: {
    name: `tenant-${tenantId}`,
    framework: "nextjs",
  },
});

Project templates

Generate projects from templates to ensure consistency:

create-project-from-template.ts

const { value: project } = await projectsCreateProject(vercel, {
  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

Create: Deploy code to project
Build: Vercel builds the application
Preview: Test deployment before promoting
Production: Promote deployment to production
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:

add-domain.ts

import { projectsAddProjectDomain } from "@vercel/sdk/funcs/projectsAddProjectDomain.js";

await projectsAddProjectDomain(vercel, {
  idOrName: project.id,
  requestBody: {
    name: "tenant1.com",
  },
});