INTEGRITY Dokumentace

← Cloudflare Workers / workers / framework-guides / web-apps

TanStack Start

TanStack Start ↗ je full-stack framework pro tvorbu webových aplikací s vykreslováním na straně serveru, streamováním, serverovými funkcemi a bundlováním.

TanStack StartRozpoznáno
Konektor: Framework to Config
položky konfigurace
Vygenerovaná konfigurace
wrangler.jsonc
main:.output/server/index.mjs
wrangler.jsonc
assets:adresář: .output/public
wrangler.jsonc
compatibility_flags:nodejs_compat
wrangler.jsonc
observabilita:enabled: true
Konektor: Config to Workers
Workers uzlu
WorkersNasazeno
Ukazatel stavu
Wrangler zpracovává konfiguraci automaticky

Vytvořte novou aplikaci

Vytvořte aplikaci TanStack Start předkonfigurovanou pro Cloudflare Workers:

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

Spusťte lokální vývojový server pro náhled projektu během vývoje:

npm run dev

Nakonfigurujte existující aplikaci

Pokud máte existující aplikaci TanStack Start, nakonfigurujte ji pro běh na Cloudflare Workers:

  1. Nainstalujte @cloudflare/vite-plugin a wrangler:

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

  2. Přidejte plugin Cloudflare do konfigurace Vite:

    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(),
	],
});

  3. Přidejte wrangler.jsonc konfigurační soubor:

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

[observability]
enabled = true

  4. Aktualizujte scripts sekci v package.json:

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

Nasadit

Nasaďte na *.workers.dev subdoména nebo vlastní doména z vašeho počítače nebo libovolného systému CI/CD, včetně Workers Builds.

npm run deploy

Vlastní entrypointy

TanStack Start používá @tanstack/react-start/server-entry jako výchozí entrypoint. Vytvořte vlastní entrypoint serveru, abyste přidali další handlery Workers, jako je Queues a Cron Triggers. Zde také můžete přidat další exporty, například Durable Objects a Workflows.

  1. Vytvořte vlastní vstupní soubor serveru:

    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);
	},
};

  2. Aktualizujte konfiguraci Wrangler tak, aby odkazovala na váš vlastní entrypoint:

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

Otestujte plánované obslužné rutiny lokálně

Otestujte plánovanou obslužnou rutinu lokálně pomocí /cdn-cgi/handler/scheduled koncový bod:

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

Příklad: použití Workflows

Exportujte třídu Workflow z vlastního entrypointu, abyste mohli spouštět trvalé vícekrokové úlohy:

app/server.js
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.ts
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);
		});
	}
}

Přidejte konfiguraci Workflow do konfigurace Wrangler:

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

Příklad: použití Service Bindings

Přidejte vazbu na službu, abyste mohli z aplikace TanStack Start volat metody RPC jiného Workeru:

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

Volání metod svázaného Workeru ze serverové funkce:

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

Bindings

Aplikaci TanStack Start lze plně integrovat s Cloudflare Developer Platform, a to jak při lokálním vývoji, tak v produkčním prostředí, pomocí vazby.

Přistupujte k bindings pomocí importování env objekt v kódu na straně serveru:

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

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

function RouteComponent() {
	// ...
}

Vygenerujte typy TypeScript pro vaše bindingy na základě konfigurace Wrangler:

npm run cf-typegen

Díky bindings lze vaši aplikaci plně integrovat s Cloudflare Developer Platform a získat tak přístup k výpočetnímu výkonu, úložišti, AI a dalším službám.

Bindings

Přístup k výpočetnímu výkonu, úložišti, AI a dalším službám.

Použijte R2 v serverové funkci

Přidejte R2 bucket binding do konfigurace Wrangler:

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

Přístup k bucketu ze serverové funkce:

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

Statické přerenderování

Předrenderujte svou aplikaci do statického HTML při sestavení a poskytujte ji jako statická aktiva.

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(),
	],
});

Další možnosti najdete v Statické prerenderování v TanStack Start ↗.

Zdroje dat pro předrenderování

Chcete-li prerenderovat s produkčními daty, použijte vzdálené bindings.

V prostředích CI nemusí být proměnné prostředí ani secrets během sestavení dostupné. Aby byly dostupné: