Quickstart | Vercel for Platforms

Summary

This document outlines the process of 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:

Creating a Project for each chat
Deploying each version of the Artifact to the Project on demand when the user wants to "Publish"
Auto-aliasing the *.CUSTOM_SUFFIX.com domain that you want, or a user provided domain.
Optional Pretecting all the deployments through a central proxy
Optional Configuring the sites as subpaths on a single domain

1. 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
Ceate a project for each chat
- 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

Create a Project:

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);
}

2. Deployment

Every project has one "Production" domain that points to the most recent version (while keeping previous versions) and infinite "Preview" deployments, 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
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:

npx @vercel/platforms@latest add deploy-files

Usage:

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: "<html><body><h1>Hello from my platform!</h1></body></html>"
  },
  {
    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"
  }
})

3. Domain Aliasing

If you want deployments to have a custom suffix: *.CUSTOM_SUFFIX.com, you can:
- Setup a wildcard domain for your domain
- 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
  - Alias a specific URL to only that one deployment in a project
- Alternatively allow customers to bring in a domain they own elsewhere to assign to their sites

4. Optional Protecting all deployments behind SSO or authentication, if you want central authentication:

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 header, that will lock down direct access to the Vercel applications
Alias all domains to the proxy site instead so all traffic goes to it first
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

5. Optional Configuring the sites to be subpaths instead of custom domains

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
You can then create a 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