TanStack Start | Workers English

TanStack Start is a full-stack framework for building web applications with server-side rendering, streaming, server functions, and bundling.

Already have a TanStack Start project?

Run wrangler deploy in a project without a Wrangler configuration file and Wrangler will automatically detect TanStack Start, generate the necessary configuration, and deploy your project.

npm

yarn

pnpm

npx wrangler deploy

yarn wrangler deploy

pnpm wrangler deploy

For more information, refer to Automatic project configuration.

Create a new application

Create a TanStack Start application pre-configured for Cloudflare Workers:

npm

yarn

pnpm

npm create cloudflare@latest -- my-tanstack-start-app --framework=tanstack-start

yarn create cloudflare my-tanstack-start-app --framework=tanstack-start

pnpm create cloudflare@latest my-tanstack-start-app --framework=tanstack-start

Start a local development server to preview your project during development:

npm

yarn

pnpm

npm run dev

yarn run dev

pnpm run dev

Configure an existing application

If you have an existing TanStack Start application, configure it to run on Cloudflare Workers:

Note

Cloudflare does not support TanStack Start projects that use Rsbuild. If your application uses Rsbuild, migrate it to Vite before following these configuration steps.

Install @cloudflare/vite-plugin and wrangler:

npm

yarn

pnpm

bun

npm i -D @cloudflare/vite-plugin wrangler

yarn add -D @cloudflare/vite-plugin wrangler

pnpm add -D @cloudflare/vite-plugin wrangler

bun add -d @cloudflare/vite-plugin wrangler

Add the Cloudflare plugin to your Vite configuration:

If your Vite configuration includes another deployment adapter, such as nitro(), remove the adapter and its import before adding the Cloudflare Vite plugin.

JavaScript

TypeScript

vite.config.js

import { defineConfig } from "vite";
import { tanstackStart } from "@tanstack/react-start/plugin/vite";
import { cloudflare } from "@cloudflare/vite-plugin";
import react from "@vitejs/plugin-react";

export default defineConfig({
	plugins: [
		cloudflare({ viteEnvironment: { name: "ssr" } }),
		tanstackStart(),
		react(),
	],
});

vite.config.ts

import { defineConfig } from "vite";
import { tanstackStart } from "@tanstack/react-start/plugin/vite";
import { cloudflare } from "@cloudflare/vite-plugin";
import react from "@vitejs/plugin-react";

export default defineConfig({
	plugins: [
		cloudflare({ viteEnvironment: { name: "ssr" } }),
		tanstackStart(),
		react(),
	],
});

Add a wrangler.jsonc configuration file:

wrangler.jsonc

wrangler.toml

{
	"$schema": "node_modules/wrangler/config-schema.json",
	"name": "<YOUR_PROJECT_NAME>",
	// Set this to today's date
	"compatibility_date": "2026-11-02",
	"compatibility_flags": ["nodejs_compat"],
	"main": "@tanstack/react-start/server-entry",
	"observability": {
		"enabled": true,
	},
}

"$schema" = "node_modules/wrangler/config-schema.json"
name = "<YOUR_PROJECT_NAME>"
# Set this to today's date
compatibility_date = "2026-11-02"
compatibility_flags = [ "nodejs_compat" ]
main = "@tanstack/react-start/server-entry"

[observability]
enabled = true

Update the scripts section in package.json:

package.json

{
	"scripts": {
		"dev": "vite dev",
		"build": "vite build",
		"preview": "vite preview",
		"deploy": "npm run build && wrangler deploy",
		"cf-typegen": "wrangler types"
	}
}

Deploy

Deploy to a *.workers.dev subdomain or a custom domain from your machine or any CI/CD system, including Workers Builds.

npm

yarn

pnpm

npm run deploy

yarn run deploy

pnpm run deploy

Note

Preview the build locally before deploying:

npm

yarn

pnpm

npm run preview

yarn run preview

pnpm run preview

Custom entrypoints

TanStack Start uses @tanstack/react-start/server-entry as your default entrypoint. Create a custom server entrypoint to add additional Workers handlers such as Queues and Cron Triggers. This is also where you can add additional exports such as Durable Objects and Workflows.

