Deploy to Vercel

Deploy your Opal Editor sites to Vercel’s global edge network with instant deployments and automatic SSL

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:

API Token (Recommended)

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

Related Resources

• Vercel Documentation
• Vercel API Reference
• Publishing Overview
• Build System