Deploy to Netlify

Publish your Opal Editor sites to Netlify with automatic CDN, SSL, and continuous deployment

Netlify is a popular hosting platform that provides automatic CDN distribution, SSL certificates, and continuous deployment. Opal Editor integrates directly with Netlify’s API to deploy your static sites.

Prerequisites

Before deploying to Netlify, you’ll need:

• A Netlify account (sign up at netlify.com)
• A Netlify personal access token or OAuth authentication
• A built site ready for deployment

Authentication Setup

Opal Editor supports two authentication methods for Netlify:

API Token (Recommended)

1. Generate a personal access token

   1. Go to Netlify User Settings > Applications
   2. Click “New access token”
   3. Give it a descriptive name (e.g., “Opal Editor”)
   4. Copy the generated token
2. Add authentication to Opal Editor

   Create a new Netlify API authentication in Opal Editor and paste your token.

OAuth

Alternatively, use OAuth for easier authentication:

• Connect your Netlify account through the OAuth flow
• Opal Editor will handle token refresh automatically

Destination Configuration

Configure your Netlify deployment destination:

{
  "remoteAuthId": "your-auth-id",
  "label": "My Netlify Site",
  "meta": {
    "siteName": "my-site-name",
    "siteId": "auto-resolved"
  }
}

Configuration Fields

• siteName (required): The name of your Netlify site (e.g., my-awesome-site)
• siteId (auto-resolved): Automatically resolved from the site name
• label: A friendly name for this destination in Opal Editor

The siteName will be used to create your site’s default URL: https://my-site-name.netlify.app

Deployment Process

1. Create or select a site

   Either select an existing Netlify site or create a new one:

   • Existing sites are validated against your Netlify account
   • New sites are created automatically during first deployment
2. Build your site

   Run a build in Opal Editor to generate static files:

   // The build process:
   // 1. Indexes source files
   // 2. Processes markdown and templates
   // 3. Copies assets
   // 4. Generates final HTML
   
3. Deploy to Netlify

   Deploy the built files:

   • Files are uploaded directly to Netlify
   • Deployment progress is shown in real-time
   • A unique deployment URL is generated
4. Access your site

   Once deployed, your site is available at:

   • Main URL: https://{siteName}.netlify.app
   • Custom domains can be configured in Netlify dashboard

How It Works

The Netlify deployment agent (RemoteAuthNetlifyAgent) handles:

1. Site Validation: Verifies the site exists in your account
2. File Preparation: Converts build output to Netlify’s deployment format
3. Upload: Sends files using Netlify’s deployment API
4. Monitoring: Tracks deployment status until completion

File Handling

Opal Editor prepares your files for Netlify:

• All files are converted to the universal deploy format
• Binary files are base64 encoded
• Text files use UTF-8 encoding
• A minimal favicon.ico is added if missing

Features

Automatic SSL

Netlify provides automatic SSL certificates for all deployments:

• HTTPS enabled by default
• Certificates are managed automatically
• No configuration required

Deploy Previews

Each deployment gets a unique URL:

• Main site URL: https://{siteName}.netlify.app
• Deployment-specific URLs for testing

Rollback Support

Netlify maintains deployment history:

• Roll back to previous deployments in the Netlify dashboard
• All deployments are preserved

Troubleshooting

Site Not Found Error

If you see “Site not found in your Netlify account”, verify:

• The site name matches exactly (case-sensitive)
• Your API token has access to the site
• The site exists in your Netlify account

Solution: Check your site name in the Netlify dashboard and ensure it matches your configuration.

Authentication Errors

If authentication fails:

• Verify your access token is valid
• Check that the token hasn’t expired
• Ensure the token has the necessary permissions
• Try regenerating your access token

Upload Failures

If file uploads fail:

• Check your internet connection
• Verify the build completed successfully
• Look for specific error messages in the deployment logs
• Try deploying again (uploads are idempotent)

Rate Limiting

Netlify has API rate limits:

• Free tier: Limited requests per minute
• Pro tier: Higher limits
• If you hit limits, wait a few minutes and retry

Best Practices

1. Use descriptive site names: Choose a meaningful name for your site
2. Test builds locally: Ensure your build completes successfully before deploying
3. Monitor deployment logs: Watch the logs for any warnings or errors
4. Configure custom domains: Set up custom domains in the Netlify dashboard for production sites
5. Use environment variables: Configure site settings in Netlify for different environments

Advanced Configuration

Netlify Configuration File

You can include a netlify.toml file in your build output for advanced configuration:

[build]
  publish = "."

[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200

[[headers]]
  for = "/*"
  [headers.values]
    X-Frame-Options = "DENY"
    X-Content-Type-Options = "nosniff"

Custom Headers

Add custom headers for security and caching:

• Include _headers file in your build output
• Configure in netlify.toml

Redirects and Rewrites

Configure redirects:

• Include _redirects file in your build output
• Or use netlify.toml for redirect rules

Related Resources

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