Skip to content
Cloudflare Docs

TanStack Start

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

Create a new application

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

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

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

Terminal window
npm run dev

Configure an existing application

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

  1. Install @cloudflare/vite-plugin and wrangler:

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

  2. Add the Cloudflare plugin to your Vite configuration:

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

  3. Add a wrangler.jsonc configuration file:

    {
      "$schema": "node_modules/wrangler/config-schema.json",
      "name": "<YOUR_PROJECT_NAME>",
      "compatibility_date": "2025-01-01",
      "compatibility_flags": ["nodejs_compat"],
      "main": "@tanstack/react-start/server-entry",
      "observability": {
        "enabled": true,
      },
    }

  4. 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.

Terminal window
npm run deploy

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:

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() {
  // ...
}

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

Terminal window
npm 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.

Bindings Access to compute, storage, AI and more.

Use R2 in a server function

Add an R2 bucket binding to your Wrangler configuration:

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

Access the bucket in a server function:

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

Static prerendering

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

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

For more options, refer to TanStack Start static prerendering ↗.

Prerender in CI environments

When prerendering in CI, your Worker code may need environment variables or secrets not available in the build environment. Include a .env file with variable references that resolve to values from your CI environment:

.env
API_KEY=${API_KEY}
DATABASE_URL=${DATABASE_URL}

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.