Create FasterCreate Faster

Cloudflare Workers (static)

Deploy a Next.js static export or a prerendered TanStack Start site to Cloudflare Workers static assets — no server runtime, no OpenNext.

Supported frameworks
Dependencies

→ Static assets on Workers

What create-faster adds

Cloudflare Workers (static) is a project-level deployment platform for Next.js and TanStack Start apps. Each app is built as a static site and served as Workers static assets — no server runtime, no OpenNext adapter, no Worker script. Selecting it with --deployment cloudflare-static configures every Next.js and TanStack Start app, according to its stack.

Because a static site has no server runtime, this option is mutually exclusive with server-dependent libraries: better-auth, trpc and posthog are rejected, and the project must contain at least one Next.js or TanStack Start app. Other apps of a Turborepo (Hono, Expo) are not configured for static hosting.

Next.js apps

A Next.js app builds a static export (output: 'export') and serves the generated out/ directory.

next.config.ts

The Next.js config emits a static export and disables the Image Optimization API (which requires a server):

next.config.ts
const nextConfig: NextConfig = {
  reactStrictMode: true,

  output: 'export',
  images: {
    unoptimized: true,
  },
  // ...
};

wrangler.jsonc

An assets-only Worker: it points assets.directory at the static export output and declares no main (there is no Worker script). This is Workers static assets, not Cloudflare Pages — there is no pages_build_output_dir. not_found_handling: "404-page" serves the export's pre-rendered out/404.html for unmatched paths instead of a blank body.

wrangler.jsonc
{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "my-site",
  "compatibility_date": "2026-06-12",
  "assets": {
    "directory": "out",
    "not_found_handling": "404-page"
  }
}

Scripts:

  • deploy - Build the static export, then deploy it (next build && wrangler deploy)
  • preview - Serve the build locally on the Workers runtime (wrangler dev)
  • cf-typegen - Generate binding types (wrangler types --env-interface CloudflareEnv cloudflare-env.d.ts)

The start script is not generated: next start rejects output: export.

TanStack Start apps

A TanStack Start app is fully prerendered by Start itself, without Nitro and without @cloudflare/vite-plugin (the Cloudflare plugin builds a Worker, which is the opposite of a static deploy). vite build renders every static route and every page reachable through a link, and writes flat HTML files into dist/client/.

vite.config.ts
tanstackStart({ prerender: { enabled: true, crawlLinks: true, autoSubfolderIndex: false } }),

autoSubfolderIndex: false writes about.html instead of about/index.html, so Workers serves /about directly instead of redirecting to /about/.

wrangler.jsonc
{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "my-site",
  "compatibility_date": "2026-06-12",
  "assets": {
    "directory": "dist/client",
    "not_found_handling": "404-page"
  }
}

Scripts:

  • build - Build and prerender into dist/client (vite build)
  • deploy - Build, then deploy the assets (vite build && wrangler deploy)
  • preview - Serve the build locally on the Workers runtime (wrangler dev)
  • cf-typegen - Generate binding types (wrangler types --env-interface CloudflareEnv cloudflare-env.d.ts)

The nitro dependency, the start script and .env.start are not generated.

404 page

Start cannot prerender a not-found response, because its prerenderer fails on any non-2xx status. The app therefore gets a catch-all route (src/routes/$.tsx) that renders the NotFound component (src/components/not-found.tsx), and vite.config.ts lists /404 in pages so the prerenderer writes it to 404.html. Workers serves that file with status 404 for unknown URLs.

The browser hydrates 404.html at the real URL, so the router must match the same route on both sides. A dedicated /404 route would not: the server tree would hold that route while the client matches nothing, and React would log hydration error #418. The catch-all route matches /404 while prerendering and any unknown URL in the browser. The same NotFound component stays the root notFoundComponent, which renders when a loader throws notFound(). /404 is also reachable directly, with status 200. In vite dev the catch-all route is a real route, so an unknown URL answers 200 with the not-found page; only the deployed static output answers 404.

Only linked pages are generated

The prerenderer discovers static routes automatically and follows every same-origin <a href> it finds, so a dynamic page such as /posts/1 is generated when a prerendered page links to it. A dynamic page that nothing links to is not generated and answers 404. List such pages explicitly with the pages option, next to the generated /404 entry:

vite.config.ts
tanstackStart({
  pages: [{ path: '/404' }, { path: '/posts/2' }, { path: '/posts/3' }],
  prerender: { enabled: true, crawlLinks: true, autoSubfolderIndex: false },
}),

What stops working

There is no server at request time. Unlike Next.js output: 'export', Start does not reject server code at build time, and vite dev runs a real SSR server where all of it works: it only breaks after the static build.

  • Server routes (server.handlers) are not prerendered and answer 404.
  • Server functions (createServerFn) answer 404 and throw Invariant failed.
  • A route whose loader calls a server function works on a direct page load (the build-time value is embedded in the HTML) but fails on client-side navigation, where the loader runs again in the browser.
  • Request and server-function middleware only run during the build-time prerender.
  • Cloudflare bindings and secrets are not available: no Worker exists.
  • evlog builds but is inert, as on Next.js.

Keep loaders to plain client-safe code (or data fetched from an external API) in a static app. SPA mode (spa.enabled) is not offered: it turns every unmatched URL, including /api/* and /_serverFn/*, into a 200 response with the HTML shell, so failing server calls go unnoticed.

Shared behavior

The Worker name is the project name in single mode and <project>-<app> in turborepo mode, so two projects deployed to one Cloudflare account never share a Worker.

Omitted files:

  • The Next.js request interceptor (proxy.ts / middleware.ts) is not generated — a static export has no server to run it.
  • For TanStack Start apps, .env.start and evlog's nitro.config.ts are not generated — the build has no Nitro server.

Modified files:

  • .gitignore - Ignores .wrangler/ and cloudflare-env.d.ts. The build outputs out/ (Next.js) and dist/ (TanStack Start) are already ignored.

Turborepo mode: wrangler.jsonc is placed in apps/<name>/ and the Worker is named <project>-<app>. Run the scripts from the app directory.

On this page