Note

If you are using TypeScript, generate Workers types before adding a custom entrypoint:

npm

yarn

pnpm

npm run cf-typegen

yarn run cf-typegen

pnpm run cf-typegen

Create a custom server entrypoint file:

JavaScript

TypeScript

src/server.js

import handler from "@tanstack/react-start/server-entry";

// Export Durable Objects as named exports
export { MyDurableObject } from "./my-durable-object";

export default {
	fetch: handler.fetch,

	// Handle Queue messages
	async queue(batch, _env, _ctx) {
		for (const message of batch.messages) {
			console.log("Processing message:", message.body);
			message.ack();
		}
	},

	// Handle Cron Triggers
	async scheduled(event, _env, _ctx) {
		console.log("Cron triggered:", event.cron);
	},
};

src/server.ts

import handler from "@tanstack/react-start/server-entry";

// Export Durable Objects as named exports
export { MyDurableObject } from "./my-durable-object";

export default {
    fetch: handler.fetch,

    // Handle Queue messages
    async queue(batch, _env, _ctx) {
        for (const message of batch.messages) {
            console.log("Processing message:", message.body);
            message.ack();
        }
    },

    // Handle Cron Triggers
    async scheduled(event, _env, _ctx) {
        console.log("Cron triggered:", event.cron);
    },
} satisfies ExportedHandler<Env>;

Update your Wrangler configuration to point to your custom entrypoint:

wrangler.jsonc

wrangler.toml

{
	"main": "src/server.ts",
    "upload_source_maps": true,
}

main = "src/server.ts"
upload_source_maps = true

Test scheduled handlers locally

Test your scheduled handler locally using the /cdn-cgi/local/scheduled endpoint:

curl "http://localhost:3000/cdn-cgi/local/scheduled?cron=*+*+*+*+*"

Export a Workflow class from your custom entrypoint to run durable, multi-step tasks:

JavaScript

TypeScript

src/server.js

import { WorkflowEntrypoint, WorkflowStep } from "cloudflare:workers";

export class MyWorkflow extends WorkflowEntrypoint {
	async run(event, step) {
		const result = await step.do("process data", async () => {
			return `Processed: ${event.payload.input}`;
		});

		await step.sleep("wait", "10 seconds");

		await step.do("finalize", async () => {
			console.log("Workflow complete:", result);
		});
	}
}

src/server.ts

import { WorkflowEntrypoint, WorkflowStep } from "cloudflare:workers";
import type { WorkflowEvent } from "cloudflare:workers";

export class MyWorkflow extends WorkflowEntrypoint<Env> {
	async run(event: WorkflowEvent<{ input: string }>, step: WorkflowStep) {
		const result = await step.do("process data", async () => {
			return `Processed: ${event.payload.input}`;
		});

		await step.sleep("wait", "10 seconds");

		await step.do("finalize", async () => {
			console.log("Workflow complete:", result);
		});
	}
}

Add the Workflow configuration to your Wrangler configuration:

wrangler.jsonc

wrangler.toml

{
	"workflows": [
		{
			"name": "my-workflow",
			"binding": "MY_WORKFLOW",
			"class_name": "MyWorkflow",
		},
	],
}

[[workflows]]
name = "my-workflow"
binding = "MY_WORKFLOW"
class_name = "MyWorkflow"

Add a service binding to call another Worker's RPC methods from your TanStack Start application:

wrangler.jsonc

wrangler.toml

{
	"services": [
		{
			"binding": "AUTH_SERVICE",
			"service": "auth-worker",
		},
	],
}

[[services]]
binding = "AUTH_SERVICE"
service = "auth-worker"

The target Worker must expose RPC methods by extending WorkerEntrypoint. Generate types for both Workers by passing both Wrangler configuration files:

npm

yarn

pnpm

npx wrangler types -c ./wrangler.jsonc -c ../auth-worker/wrangler.jsonc

yarn wrangler types -c ./wrangler.jsonc -c ../auth-worker/wrangler.jsonc

pnpm wrangler types -c ./wrangler.jsonc -c ../auth-worker/wrangler.jsonc

