Multi-Project Platforms Reference

Start with our Custom Blocks and Actions that speed up your usage of the Vercel API.

Create a new Vercel project using the create project API.

SDK:

import { Vercel } from '@vercel/sdk';
 
const vercel = new Vercel({
  bearerToken: '<YOUR_BEARER_TOKEN_HERE>',
});
 
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();

Create a deployment for a project using the create deployment API.

SDK:

import { Vercel } from '@vercel/sdk';
 
const vercel = new Vercel({
  bearerToken: '<YOUR_BEARER_TOKEN_HERE>',
});
 
async function run() {
  const result = await vercel.deployments.createDeployment({
    teamId: 'team_1a2b3c4d5e6f7g8h9i0j1k2l',
    slug: 'my-team-url-slug',
    requestBody: {
      deploymentId: 'dpl_2qn7PZrx89yxY34vEZPD31Y9XVj6',
      files: [
        {
          data: '<value>',
          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();

Get deployments for a project using the list deployments API.

SDK:

import { Vercel } from '@vercel/sdk';
 
const vercel = new Vercel({
  bearerToken: '<YOUR_BEARER_TOKEN_HERE>',
});
 
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();

Remove a project and all its deployments using the delete project API.

SDK:

import { Vercel } from '@vercel/sdk';
 
const vercel = new Vercel({
  bearerToken: '<YOUR_BEARER_TOKEN_HERE>',
});
 
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();

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

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

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

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

Problem: Hitting function size or execution limits.

Solution:

• Review function sizes
• Optimize bundle size
• Check execution time limits
• Consider upgrading plan
• Split large functions

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.

Project limits depend on your plan:

• Hobby: Limited projects per account
• Pro: Higher limits
• Enterprise: Custom limits based on needs

Contact sales for specific limits.

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.

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

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.

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

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.

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.

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

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

• Concepts: Understand multi-project architecture
• Quickstart: Get started with multi-project platforms
• Vercel SDK: Complete SDK documentation