Skip to main content
Vercel is a cloud platform optimized for frontend frameworks and static sites. Opal Editor integrates with Vercel’s API to provide instant deployments to their global edge network.

​
Prerequisites

Before deploying to Vercel:
  • A Vercel account (sign up at vercel.com)
  • A Vercel API token or OAuth authentication
  • A completed build ready for deployment

​
Authentication Setup

Opal Editor supports two authentication methods for Vercel:
1

Create an API token

  1. Go to Vercel Account Settings > Tokens
  2. Click “Create Token”
  3. Give it a descriptive name (e.g., “Opal Editor”)
  4. Select the appropriate scope (Full Account or specific projects)
  5. Copy the generated token
2

Add to Opal Editor

Create a new Vercel API authentication in Opal Editor and paste your token.
Store your Vercel token securely. It provides access to your Vercel account and projects.

​
OAuth

Use OAuth for streamlined authentication:
  • Automatic token refresh
  • No manual token management
  • Secure credential storage

​
Destination Configuration

Configure your Vercel deployment destination: 
{
  "remoteAuthId": "your-auth-id",
  "label": "My Vercel Project",
  "meta": {
    "project": "my-project-name"
  }
}

​
Configuration Fields

  • project (required): Your Vercel project name
    • Must be lowercase
    • Can include letters, digits, ., _, and -
    • Cannot contain the sequence ---
    • Maximum 100 characters
Project names are automatically validated against Vercel’s naming requirements. Invalid names will show an error message.

​
Deployment Process

1

Create or select a project

Specify a Vercel project name:
  • If the project doesn’t exist, it will be created automatically
  • Existing projects can be selected from your account
2

Build your site

Complete a build in Opal Editor:
  • Markdown is converted to HTML
  • Templates are rendered
  • Assets are prepared
  • Files are optimized for deployment
3

Deploy to Vercel

Start the deployment:
  • Files are uploaded to Vercel’s edge network
  • Deployment progress is tracked in real-time
  • Build status is monitored
4

Access deployment URLs

Receive two URLs:
  • Destination URL: https://{project}.vercel.app (main project URL)
  • Deployment URL: Unique URL for this specific deployment

​
How It Works

The Vercel deployment agent (RemoteAuthVercelAgent) manages:
  1. Project Validation: Checks if the project exists or creates it
  2. File Upload: Converts files to Vercel’s deployment format
  3. Deployment Creation: Initiates a new deployment
  4. Status Polling: Monitors deployment progress until completion
  5. URL Generation: Returns both destination and deployment-specific URLs

​
File Preparation

Opal Editor converts your build output: 
// Files are converted to Vercel's format:
{
  type: "file",
  path: "index.html",
  encoding: "utf-8",
  getContent: () => Promise<string>
}
  • Text files use UTF-8 encoding
  • Binary files use base64 encoding
  • All file types are supported

​
Features

​
Instant Global Deployment

Vercel deploys to their global edge network:
  • Content served from the nearest edge location
  • Sub-second initial page loads
  • Automatic CDN caching

​
Deployment URLs

Each deployment receives unique URLs:
  • Production URL: https://{project}.vercel.app
  • Deployment Preview: https://{deployment-id}.vercel.app
  • Perfect for testing before going live

​
Automatic HTTPS

All deployments include:
  • Automatic SSL certificates
  • HTTPS enforced by default
  • No configuration needed

​
Zero Configuration

No build configuration required:
  • Deploy pure static files
  • No framework detection needed
  • Works with any static site

​
Team Projects

Deploy to team projects:
  • The API automatically detects team membership
  • Team projects are accessible with appropriate permissions
  • Team ID is resolved automatically
Ensure your API token has access to the team you want to deploy to.

​
Troubleshooting

​
Project Name Validation Errors

Project names must follow Vercel’s naming rules:
  • Lowercase only
  • Letters, digits, ., _, - allowed
  • Cannot contain ---
  • Max 100 characters
Solution: Update your project name to meet these requirements.

​
Authentication Failures

If authentication fails:
  1. Verify your API token is correct
  2. Check token hasn’t expired
  3. Ensure token has necessary scopes
  4. Try regenerating the token

​
Deployment Timeout

If deployment takes too long:
  • Check Vercel’s status page for outages
  • Verify your internet connection
  • Try deploying again
  • Check deployment logs for specific errors

​
Invalid Token Scope

If you see scope errors:
  • Ensure your token has access to the project
  • Check team permissions if deploying to a team
  • Create a new token with appropriate scopes

​
Best Practices

  1. Use meaningful project names: Choose descriptive, lowercase names
  2. Test deployments: Use deployment preview URLs to test before production
  3. Monitor deployment status: Watch the logs for any issues
  4. Leverage preview URLs: Share deployment-specific URLs for review
  5. Configure custom domains: Add custom domains in the Vercel dashboard

​
Advanced Configuration

​
Custom Domains

Add custom domains in the Vercel dashboard:
  1. Go to your project settings
  2. Navigate to Domains
  3. Add your custom domain
  4. Configure DNS as instructed

​
Environment Variables

While Opal Editor deploys static files, you can configure environment variables in Vercel for build-time usage:
  • Set in the Vercel dashboard
  • Available during Vercel’s build process
  • Not applicable to Opal Editor’s local builds

​
Edge Configuration

Optimize edge delivery:
  • Add vercel.json to your build output
  • Configure headers, redirects, and rewrites
  • Set caching policies
Example vercel.json: 
{
  "headers": [
    {
      "source": "/(.*)",
      "headers": [
        {
          "key": "Cache-Control",
          "value": "public, max-age=3600"
        }
      ]
    }
  ],
  "redirects": [
    {
      "source": "/old-path",
      "destination": "/new-path",
      "permanent": true
    }
  ]
}

​
Deployment Polling

Opal Editor polls Vercel’s API to track deployment status:
  • Checks every 2.5 seconds by default
  • Continues until deployment completes
  • Shows real-time status updates
  • Handles both success and failure states

Build docs developers (and LLMs) love

Get started for freeTalk to us