Deployment

Hive is built as a static frontend with serverless API functions, making it ideal for deployment on platforms like Vercel, Netlify, or Cloudflare Pages.

Prerequisites

Before deploying, ensure you have:

✅ A configured Supabase project (setup guide)
✅ Environment variables ready (variables list)
✅ Git repository with your Hive source code

Deploying to Vercel (Recommended)

Vercel provides the best experience for deploying Hive with automatic serverless function deployment.

Quick Deploy

Import Repository

Go to vercel.com and sign in
Click Add New… → Project
Import your Git repository (GitHub, GitLab, or Bitbucket)

Configure Build Settings

Vercel should auto-detect the configuration. If not, set:

Framework Preset: Other
Build Command: (leave empty)
Output Directory: frontend
Install Command: npm install
Root Directory: source/frontend

Set Environment Variables

Add these environment variables in the Vercel dashboard:

SUPABASE_URL=https://your-project.supabase.co
SUPABASE_ANON_KEY=eyJhbGci...
SUPABASE_SERVICE_KEY=eyJhbGci...
ADMIN_EMAILS=admin@company.com

# Optional: Expose to client
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbGci...

Never expose SUPABASE_SERVICE_KEY as a NEXT_PUBLIC_* variable. It must remain server-side only.

Deploy

Click Deploy and wait for the build to complete. Vercel will provide a production URL.

Serverless Functions

Vercel automatically deploys files in the /api directory as serverless functions. Hive includes:

// POST /api/auth-sync
// Syncs Supabase Auth changes to usuarios table
// Requires admin role to execute

module.exports = async (req, res) => {
  // Admin-only: update email, password, username
  // Mirrors changes to usuarios table
  // Validates uniqueness constraints
};

Both functions use the @supabase/supabase-js package specified in package.json. Vercel automatically installs dependencies for serverless functions.

Vercel Configuration

Create a vercel.json in the frontend directory for advanced configuration:

vercel.json

{
  "version": 2,
  "builds": [
    {
      "src": "index.html",
      "use": "@vercel/static"
    },
    {
      "src": "api/**/*.js",
      "use": "@vercel/node"
    }
  ],
  "routes": [
    {
      "src": "/api/(.*)",
      "dest": "/api/$1"
    },
    {
      "src": "/(.*)",
      "dest": "/$1"
    }
  ],
  "env": {
    "NODE_VERSION": "18"
  },
  "functions": {
    "api/**/*.js": {
      "memory": 1024,
      "maxDuration": 10
    }
  }
}

builds

array

Defines how Vercel processes different file types. Static files use @vercel/static, API functions use @vercel/node.

routes

array

Routing rules for requests. API routes go to serverless functions, all other requests serve static files.

functions.memory

number

default:"1024"

Memory allocation for serverless functions in MB. Increase if functions timeout.

functions.maxDuration

number

default:"10"

Maximum execution time for serverless functions in seconds.

Deploying to Netlify

Netlify also supports serverless functions with a similar workflow.

Create netlify.toml

Create a netlify.toml in the frontend directory:

netlify.toml

[build]
  publish = "."
  functions = "api"

[[redirects]]
  from = "/api/*"
  to = "/.netlify/functions/:splat"
  status = 200

[dev]
  framework = "#static"

Deploy to Netlify

Connect your Git repository to Netlify
Set the Base directory to source/frontend
Leave Build command empty
Set Publish directory to .
Add environment variables (same as Vercel)
Click Deploy site

Netlify Functions have a different file structure than Vercel. You may need to adjust the api directory exports to match Netlify’s format.

Deploying to Other Platforms

Cloudflare Pages

Cloudflare Pages supports static hosting but requires Cloudflare Workers for serverless functions:

