Skip to main content
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:
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

Build docs developers (and LLMs) love

Get started for freeTalk to us