Vercel

If your app runs on Vercel, four of its platform services can sit behind MainSDK interfaces: Vercel Runtime Cache behind kv, Vercel Queues behind jobs, Vercel Global Config (formerly Edge Config) behind config, and Vercel Flags behind flags. Your code calls the same interfaces it would on any host, and the services live in the Vercel project you already deploy. Pick these drivers when you deploy on Vercel and want fewer outside accounts; pick each one separately, since every interface has its own driver line.

For deploying a MainSDK app on Vercel (secrets as references, the check on every preview, the firewall export), see Deploy on Vercel.

kv:
  driver: vercel-runtime-cache

workflows:
  driver: vercel-workflow

jobs:
  driver: vercel-queues

sandbox:
  driver: vercel-sandbox

deploy:
  driver: vercel

config:
  driver: vercel-global-config

flags:
  driver: vercel-flags

Before you start

You need a Vercel account and a project linked to your repository.

1. Runtime Cache is part of the Vercel functions runtime for your project; there is no store to create.
2. Queues: enable Vercel Queues for the project and decide which topics your jobs use.
3. Global Config: create a Global Config store, connect it to the project, and add your settings as items.
4. Flags: create your flags and targeting rules in Vercel Flags for the project.
5. Environment variables: connecting a store to the project can add its connection variable for you. Add any other keys MainSDK reads with vercel env add, per environment, and refer to them in main.yaml as secret:NAME through secrets: { driver: env }.

How each Vercel driver authenticates to its service is not defined yet.

Configure

Runtime Cache for kv:

kv:
  driver: vercel-runtime-cache

Queues for jobs:

jobs:
  driver: vercel-queues
  dead-letter: true
idempotency: { store: db, ttl: 24h }

Global Config for config:

config:
  driver: vercel-global-config
  schema: ./config.schema.json

Flags for flags:

flags:
  driver: vercel-flags

Connection keys for each service (store id, project, SDK key) are not decided yet; when they are, they go in as secret: references.

Use it

Cache a slow lookup in Runtime Cache:

import { cache } from "mainsdk";

export async function pricesFor(market: string) {
  return cache.wrap(`prices:${market}`, () => loadPrices(market), { ttl: "5m", tags: ["prices"] });
}

Run a job on Vercel Queues:

import { auth, jobs } from "mainsdk";

export async function POST(req: Request) {
  const session = await auth.require(req);
  const { month } = await req.json();
  await jobs.run(
    "reports.export",
    { userId: session.user.id, month },
    { idempotencyKey: `export:${session.user.id}:${month}`, retries: 3, backoff: "exponential" },
  );
  return new Response(null, { status: 202 });
}

Read a setting from Global Config:

import { auth, config } from "mainsdk";

export async function POST(req: Request) {
  await auth.require(req);
  const { items } = await req.json();
  const max = config.get("cart.maxItems");   // typed from config.schema.json
  return items.length > max
    ? Response.json({ error: `Keep the cart to ${max} items` }, { status: 422 })
    : Response.json({ ok: true });
}

Check a flag in Vercel Flags:

import { auth, flags } from "mainsdk";

export async function GET(req: Request) {
  const session = await auth.require(req);
  const useNew = await flags.enabled("new-checkout", { for: session.user });
  return Response.json({ checkout: useNew ? "new" : "classic" });
}

Local development and testing

• No Vercel services: keep local drivers in main.env.dev.yaml: config: { driver: files } and the in-process local queue for jobs (its driver id is not decided yet). mainsdk check --env prod refuses local drivers in production.
• Tests: createTestApp() from @mainsdk/testing runs kv, jobs, config and flags on in-memory fakes, so tests reach no Vercel service. chaos.on("config", { outage: true }) proves settings keep their last good value; chaos.on("jobs", { outage: true }) and chaos.on("kv", { outage: true }) drill the other services.
• Preview deployments: each Vercel environment has its own variables, so previews can use their own Global Config store and flag values.

What MainSDK adds on top

• kv: keys scoped per tenant and a TTL on every entry.
• jobs: a CloudEvents envelope, retries with backoff, a dead-letter queue, and MainSDK's own idempotency record, so a duplicate key never runs the side effect twice.
• config: settings typed against a schema; a bad value is rejected with MAIN-CONFIG-0020 and the last good one kept, and every change is audited.
• flags: flags and targeting stay in Vercel Flags; your code asks one question.

See Key-value store and cache, Events and background jobs, Runtime settings and Feature flags.

Limits and notes

• Runtime Cache is ephemeral and kept per region: an entry written in one region is not read in another, and entries can be dropped before their TTL. Use it as a cache, never as the only copy.
• vercel-queues comes with the webhooks-jobs spec and vercel-global-config with the config-secrets spec (both phase 1). vercel-runtime-cache and vercel-flags are planned phase 1 drivers whose interfaces have no spec yet.
• Delivery on Queues is at least once; MainSDK makes the effects idempotent. Exactly-once delivery is not promised.
• Pick your Vercel function regions to match your data. MainSDK regions are US, EU and India; see Data and regions.
• On Vercel, the platform's OIDC token can stand in for the MainSDK Cloud ingest key when you send telemetry (phase 2); see Deploy on Vercel.
• config.raw() returns the provider's client for features config does not wrap; every use is logged and listed by mainsdk check.

Swap to or from it

Each interface swaps on its own line:

jobs:
  driver: inngest   # was vercel-queues

FAQ

Do I have to use these drivers to deploy on Vercel? No. Any driver works on Vercel; these four just keep the services inside your Vercel project.

Global Config or Vercel Flags? Use Global Config through config for typed values that apply to the whole app, and Vercel Flags through flags to turn features on per user or market.

Does Runtime Cache replace a database? No. It is an ephemeral cache. Keep records in db, for example on Neon.

Next

• Deploy on Vercel
• Key-value store and cache, Events and background jobs, Runtime settings and Feature flags
• Neon, Upstash, Inngest and OpenFeature
• Swap a driver

Open questions