Deploy static files to Cloudflare Pages
Deploy /api functions as Cloudflare Workers
Configure routing rules to proxy /api/* to Workers

Render

Render supports static sites with serverless functions:

Create a new Static Site on Render
Set Build Command to (empty)
Set Publish Directory to source/frontend
Add environment variables
For API functions, create separate Web Services or use Render’s serverless support (if available)

Railway

Railway is better suited for full-stack applications:

Deploy as a Node.js service
Use Express or similar to serve static files and handle /api routes
Not recommended for this static + serverless architecture

Custom Domain Setup

Vercel

Add Domain

Go to Project Settings → Domains
Enter your custom domain (e.g., hive.company.com)
Click Add

Configure DNS

Vercel provides DNS records to add to your domain registrar:

A Record: Points to Vercel’s IP
CNAME Record: Points to cname.vercel-dns.com

Choose the option that works with your DNS provider.

Verify

Wait for DNS propagation (can take up to 48 hours, usually much faster). Vercel will automatically issue an SSL certificate.

Netlify

Similar process:

Domain Settings → Add custom domain
Configure DNS with provided records
Enable HTTPS (automatic with Let’s Encrypt)

SSL/HTTPS Configuration

Both Vercel and Netlify provide automatic SSL certificates via Let’s Encrypt:

✅ Automatic renewal - Certificates renew before expiration
✅ Force HTTPS - Redirect HTTP to HTTPS automatically
✅ Modern TLS - Supports TLS 1.2 and 1.3

Always use HTTPS in production. Supabase Auth requires secure connections to prevent token interception.

Environment-Specific Configuration

Preview Deployments

Both Vercel and Netlify support preview deployments for pull requests:

Vercel: Automatic preview URLs for every push
Netlify: Deploy previews with unique URLs

Set preview-specific environment variables if needed:

# Preview environment (Vercel)
SUPABASE_URL=https://staging-project.supabase.co
SUPABASE_ANON_KEY=staging_key...

Production vs Development

Use separate Supabase projects for production and development:

SUPABASE_URL=https://prod-project.supabase.co
SUPABASE_ANON_KEY=prod_anon_key...
SUPABASE_SERVICE_KEY=prod_service_key...
ADMIN_EMAILS=admin@company.com

Post-Deployment Checklist

Verify Environment Variables

Check that all required variables are set correctly in the deployment platform.

Test Supabase Connection

Open your deployed site’s browser console and verify:

console.log(window.__supabaseClient);
// Should show Supabase client object

Test Authentication

Try logging in with a test user to verify Auth integration.

Test API Functions

Make a POST request to /api/presence-ping with a valid Bearer token:

curl -X POST https://your-site.vercel.app/api/presence-ping \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"state": "online"}'

Monitor Logs

Check deployment platform logs for any errors:

Vercel: Project → Deployments → View Function Logs
Netlify: Site → Functions → View logs

Performance Optimization

Caching

Configure caching headers in vercel.json:

{
  "headers": [
    {
      "source": "/(.*).js",
      "headers": [
        {
          "key": "Cache-Control",
          "value": "public, max-age=31536000, immutable"
        }
      ]
    },
    {
      "source": "/(.*).css",
      "headers": [
        {
          "key": "Cache-Control",
          "value": "public, max-age=31536000, immutable"
        }
      ]
    }
  ]
}

CDN

Both Vercel and Netlify include global CDN by default:

Static assets cached at edge locations
Automatic compression (gzip, Brotli)
HTTP/2 and HTTP/3 support

Serverless Function Optimization

Reduce cold start times:

Keep function code minimal
Use environment variables instead of fetching config
Cache Supabase client instances when possible

Troubleshooting

500 Error on API routes

Serverless function crashed or timed out.Solution:

Check function logs for error messages
Verify environment variables are set
Increase maxDuration in vercel.json if timeout
Check that @supabase/supabase-js is in package.json dependencies

404 Error on API routes

API functions not deployed correctly.Solution:

Verify /api directory exists in source/frontend
Check build logs for function deployment messages
Ensure vercel.json or netlify.toml routes are correct

CORS errors on API calls

Missing CORS headers in serverless functions.Solution: Add CORS headers to API responses:

res.setHeader('Access-Control-Allow-Origin', '*');
res.setHeader('Access-Control-Allow-Methods', 'POST, OPTIONS');
res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization');

Build fails with 'Module not found'

Missing dependencies or incorrect paths.Solution:

Run npm install in source/frontend
Verify package.json includes @supabase/supabase-js
Check that all import paths are correct

Deployment succeeds but site is blank

Incorrect output directory or missing index.html.Solution:

Verify index.html exists in source/frontend
Check deployment logs for “Publish directory” path
Ensure all referenced assets (CSS, JS) are accessible

Next Steps

Environment Variables

Review all available environment variables

Supabase Setup

Configure your Supabase backend

Get Started

Core Features

User Guide

Configuration

Prerequisites

Deploying to Vercel (Recommended)

Quick Deploy

Serverless Functions

Vercel Configuration

Deploying to Netlify

Deploying to Other Platforms

Cloudflare Pages

Render

Railway

Custom Domain Setup

Vercel

Netlify

SSL/HTTPS Configuration

Environment-Specific Configuration

Preview Deployments

Production vs Development

Post-Deployment Checklist

Performance Optimization

Caching

CDN

Serverless Function Optimization

Troubleshooting

Next Steps

Environment Variables

Supabase Setup

Build docs developers (and LLMs) love

Get Started

Core Features

User Guide

Configuration

​Prerequisites

​Deploying to Vercel (Recommended)

​Quick Deploy

​Serverless Functions

​Vercel Configuration

​Deploying to Netlify

​Deploying to Other Platforms

​Cloudflare Pages

​Render

​Railway

​Custom Domain Setup

​Vercel

​Netlify

​SSL/HTTPS Configuration

​Environment-Specific Configuration

​Preview Deployments

​Production vs Development

​Post-Deployment Checklist

​Performance Optimization

​Caching

​CDN

​Serverless Function Optimization

​Troubleshooting

​Next Steps

Environment Variables

Supabase Setup

Build docs developers (and LLMs) love

Prerequisites

Deploying to Vercel (Recommended)

Quick Deploy

Serverless Functions

Vercel Configuration

Deploying to Netlify

Deploying to Other Platforms

Cloudflare Pages

Render

Railway

Custom Domain Setup

Vercel

Netlify

SSL/HTTPS Configuration

Environment-Specific Configuration

Preview Deployments

Production vs Development

Post-Deployment Checklist

Performance Optimization

Caching

CDN

Serverless Function Optimization

Troubleshooting

Next Steps