TanStack Start on Cloudflare Workers

@decocms/tanstack is the binding that runs a Deco Blocks site on TanStack Start and deploys it to Cloudflare Workers. This page is the reference for it: what each file in your project does, every option of the Worker wrapper, the route factories, the layout components, the router, and the Vite plugin. If you haven't built a page yet, start with the TanStack quickstart and come back here when you need to change a default.

A binding is the package that connects the framework-neutral runtime (@decocms/blocks) to one app framework. The TanStack binding is the more complete of the two: it also owns the edge cache, Fast Deploy and the page-as-JSON endpoints, none of which exist on Next.js.

The files a site owns

A TanStack site wires the binding through a handful of files. The migration scaffold and the quickstart both produce this layout.

Load setup first

src/setup.ts fills module-level registries: the decofile, the section registry, matchers and the schema loader. TanStack Start splits server functions into separate modules, and any of them can run before your route files are imported. So the setup module must be the first import of both server entry points.

import "./setup";
import { createStartHandler, defaultStreamHandler } from "@tanstack/react-start/server";
 
export default createStartHandler(defaultStreamHandler);

The Worker entry

createDecoWorkerEntry(serverEntry, options) takes TanStack Start's server entry and returns a Worker handler { fetch(request, env, ctx) }. Every request goes through it before TanStack sees it. It answers the admin protocol, applies CMS redirects, serves ?renderJson, runs your proxy, caches responses at the edge, adds security headers and records telemetry. The Worker request pipeline walks through the order step by step.

import "./setup";
import handler, { createServerEntry } from "@tanstack/react-start/server-entry";
import { createDecoWorkerEntry } from "@decocms/tanstack";
import { detectDevice } from "@decocms/blocks/sdk/detectDevice";
import {
  corsHeaders,
  handleDecofileRead,
  handleDecofileReload,
  handleMeta,
  handleRender,
} from "@decocms/blocks-admin";
 
const serverEntry = createServerEntry({ fetch: handler.fetch });
 
export default createDecoWorkerEntry(serverEntry, {
  admin: { handleMeta, handleDecofileRead, handleDecofileReload, handleRender, corsHeaders },
  buildSegment: (request) => ({
    device: detectDevice(request.headers.get("user-agent") ?? ""),
  }),
  renderJson: false,
  asJson: false,
});

The options type isn't exported from the package, so the tables below spell out each option's shape. Everything is optional.

Admin

Caching

These options shape the edge cache. Caching explains profiles, headers and purging in depth.

Segments

A segment is the set of request properties that change what a page looks like, such as device, logged-in state or sales channel. The Worker keys its cache on the segment so different audiences never share an entry.

Without buildSegment, the Worker logs a warning at boot: it can't tell logged-in visitors apart, so they would share the anonymous cache entry. Commerce apps ship a helper for this. With VTEX, for example, extractVtexContext from @decocms/apps-vtex/middleware reads the login and sales-channel cookies (see VTEX).

Only add dimensions you actually use. A regionId on a site without regional pricing multiplies every page into one copy per region for nothing. Location-based keying is handled by geoCacheKey below.

Geo

Security

Page JSON

The migration scaffold sets renderJson and asJson to false; turn them on when a client actually needs them.

Proxy

import { createVtexCheckoutProxy, shouldProxyToVtex } from "@decocms/apps-vtex/utils/proxy";
 
const proxyCheckout = createVtexCheckoutProxy({
  account: "acme",
  checkoutOrigin: "secure.store.example.com",
});
 
export default createDecoWorkerEntry(serverEntry, {
  // ...admin, buildSegment
  proxyHandler: (request, url) =>
    shouldProxyToVtex(url.pathname) ? proxyCheckout(request, url) : null,
});

Speculation rules

Observability and outbound requests

Routes

The CMS routes

cmsRouteConfig(options) and cmsHomeRouteConfig(options) return TanStack route options to spread into createFileRoute("/$") and createFileRoute("/"). They supply the loader (which resolves the page on the server), search-param handling, cache headers, the <head> (title, description, robots, Open Graph, canonical, JSON-LD) and an error boundary. They don't supply component or notFoundComponent: those are yours.

import { createFileRoute } from "@tanstack/react-router";
import { cmsRouteConfig, DecoPageRenderer, NotFoundPage } from "@decocms/tanstack";
import { deferredSectionLoader } from "@decocms/tanstack/sdk/deferredSectionLoader";
 
export const Route = createFileRoute("/$")({
  ...cmsRouteConfig({
    siteName: "My Store",
    defaultTitle: "My Store",
    defaultDescription: "Everything for your home.",
  }),
  component: CmsPageRoute,
  notFoundComponent: NotFoundPage,
});
 
function CmsPageRoute() {
  const data = Route.useLoaderData();
  if (!data) return <NotFoundPage />;
  return (
    <DecoPageRenderer
      sections={data.resolvedSections ?? []}
      deferredSections={data.deferredSections ?? []}
      pagePath={data.pagePath}
      pageUrl={data.pageUrl}
      device={data.device}
      loadDeferredSectionFn={deferredSectionLoader}
    />
  );
}

