@ripple-ts/adapter-vercel

Vercel adapter for the Ripple metaframework.

Deploys your Ripple SSR application to Vercel using the Build Output API v3.

Installation

pnpm add @ripple-ts/adapter-vercel

Usage

ripple.config.ts

import { defineConfig } from '@ripple-ts/vite-plugin';
import { serve, runtime } from '@ripple-ts/adapter-vercel';
import { routes } from './src/routes.ts';

export default defineConfig({
  adapter: { serve, runtime },
  router: { routes },
});

Build & Deploy

The adapter generates Vercel's Build Output API v3 structure.

Option 1: Post-build CLI

pnpm vite build && ripple-adapt-vercel

Or add to your package.json:

{
  "scripts": {
    "build": "vite build",
    "vercel-build": "vite build && ripple-adapt-vercel"
  }
}

Option 2: Use adapt() programmatically

import { adapt } from '@ripple-ts/adapter-vercel';

await adapt({
  outDir: 'dist',
  // options...
});

Options

| Option | Type | Default | Description | | ------------------------ | -------------------- | ------------- | ------------------------------------------------------------------------ | | outDir | string | 'dist' | Build output directory (from vite build) | | serverless | ServerlessConfig | {} | Serverless function configuration | | serverless.runtime | string | auto-detected | Node.js runtime version ('nodejs20.x', 'nodejs22.x', 'nodejs24.x') | | serverless.regions | string[] | undefined | Deployment regions | | serverless.memory | number | undefined | Memory (MB) allocated to the function | | serverless.maxDuration | number | undefined | Maximum execution time (seconds) | | isr | ISRConfig \| false | false | Incremental Static Regeneration config | | isr.expiration | number \| false | — | Seconds before background revalidation (false = never expire) | | isr.bypassToken | string | undefined | Token to bypass the ISR cache | | isr.allowQuery | string[] | undefined | Query params included in the cache key (empty = ignore query) | | images | ImagesConfig | undefined | Vercel Image Optimization config | | headers | VercelHeader[] | [] | Custom response headers | | redirects | VercelRedirect[] | [] | Custom redirects | | rewrites | VercelRewrite[] | [] | Additional rewrites (prepended before catch-all) | | cleanUrls | boolean | true | Remove .html extensions from URLs | | trailingSlash | boolean | undefined | Enforce trailing slash behavior |

How It Works

1. vite build produces dist/client/ (static assets) and dist/server/entry.js (server bundle)
2. adapt() restructures the output into .vercel/output/:
   • Copies dist/client/ → .vercel/output/static/
   • Creates a serverless function at .vercel/output/functions/index.func/
   • Generates .vercel/output/config.json with routing rules
   • Uses @vercel/nft to trace and bundle server dependencies

The generated structure:

.vercel/output/
├── config.json                    # Build Output API v3 config
├── static/                        # Static files (served by Vercel CDN)
│   ├── assets/
│   ├── index.html
│   └── ...
└── functions/
    └── index.func/                # Serverless function
        ├── index.js               # Handler entry point
        ├── .vc-config.json        # Function configuration
        ├── package.json           # ESM marker
        └── ... (traced deps)

Local Development

The adapter re-exports serve and runtime from @ripple-ts/adapter-node, so local development with vite dev and ripple-preview works exactly the same as with adapter-node.

Incremental Static Regeneration (ISR)

Enable ISR to let Vercel cache serverless responses at the edge and revalidate them in the background:

await adapt({
  isr: {
    // Re-generate cached pages every 60 seconds
    expiration: 60,
  },
});

Never-expiring cache (only revalidated via on-demand revalidation):

await adapt({
  isr: {
    expiration: false,
    bypassToken: process.env.REVALIDATION_TOKEN,
  },
});

Cache key control — only include specific query parameters:

await adapt({
  isr: {
    expiration: 300,
    allowQuery: ['page', 'q'], // /search?q=foo and /search?q=bar are cached separately
  },
});

The ISR config is emitted as a prerender field in the function's .vc-config.json, following Vercel's Build Output API v3 prerender configuration.

Vercel Configuration

No vercel.json configuration is needed — the adapter generates all necessary routing rules via the Build Output API.

If you do have a vercel.json, the adapter respects your buildCommand and outputDirectory settings. Set your build command to run the adapter:

{
  "buildCommand": "pnpm vite build && pnpm ripple-adapt-vercel"
}