@rebask/vercel

Vercel adapter for Rebask applications.

Installation

npm install -D @rebask/vercel

Usage

Add the adapter to your vite.config.ts:

import { defineConfig } from "vite";
import { rebask } from "@rebask/core/vite";
import { vercelAdapter } from "@rebask/vercel";

export default defineConfig({
  plugins: [
    rebask(),
    vercelAdapter({
      runtime: "nodejs24.x",
      memory: 1024, // Optional: override memory in MB
      maxDuration: 10, // Optional: override max duration in seconds
      regions: ["iad1"], // Optional: pin function regions
    }),
  ],
});

Options

• runtime: Vercel Node.js runtime version (for example, "nodejs20.x" or "nodejs24.x", default: "nodejs24.x")
• memory: Optional memory override in MB. When omitted, Vercel uses the project/platform default.
• maxDuration: Optional maximum execution duration override in seconds. When omitted, Vercel uses the project/platform default.
• regions: Function regions for deployment. When omitted, Vercel uses the project or vercel.json defaults.
• images: Image optimization configuration for Vercel (optional). Automatically detected from rebaskImage() plugin if present. When provided, routes /_rebask/image to Vercel's image optimization API. See Image Optimization section below.

Data Cache Ownership

When vercelAdapter() is enabled for a Vercel build:

• HTML/RSC entries do not go through your custom rebask.config.* cacheHandler.
• "use cache" entries use your rebask.config.* cacheHandler if you set one (for example, Redis-backed storage).
• If no cacheHandler is configured, "use cache" entries fall back to Vercel Runtime/Data Cache via @vercel/functions.

So, to use Vercel Data Cache for "use cache" on Vercel, remove the custom cacheHandler from rebask.config.*.

Image Optimization

When deploying to Vercel, you can leverage Vercel's built-in image optimization API instead of bundling sharp in your serverless function. This reduces bundle size and improves performance.

Automatic Configuration Detection

The adapter automatically detects rebaskImage() plugin configuration and uses it for Vercel's image optimization. This means you don't need to duplicate your image configuration:

import { defineConfig } from "vite";
import { rebask } from "@rebask/core/vite";
import { rebaskImage } from "@rebask/core/vite/image";
import { vercelAdapter } from "@rebask/vercel";

export default defineConfig({
  plugins: [
    rebask(),
    rebaskImage({
      deviceSizes: [640, 750, 828, 1080, 1200, 1920, 2048, 3840],
      imageSizes: [32, 48, 64, 96, 128, 256, 384],
      formats: ["image/webp"],
      minimumCacheTTL: 14400, // 4 hours
      localPatterns: [{ pathname: "/images/**", search: "" }],
    }),
    vercelAdapter(), // Automatically uses rebaskImage() config
  ],
});

Behavior:

• If rebaskImage() is detected → automatically uses its configuration (no need to provide images option)
• If rebaskImage() is detected AND images option is provided → warns and ignores images option (uses rebaskImage() config)
• If rebaskImage() is NOT detected AND images option is provided → uses the provided images option
• If neither is provided → no image optimization config (uses default rebask.image.ts handler)

Manual Configuration

You can also manually configure image optimization by providing the images option directly:

import { defineConfig } from "vite";
import { rebask } from "@rebask/core/vite";
import { vercelAdapter } from "@rebask/vercel";

export default defineConfig({
  plugins: [
    rebask(),
    vercelAdapter({
      images: {
        sizes: [640, 828, 1200, 1920, 3840],
        formats: ["image/avif", "image/webp"],
        minimumCacheTTL: 300,
        domains: ["example.com"],
        localPatterns: [{ pathname: "/images/**", search: "" }],
        // Optional: remotePatterns for more flexible domain matching
        remotePatterns: [
          {
            protocol: "https",
            hostname: "**.example.com",
          },
        ],
      },
    }),
  ],
});

How it works:

• When image config is provided (via rebaskImage() or images option), the adapter routes /_rebask/image requests to Vercel's /_vercel/image API
• Your application continues using /_rebask/image URLs (consistent across platforms)
• Vercel handles image optimization at the CDN level (faster and more efficient)
• The rebask.image.ts handler becomes optional on Vercel (sharp not needed in bundle)

Image Configuration Options:

• sizes: Array of image widths in pixels (e.g., [640, 828, 1200, 1920, 3840])
• formats: Supported image formats ("image/avif" and/or "image/webp")
• minimumCacheTTL: Minimum cache TTL in seconds (default: 300)
• domains: Allowed domains for remote images (deprecated, use remotePatterns instead)
• remotePatterns: More flexible domain matching patterns for remote images
• localPatterns: Path patterns for local images (e.g., [{ pathname: "/images/**", search: "" }]). If not provided, all local images are allowed.
• dangerouslyAllowSVG: Allow SVG images (default: false)
• contentSecurityPolicy: CSP header for image responses
• contentDispositionType: Content disposition type ("inline" or "attachment")

Note: For non-Vercel deployments, continue using the rebask.image.ts handler with sharp for image optimization.

See Vercel's Image Optimization documentation for full details.

Build

After building your application with vite build, the adapter will generate a .vercel/output directory that can be deployed to Vercel.

Testing Locally

Before deploying, you can test your adapter output locally using the Vercel CLI:

1. Install Vercel CLI (if not already installed):

   pnpm i -g vercel@latest

2. Link your project (optional, but recommended):

   vercel link

   This will prompt you to select or create a Vercel project.

3. Build your application:

   vite build

4. Test locally:

   Option A: Use vercel dev (may rebuild):

   vercel dev

   Note: vercel dev may rebuild your app even if .vercel/output exists. This is expected behavior - it will build and generate .vercel/output, then use it.

   Option B: Use your preview server (uses existing build):

   vite preview

   Or use your custom preview command. This uses the existing build without rebuilding.

Deployment

Using Vercel CLI

Since the adapter generates a pre-built .vercel/output directory, you need to use the --prebuilt flag to tell Vercel to skip building:

vercel deploy --prebuilt

Or for production:

vercel deploy --prebuilt --prod

Automatic Deployments

For automatic deployments from Git, Vercel should automatically detect the Build Output API format when .vercel/output exists after the build completes.

How it works:

1. Vercel runs your build command (e.g., vite build)
2. The adapter generates .vercel/output during the build
3. Vercel automatically detects the Build Output API format (when config.json with version: 3 exists in .vercel/output)
4. Vercel deploys using the .vercel/output directory instead of framework defaults

Configuration:

Create a vercel.json in your project root:

{
  "buildCommand": "vite build"
}

Or leave it empty - Vercel will auto-detect Vite and run vite build automatically.

Important: Do NOT set buildCommand: null for Git-based deployments, as Vercel needs to run the build to generate .vercel/output. The buildCommand: null is only useful for vercel deploy --prebuilt when you've already built locally.

Troubleshooting:

If Vercel is still treating your app as a standard Vite app instead of using Build Output API:

• Ensure .vercel/output/config.json exists with version: 3
• Verify .vercel/output/functions/ and .vercel/output/static/ directories exist
• Check that your build completes successfully and generates .vercel/output
• Ensure your project root is correctly configured in Vercel dashboard settings