Platforms

Deploying to Vercel

Deploy your RivetKit app to Vercel.

Steps

Prerequisites

Vercel account
Your RivetKit app
- If you don’t have one, see the Quickstart page or our Examples
Access to the Rivet Cloud or a self-hosted Rivet Engine

Prepare Your Application

Make sure your project is configured correctly for Vercel deployment.

Your Hono project needs:

A vercel.json file with the Hono framework specified:

{
  "framework": "hono"
}

vercel.json

Your server file must import from "hono" for Vercel to recognize the framework:

// You MUST import from "hono" for Vercel to detect this as a Hono app
import { Hono } from "hono";
import { registry } from "./actors.ts";

const app = new Hono();
app.all("/api/rivet/*", (c) => registry.handler(c.req.raw));
export default app;

TypeScript

Use .ts file extensions in imports and configure your tsconfig.json:

{
  "compilerOptions": {
    "allowImportingTsExtensions": true,
    "rewriteRelativeImportExtensions": true
  }
}

tsconfig.json

See the Hello World template for a complete example.

For more details on Hono deployments, see Vercel’s Hono documentation.

Deploy to Vercel

Connect your GitHub repository to Vercel
Vercel will deploy your app

Configure Preview Deployments (Recommended)

Add a GitHub action to automatically create isolated Rivet namespaces for each PR:

Add these secrets to your GitHub repository:
- RIVET_CLOUD_TOKEN: Get from Rivet Dashboard → Settings → Advanced → Cloud API Tokens
- VERCEL_TOKEN: Get from Vercel Account Settings
Create .github/workflows/rivet-preview.yml:

name: Rivet Preview

on:
  pull_request:
    types: [opened, synchronize, reopened]
  push:
    branches: [main]

concurrency:
  group: rivet-preview-${{ github.event.pull_request.number || github.ref }}
  cancel-in-progress: true

jobs:
  rivet-preview:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
    steps:
      - uses: rivet-dev/preview-namespace-action@v1
        with:
          platform: vercel
          rivet-token: ${{ secrets.RIVET_CLOUD_TOKEN }}
          vercel-token: ${{ secrets.VERCEL_TOKEN }}

YAML

Troubleshooting

Error: ENOENT: no such file or directory, mkdir '.../rivetkit/.../state'

Cause: The RIVET_ENDPOINT environment variable is not configured. RivetKit falls back to the file system driver, which fails in Vercel’s read-only serverless environment.

Solution: Ensure RIVET_ENDPOINT is set with your Rivet endpoint using the URL auth format:

RIVET_ENDPOINT=https://my-namespace:sk_****@api.rivet.dev

If using the preview-namespace-action, this is configured automatically.

The /api/rivet/metadata endpoint returns data but clientEndpoint, clientNamespace, and clientToken are missing.

Cause: The RIVET_PUBLIC_ENDPOINT environment variable is not configured. This tells the metadata endpoint what connection info to provide to clients.

Solution: Set RIVET_PUBLIC_ENDPOINT with the publishable token (for client access):

RIVET_PUBLIC_ENDPOINT=https://my-namespace:pk_****@api.rivet.dev

If using the preview-namespace-action, this is configured automatically.