Call the bound Worker's methods from a server function:

JavaScript

TypeScript

src/routes/index.jsx

import { createServerFn } from "@tanstack/react-start";
import { env } from "cloudflare:workers";

const verifyUser = createServerFn()
	.validator((token) => token)
	.handler(async ({ data: token }) => {
		const result = await env.AUTH_SERVICE.verify(token);
		return result;
	});

src/routes/index.tsx

import { createServerFn } from "@tanstack/react-start";
import { env } from "cloudflare:workers";

const verifyUser = createServerFn()
	.validator((token: string) => token)
	.handler(async ({ data: token }) => {
		const result = await env.AUTH_SERVICE.verify(token);
		return result;
	});

Example: Using Workflows

Export a Workflow class from your custom entrypoint to run durable, multi-step tasks:

JavaScript

TypeScript

src/server.js

import { WorkflowEntrypoint, WorkflowStep } from "cloudflare:workers";

export class MyWorkflow extends WorkflowEntrypoint {
	async run(event, step) {
		const result = await step.do("process data", async () => {
			return `Processed: ${event.payload.input}`;
		});

		await step.sleep("wait", "10 seconds");

		await step.do("finalize", async () => {
			console.log("Workflow complete:", result);
		});
	}
}

src/server.ts

import { WorkflowEntrypoint, WorkflowStep } from "cloudflare:workers";
import type { WorkflowEvent } from "cloudflare:workers";

export class MyWorkflow extends WorkflowEntrypoint<Env> {
	async run(event: WorkflowEvent<{ input: string }>, step: WorkflowStep) {
		const result = await step.do("process data", async () => {
			return `Processed: ${event.payload.input}`;
		});

		await step.sleep("wait", "10 seconds");

		await step.do("finalize", async () => {
			console.log("Workflow complete:", result);
		});
	}
}

Add the Workflow configuration to your Wrangler configuration:

wrangler.jsonc

wrangler.toml

{
	"workflows": [
		{
			"name": "my-workflow",
			"binding": "MY_WORKFLOW",
			"class_name": "MyWorkflow",
		},
	],
}

[[workflows]]
name = "my-workflow"
binding = "MY_WORKFLOW"
class_name = "MyWorkflow"

Example: Using Service Bindings

Add a service binding to call another Worker's RPC methods from your TanStack Start application:

wrangler.jsonc

wrangler.toml

{
	"services": [
		{
			"binding": "AUTH_SERVICE",
			"service": "auth-worker",
		},
	],
}

[[services]]
binding = "AUTH_SERVICE"
service = "auth-worker"

The target Worker must expose RPC methods by extending WorkerEntrypoint. Generate types for both Workers by passing both Wrangler configuration files:

npm

yarn

pnpm

npx wrangler types -c ./wrangler.jsonc -c ../auth-worker/wrangler.jsonc

yarn wrangler types -c ./wrangler.jsonc -c ../auth-worker/wrangler.jsonc

pnpm wrangler types -c ./wrangler.jsonc -c ../auth-worker/wrangler.jsonc

Call the bound Worker's methods from a server function:

JavaScript

TypeScript

src/routes/index.jsx

import { createServerFn } from "@tanstack/react-start";
import { env } from "cloudflare:workers";

const verifyUser = createServerFn()
	.validator((token) => token)
	.handler(async ({ data: token }) => {
		const result = await env.AUTH_SERVICE.verify(token);
		return result;
	});

src/routes/index.tsx

import { createServerFn } from "@tanstack/react-start";
import { env } from "cloudflare:workers";

const verifyUser = createServerFn()
	.validator((token: string) => token)
	.handler(async ({ data: token }) => {
		const result = await env.AUTH_SERVICE.verify(token);
		return result;
	});

Bindings

Your TanStack Start application can be fully integrated with the Cloudflare Developer Platform, in both local development and in production, by using bindings.

Access bindings by importing the env object in your server-side code:

JavaScript

TypeScript

src/routes/index.jsx

import { createFileRoute } from "@tanstack/react-router";
import { createServerFn } from "@tanstack/react-start";
import { env } from "cloudflare:workers";

