Documentation

Everything you need to build and deploy on Relay.

Quick Start

Get your first edge function deployed in under 2 minutes. This guide walks you through installing the CLI, creating a project, and deploying to Relay's global edge network.

terminal 
# Install the CLI
$ npm install -g @relay/cli

# Create a new project
$ relay init my-edge-app
✓ Created project in ./my-edge-app

# Deploy to the edge
$ cd my-edge-app && relay deploy
Deploying to 47 edge locations...
✓ Live at https://my-edge-app.relay.global

Installation

The Relay CLI requires Node.js 18 or later. Install it globally via npm:

terminal 
$ npm install -g @relay/cli

# Verify installation
$ relay --version
relay v3.2.1

# Authenticate with your account
$ relay login
Opening browser for authentication...
✓ Logged in as dev@example.com

Alternatively, you can use the Relay SDK directly in your project:

terminal 
$ npm install @relay/sdk

Configuration

Create a relay.config.js file in your project root to customize build and deployment settings.

relay.config.js 
export default {
  name: "my-edge-app",
  regions: ["auto"],       // or specify: ["eu-west", "us-east"]
  build: {
    command: "npm run build",
    output: "./dist",
  },
  routes: [
    { pattern: "/api/*", handler: "./functions/api.ts" },
    { pattern: "/*", handler: "./static" },
  ],
  env: {
    DATABASE_URL: { secret: true },
  },
};

Environment Variables

Set environment variables and secrets via the CLI or dashboard. Secrets are encrypted at rest and only available to your edge functions at runtime.

terminal 
$ relay env set DATABASE_URL "postgres://..." --secret
✓ Secret DATABASE_URL set for production

$ relay env list
DATABASE_URL  ••••••••  (secret)
NODE_ENV      production

Deploying

Deploy your project to all configured regions with a single command. Relay handles building, uploading, and propagating your code to every edge node.

terminal 
$ relay deploy --region=auto
Building project...
✓ Build completed in 1.2s (4 functions, 12 assets)
Deploying to 47 edge locations...
✓ eu-west-1    ready (32ms)
✓ us-east-1    ready (28ms)
✓ ap-south-1   ready (45ms)
✓ ...and 44 more regions
✓ Deployed to https://my-edge-app.relay.global
  Latency: p50=4ms p99=12ms

Preview Deployments

Every pull request gets an automatic preview deployment with a unique URL. Connect your GitHub repository to enable this:

terminal 
$ relay git connect
✓ Connected to github.com/your-org/my-edge-app
  Preview deployments enabled for all PRs

Edge Functions

Edge functions run JavaScript or TypeScript at the nearest edge node to your users. They support the Web Platform APIs including fetch, Request, Response, and streams.

functions/api.ts 
import { EdgeFunction, json } from "@relay/sdk";

export default EdgeFunction({
  async handler(request, context) {
    const geo = context.geo;  // { city, country, lat, lng }
    const cache = context.cache;

    // Check cache first
    const cached = await cache.get("data-key");
    if (cached) return json(cached);

    // Fetch from origin
    const data = await fetch("https://api.example.com/data");
    const body = await data.json();

    // Cache for 60 seconds
    await cache.set("data-key", body, { ttl: 60 });

    return json(body, {
      headers: { "X-Edge-Region": context.region },
    });
  },
});

API Reference

The Relay REST API lets you manage deployments, functions, and analytics programmatically.

Authentication

All API requests require an API key passed in the Authorization header:

terminal 
$ curl https://api.relay.global/v1/deployments \
    -H "Authorization: Bearer rl_live_xxxxxxxxxxxx"

{
  "deployments": [
    {
      "id": "dpl_abc123",
      "status": "active",
      "regions": 47,
      "url": "https://my-edge-app.relay.global",
      "created_at": "2026-03-30T14:22:00Z"
    }
  ]
}

Endpoints

Method Endpoint Description
GET /v1/deployments List all deployments
POST /v1/deployments Create a new deployment
GET /v1/functions List edge functions
GET /v1/analytics Query analytics data
DELETE /v1/deployments/:id Delete a deployment