The home route is the same with cmsHomeRouteConfig. Its options are the same as below minus ignoreSearchParams and ssr, and siteName is optional there (it defaults to defaultTitle).

The built-in error page and the label of NavigationProgress are in Portuguese. To use your own text, pass errorComponent:

function PageError({ reset }: { error: Error; reset: () => void }) {
  return (
    <div role="alert">
      <p>Something went wrong loading this page.</p>
      <button type="button" onClick={reset}>Try again</button>
    </div>
  );
}
 
export const Route = createFileRoute("/$")({
  ...cmsRouteConfig({
    siteName: "My Store",
    defaultTitle: "My Store",
    errorComponent: PageError,
  }),
  component: CmsPageRoute,
  notFoundComponent: NotFoundPage,
});

The loader returns null when no page block matches the path. Otherwise it returns the resolved page: resolvedSections, deferredSections, pagePath, pageUrl, device, seo, cacheProfile and a few more. CmsPage and NotFoundPage are exported as ready-made components, but CmsPage doesn't wire loadDeferredSectionFn, so render DecoPageRenderer yourself as above.

Admin routes

Studio also calls three paths that TanStack serves as file routes. Build them with the factories; each call returns a fresh options object.

import { createFileRoute } from "@tanstack/react-router";
import { decoMetaRouteConfig } from "@decocms/tanstack";
 
export const Route = createFileRoute("/deco/meta")(decoMetaRouteConfig());

import { createFileRoute } from "@tanstack/react-router";
import { decoInvokeRouteConfig } from "@decocms/tanstack";
 
export const Route = createFileRoute("/deco/invoke/$")(decoInvokeRouteConfig());

import { createFileRoute } from "@tanstack/react-router";
import { decoRenderRouteConfig } from "@decocms/tanstack";
 
export const Route = createFileRoute("/deco/render")(decoRenderRouteConfig());

withSiteGlobals is still exported but does nothing. Site globals are resolved inside the CMS route loaders.

Layout and rendering components

DecoRootLayout

DecoRootLayout renders the whole HTML document: <html>, <head> with TanStack's head content, and <body> with the event bootstrap, the analytics collector, a navigation progress bar, the route outlet, the draft-preview badge, Studio's live controls and TanStack's scripts. It already renders the outlet, so don't pass <Outlet /> as a child.

import { createRootRoute } from "@tanstack/react-router";
import { DecoRootLayout } from "@decocms/tanstack";
import appCss from "../styles/app.css?url";
 
export const Route = createRootRoute({
  head: () => ({
    meta: [{ charSet: "utf-8" }, { name: "viewport", content: "width=device-width, initial-scale=1" }],
    links: [{ rel: "stylesheet", href: appCss }],
  }),
  component: () => <DecoRootLayout siteName="my-store" lang="en" />,
});

DecoPageRenderer

DecoPageRenderer renders a page's sections in order. Eager sections render immediately. Deferred sections render a skeleton first (the section's own LoadingFallback, or the loadingFallback prop), then load when they come within 300px of the viewport.

The package also exports SectionRenderer and SectionList for rendering sections outside a page, NavigationProgress (a top progress bar with an optional color), StableOutlet, DraftPreviewIndicator and PreviewProviders (router and query providers for preview renders, meant for createAdminSetup({ previewWrapper })).

The router

createDecoRouter(options) wraps TanStack's createRouter with defaults that suit storefronts. Search params are parsed and written with URLSearchParams, so a repeated key such as ?filter.brand=Nike&filter.brand=Acme becomes an array instead of a JSON string. Create the QueryClient inside getRouter():

import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { createDecoRouter } from "@decocms/tanstack";
import { routeTree } from "./routeTree.gen";
import "./setup";
 
export function getRouter() {
  const queryClient = new QueryClient();
  return createDecoRouter({
    routeTree,
    context: { queryClient },
    Wrap: ({ children }) => <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>,
  });
}
 
declare module "@tanstack/react-router" {
  interface Register {
    router: ReturnType<typeof getRouter>;
  }
}

decoParseSearch and decoStringifySearch are the two serializers, exported for use elsewhere.

The Vite plugin

decoVitePlugin() from @decocms/tanstack/vite must be in your Vite config. The module is plain JavaScript without type declarations, so TypeScript configs need a // @ts-expect-error on the import.

import { cloudflare } from "@cloudflare/vite-plugin";
import { tanstackStart } from "@tanstack/react-start/plugin/vite";
import react from "@vitejs/plugin-react";
import { defineConfig } from "vite";
// @ts-expect-error -- plain JS module without type declarations
import { decoVitePlugin } from "@decocms/tanstack/vite";
 