export const Route = createFileRoute("/")({
	loader: () => getData(),
	component: RouteComponent,
});

const getData = createServerFn().handler(() => {
	// Access bindings via env
	// For example: env.MY_KV, env.MY_BUCKET, or env.AI
});

function RouteComponent() {
	// ...
}

src/routes/index.tsx

import { createFileRoute } from "@tanstack/react-router";
import { createServerFn } from "@tanstack/react-start";
import { env } from "cloudflare:workers";

export const Route = createFileRoute("/")({
	loader: () => getData(),
	component: RouteComponent,
});

const getData = createServerFn().handler(() => {
	// Access bindings via env
	// For example: env.MY_KV, env.MY_BUCKET, or env.AI
});

function RouteComponent() {
	// ...
}

Generate TypeScript types for your bindings based on your Wrangler configuration:

npm

yarn

pnpm

npm run cf-typegen

yarn run cf-typegen

pnpm run cf-typegen

With bindings, your application can be fully integrated with the Cloudflare Developer Platform, giving you access to compute, storage, AI and more.

Use R2 in a server function

Add an R2 bucket binding to your Wrangler configuration:

wrangler.jsonc

wrangler.toml

{
	"r2_buckets": [
		{
			"binding": "MY_BUCKET",
			"bucket_name": "<YOUR_BUCKET_NAME>",
		},
	],
}

[[r2_buckets]]
binding = "MY_BUCKET"
bucket_name = "<YOUR_BUCKET_NAME>"

Access the bucket in a server function:

JavaScript

TypeScript

src/routes/index.js

import { createServerFn } from "@tanstack/react-start";
import { env } from "cloudflare:workers";

const uploadFile = createServerFn({ method: "POST" })
	.validator((data) => data)
	.handler(async ({ data }) => {
		await env.MY_BUCKET.put(data.key, data.content);
		return { success: true };
	});

const getFile = createServerFn()
	.validator((key) => key)
	.handler(async ({ data: key }) => {
		const object = await env.MY_BUCKET.get(key);
		return object ? await object.text() : null;
	});

src/routes/index.ts

import { createServerFn } from "@tanstack/react-start";
import { env } from "cloudflare:workers";

const uploadFile = createServerFn({ method: "POST" })
	.validator((data: { key: string; content: string }) => data)
	.handler(async ({ data }) => {
		await env.MY_BUCKET.put(data.key, data.content);
		return { success: true };
	});

const getFile = createServerFn()
	.validator((key: string) => key)
	.handler(async ({ data: key }) => {
		const object = await env.MY_BUCKET.get(key);
		return object ? await object.text() : null;
	});

Static prerendering

Prerender your application to static HTML at build time and serve as static assets.

JavaScript

TypeScript

vite.config.js

import { defineConfig } from "vite";
import { cloudflare } from "@cloudflare/vite-plugin";
import { tanstackStart } from "@tanstack/react-start/plugin/vite";
import react from "@vitejs/plugin-react";

export default defineConfig({
	plugins: [
		cloudflare({ viteEnvironment: { name: "ssr" } }),
		tanstackStart({
			prerender: {
				enabled: true,
			},
		}),
		react(),
	],
});

vite.config.ts

import { defineConfig } from "vite";
import { cloudflare } from "@cloudflare/vite-plugin";
import { tanstackStart } from "@tanstack/react-start/plugin/vite";
import react from "@vitejs/plugin-react";

export default defineConfig({
	plugins: [
		cloudflare({ viteEnvironment: { name: "ssr" } }),
		tanstackStart({
			prerender: {
				enabled: true,
			},
		}),
		react(),
	],
});

For more options, refer to TanStack Start static prerendering.

Prerendering data sources

Caution

Prerendering runs at build time. It uses your local environment variables, secrets, and bindings storage data.

To prerender with production data, use remote bindings.

In CI environments, environment variables or secrets may not be available during the build. To make them accessible:

Set CLOUDFLARE_INCLUDE_PROCESS_ENV=true in your CI environment and provide the required values as environment variables.
If using Workers Builds, update your build settings.