跳转到内容
搜索文档
↵选择
↑↓导航
ESC关闭

TanStack Start

最后更新 查看 MarkdownAgent 设置

TanStack Start ↗ 是一个全栈框架，用于构建具有服务端渲染、流式传输、服务端函数和打包功能的 Web 应用。

TanStack StartDetected
Generated configuration
wrangler.jsonc
main:.output/server/index.mjs
wrangler.jsonc
assets:directory: .output/public
wrangler.jsonc
compatibility_flags:nodejs_compat
wrangler.jsonc
observability:enabled: true
WorkersDeployed
Wrangler handles configuration automatically

创建新应用

创建预配置用于 Cloudflare Workers 的 TanStack Start 应用：

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

启动本地开发服务器，在开发期间预览项目：

npm run dev

配置现有应用

如果你已有 TanStack Start 应用，将其配置为在 Cloudflare Workers 上运行：

  1. 安装 @cloudflare/vite-plugin 和 wrangler：

    npm i @cloudflare/vite-plugin wrangler -- -D

  2. 将 Cloudflare 插件添加到你的 Vite 配置：

    vite.config.jsjs
    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.tsts
    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(),
	],
});

  3. 添加 wrangler.jsonc 配置文件：

    {
	"$schema": "node_modules/wrangler/config-schema.json",
	"name": "<YOUR_PROJECT_NAME>",
	// Set this to today's date
	"compatibility_date": "2026-08-17",
	"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-08-17"
compatibility_flags = [ "nodejs_compat" ]
main = "@tanstack/react-start/server-entry"

[observability]
enabled = true

  4. 更新 package.json 中的 scripts 部分：

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

部署

从本地机器或任何 CI/CD 系统（包括 Workers Builds）部署到 *.workers.dev 子域或自定义域名。

npm run deploy

自定义入口点

TanStack Start 使用 @tanstack/react-start/server-entry 作为默认入口点。创建自定义服务端入口点以添加额外的 Worker 处理器，例如 Queues 和 Cron Triggers。你也可以在此添加额外的导出，例如 Durable Objects 和 Workflows。

  1. 创建自定义服务端入口点文件：

    src/server.jsjs
    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.tsts
    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);
	},
};

  2. 更新 Wrangler 配置以指向自定义入口点：

    {
	"main": "src/server.ts",
}
    main = "src/server.ts"

在本地测试 scheduled 处理器

使用 /cdn-cgi/handler/scheduled 端点在本地测试 scheduled 处理器：

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

示例：使用 Workflows

从自定义入口点导出 Workflow 类以运行持久、多步骤任务：

app/server.jsjs
import {
	WorkflowEntrypoint,
	WorkflowStep,
	WorkflowEvent,
} 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);
		});
	}
}
app/server.tsts
import {
	WorkflowEntrypoint,
	WorkflowStep,
	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);
		});
	}
}

将 Workflow 配置添加到 Wrangler 配置：

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

示例：使用 Service Bindings

添加 service binding 以从 TanStack Start 应用调用另一个 Worker 的 RPC 方法：

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

从服务端函数调用绑定 Worker 的方法：

app/routes/index.jsxjs
import { createServerFn } from "@tanstack/react-start";
import { env } from "cloudflare:workers";

const verifyUser = createServerFn()
	.inputValidator((token) => token)
	.handler(async ({ data: token }) => {
		const result = await env.AUTH_SERVICE.verify(token);
		return result;
	});
app/routes/index.tsxts
import { createServerFn } from "@tanstack/react-start";
import { env } from "cloudflare:workers";

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

绑定（binding）

你的 TanStack Start 应用可以通过绑定（binding）在本地开发和生产环境中与 Cloudflare Developer Platform 完全集成。

通过在服务端代码中导入 env 对象访问绑定（binding）：

app/routes/index.jsxjs
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, env.AI, etc.
});

function RouteComponent() {
	// ...
}
app/routes/index.tsxts
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, env.AI, etc.
});

function RouteComponent() {
	// ...
}

根据 Wrangler 配置为绑定（binding）生成 TypeScript 类型：

npm run cf-typegen

通过绑定（binding），你的应用程序可以与 Cloudflare Developer Platform 完全集成，让你访问计算、存储、AI 等功能。

Bindings

访问计算、存储、AI 等功能。

在服务端函数中使用 R2

向 Wrangler 配置添加 R2 bucket binding：

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

在服务端函数中访问 bucket：

app/routes/index.jsxjs
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;
	});
app/routes/index.tsxts
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;
	});

静态预渲染

在构建时将应用预渲染为静态 HTML，并作为静态资源提供。

vite.config.jsjs
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.tsts
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(),
	],
});

更多选项，请参阅 TanStack Start static prerendering ↗。

预渲染数据源

要使用生产数据进行预渲染，请使用远程绑定（remote bindings）。

在 CI 环境中，构建期间可能无法获取环境变量或 secrets。要使其可访问：

  • 在 CI 环境中设置 CLOUDFLARE_INCLUDE_PROCESS_ENV=true，并将所需值作为环境变量提供。
  • 如果使用 Workers Builds，请更新构建设置。

这篇文档对您有帮助吗？