export default defineConfig({
  plugins: [
    cloudflare({ viteEnvironment: { name: "ssr" } }),
    tanstackStart({ server: { entry: "server" } }),
    react(),
    decoVitePlugin(),
  ],
  define: {
    "process.env.DECO_SITE_NAME": JSON.stringify(process.env.DECO_SITE_NAME || "my-store"),
  },
  resolve: {
    dedupe: ["@decocms/blocks", "@decocms/blocks-admin", "@decocms/tanstack", "react", "react-dom"],
  },
});

What the plugin does:

• Keeps server code out of the browser. In the client build it replaces react-dom/server, node:async_hooks, the schema (meta.gen.json), the decofile (blocks.gen.ts) and the generated loader map (loaders.gen.ts) with empty stubs, so content, schema and loader source never ship to the browser.
• Loads content on the server. In the server build, .deco/blocks.gen.ts becomes a JSON.parse of its .json sibling.
• Stamps a build hash. It defines __DECO_BUILD_HASH__ from the CI commit or git rev-parse, which the Worker uses to version its cache when BUILD_HASH isn't set.
• Regenerates in development. It watches .deco/blocks/*.json and applies edits live, regenerates .deco/meta.gen.json when files under src/ change, and runs generate for sections, loaders and invoke on start and on changes. If blocks.gen.json or meta.gen.json is missing on a fresh clone, it generates them before the first request.
• Provides a default start entry. If you have no src/start.ts, it uses one that wires decoServerFnFetch (next section).
• Splits vendor chunks for React, the router and React Query in production builds. It deliberately leaves @decocms/* packages unsplit: they import each other in a cycle, and splitting them gives a chunk load order that crashes at runtime. If you customize build.rollupOptions.output.manualChunks, don't give these packages their own chunks.

decoVitePlugin({ fastDeploy }) takes one option. fastDeploy: "auto" (the default) removes the bundled decofile from the server bundle only when the build sets DECO_SEEDED_DEPLOY. true forces that, and false never does it. Without the bundled copy there is no fallback if Fast Deploy can't read KV, so leave it on "auto" unless your pipeline seeds KV before every deploy. See Deploying and Fast Deploy.

React Compiler

This isn't done by the plugin: the migrator's vite.config.ts also turns on the React Compiler with react({ babel: { plugins: [["babel-plugin-react-compiler", { target: "19" }]] } }) and babel-plugin-react-compiler as a dev dependency. It's optional for new sites.

Server function fetch

TanStack Start calls server functions (such as the deferred-section loader) over /_serverFn. decoServerFnFetch is a fetch that adds a cache-segment marker to those calls, so the CDN can cache them safely. The Vite plugin wires it automatically unless your site has its own src/start.ts. If it does, add it there:

import { createStart } from "@tanstack/react-start";
import { decoServerFnFetch } from "@decocms/tanstack/sdk/serverFnFetch";
 
export const startInstance = createStart(() => ({
  serverFns: { fetch: decoServerFnFetch },
}));

Import it from its subpath, not the package root: src/start.ts is part of the client bundle.

Cookie passthrough

@decocms/tanstack/sdk/cookiePassthrough bridges cookies between the browser and an upstream API inside a server function:

• getRequestCookieHeader() returns the incoming Cookie header, or undefined outside a request.
• forwardResponseCookies(cookies: string[]) appends Set-Cookie headers to the current response, keeping any already set. Outside a request it does nothing.

You don't need them for the VTEX actions: the invoke file that generate writes carries its own cookie bridge, so those actions already pass the platform's Set-Cookie headers to the browser. Use the helpers in your own server functions that talk to a cookie-based API.

wrangler.jsonc

{
  "name": "my-store",
  "main": "src/worker-entry.ts",
  "compatibility_date": "2025-05-01",
  "compatibility_flags": ["nodejs_compat", "no_handle_cross_request_promise_resolution"],
  "version_metadata": { "binding": "CF_VERSION_METADATA" },
  "vars": {
    "DECO_SITE_NAME": "my-store",
    "DECO_ENV_NAME": "production"
  }
}

• main must be your worker entry, not TanStack's server entry.
• nodejs_compat is required: request context uses AsyncLocalStorage.
• no_handle_cross_request_promise_resolution is required: the framework's caches share in-flight promises between requests, and without the flag the Worker hangs.
• version_metadata lets telemetry report which deploy served a request.
• For Fast Deploy, add a DECO_KV binding and "DECO_FAST_DEPLOY": "1", and call setupTanstackFastDeploy() in src/setup.ts. See Deploying and Fast Deploy.

Pass BUILD_HASH per deploy so each deploy gets a fresh cache namespace:

npx wrangler deploy --var BUILD_HASH:$(git rev-parse --short HEAD)

Related

• Quickstart: TanStack Start builds the files on this page from scratch.
• Caching covers profiles, X-Cache headers and purging.
• The Worker request pipeline shows what createDecoWorkerEntry does with each request.
• Deferred sections explains when sections are deferred.
• Troubleshooting lists symptoms and fixes.