Vercel Skew Protection support - best practices?

[glekner]

I noticed TanStack Start isn't on the supported frameworks list. We're getting a noticeable amount of Sentry events from users hitting broken pages after a deploy.

has anyone found a good way to handle this with TanStack Start?
I know you can manually attach ⁠VERCEL_DEPLOYMENT_ID to requests, but wondering if there's a pattern the community has settled on

[MukundaKatta]

TanStack Start isn't yet on the skew-protection official list, but you can roll the pattern yourself in about 20 lines — Vercel's skew protection really only needs two things: the deployment ID on the request, and a detection/recovery for "I hit a stale deployment" responses.

Here's the pattern I've been using in a couple of production Start apps. It's framework-agnostic enough that you could lift it into any SSR Start app.

1. Expose VERCEL_DEPLOYMENT_ID to the client

Vercel exposes VERCEL_DEPLOYMENT_ID at build time. Make it available to the client bundle and to the server runtime:

// app.config.ts (or vite.config.ts depending on your Start version)
import { defineConfig } from '@tanstack/react-start/config'

export default defineConfig({
  vite: {
    define: {
      'import.meta.env.VERCEL_DEPLOYMENT_ID': JSON.stringify(process.env.VERCEL_DEPLOYMENT_ID ?? ''),
    },
  },
})

Now import.meta.env.VERCEL_DEPLOYMENT_ID is baked into the bundle, carrying the deployment that built the JS running in the user's browser. That's the version you need to route to on subsequent requests.

2. Attach it to every request — server fns, loaders, and data fetches

// src/lib/fetch.ts
export const clientFetch: typeof fetch = (input, init = {}) => {
  const headers = new Headers(init.headers)
  const id = import.meta.env.VERCEL_DEPLOYMENT_ID
  if (id) headers.set('x-deployment-id', id)
  return fetch(input, { ...init, headers })
}

Wire it into the places that actually talk to your server:

// src/router.tsx
import { createRouter } from '@tanstack/react-router'
import { clientFetch } from './lib/fetch'

export const router = createRouter({
  // tanstack-query integration if you use it:
  defaultPreloadStaleTime: 0,
  context: { queryClient },
  fetch: clientFetch,
})

And for useServerFn: Start's createServerFn uses the same fetch under the hood when it's called from the browser, so setting the global fetch or passing clientFetch explicitly is what carries the header into every server-fn call. If you have a direct fetch(/*...*/) somewhere bypassing this, that's a skew-protection hole.

3. Detect the "this build is stale" response and recover

Vercel returns the target deployment's response when it routes correctly. But if the client sends an ID for a deployment that's already been rotated out (past skew window), you get an error. The pattern to recover:

// src/lib/skew-guard.ts
export async function withSkewGuard<T>(fn: () => Promise<T>): Promise<T> {
  try {
    return await fn()
  } catch (err: any) {
    if (err?.status === 404 || err?.code === 'DEPLOYMENT_NOT_FOUND') {
      // This deployment is gone. Reload the page so the user picks up the current one.
      window.location.reload()
      // Throw anyway so callers don't get a T.
      throw err
    }
    throw err
  }
}

Use it as the top-level wrapper in router onError:

const router = createRouter({
  // ...
  defaultErrorComponent: ({ error }) => {
    if (error?.status === 404 && error?.message?.includes('deployment')) {
      // Schedule a reload on next tick to avoid loops.
      setTimeout(() => window.location.reload(), 100)
      return <div>Updating app…</div>
    }
    return <DefaultError error={error} />
  },
})

4. Turn on Vercel skew protection for the project

In the Vercel dashboard: Settings → Skew Protection → Enabled. This tells the edge to route x-deployment-id–tagged requests to the matching deployment for up to the configured window (default 1h, configurable to 12h on Pro/Ent).

Without step 4, step 2 does nothing — the header is ignored. Without steps 2–3, step 4 does nothing — no request carries an ID to route on.

What I'd watch for

• Third-party SDKs bypassing clientFetch. Anything that makes its own fetch() (Sentry, PostHog, Segment) won't have the header. Usually fine — those calls hit third parties, not your own API — but it's worth auditing.
• Streaming / WebSocket connections. Skew protection works for HTTP requests. Long-lived connections established before the deploy don't get migrated; they'll either keep hitting the old deployment (until it gets GC'd) or close and reconnect to the new one. Your code should already handle reconnection.
• Service worker caches. If you have a SW caching JS chunks, the SW may serve chunks from the old deployment after the deploy — that's the "hard-refresh to get new UI" problem skew protection is specifically for. Make sure the SW is respecting the bundle's new hashed URLs.

Is the community settled on a pattern?

From what I've seen across TanStack Start apps that deploy to Vercel, the pattern above (baked-in VERCEL_DEPLOYMENT_ID + header on every fetch + reload-on-stale) is what's emerged. There isn't an official plugin yet — @tannerlinsley's team has rightly kept Start vendor-agnostic — so the cleanest move is to wrap the 20 lines above in a @your-app/vercel-skew local module and use it explicitly.

A public @tanstack/start-skew-vercel package would be genuinely useful; worth asking about in an issue if you want it to exist. The primitives Start already exposes (router-level fetch, per-request-context server fns) are enough to implement it in userland.