Skip to content
Cloudflare Docs

TanStack Start

TanStack Start ↗ is a full-stack framework for building web applications. It comes with features like server-side rendering, streaming, server functions, bundling, and more. In this guide, you learn to deploy a TanStack Start application to Cloudflare Workers.

Creating a new TanStack Start application

To create a TanStack Start application, run the following command:

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

After you have created your project, run the following command in the project directory to start a local development server. This will allow you to preview your project locally during development.

Terminal window
npm run dev

Configuring an existing TanStack Start application

If you have an existing TanStack Start application, you can configure it to run on Cloudflare Workers by following these steps:

  1. Add the wrangler.jsonc configuration file to the root of your project with the following content:

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

  2. Install wrangler as a development dependency:

    Terminal window
    npm i -D wrangler@latest

  3. Install the @cloudflare/vite-plugin package as a dependency:

    Terminal window
    npm i @cloudflare/vite-plugin@latest

  4. Update your vite.config.ts file to include the Cloudflare Vite plugin:

    vite.config.ts
    import { defineConfig } from "vite";
    import { cloudflare } from "@cloudflare/vite-plugin";
    ...
    

    export default defineConfig({
      plugins: [cloudflare({ viteEnvironment: { name: 'ssr' } }), ...],
      // ... other configurations
    });

  5. Update the scripts section of your package.json file to include the following commands:

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

Deploy your Project

You can deploy your project to a *.workers.dev subdomain or a Custom Domain from your own machine or from any CI/CD system, including Cloudflare's own Workers Builds.

The following command will build and deploy your project. If you are using CI, ensure you update your Deploy command configuration appropriately.

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.

You can use bindings simply by importing the env object ↗ and accessing it in your server side code.

For example in the following way:

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(() => {
  // Use env here
});


function RouteComponent() {
  // ...
}

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.

Static Prerendering

You can prerender your application to static HTML files at build time with TanStack Start and serve them as static assets.

vite.config.ts
import { defineConfig } from "vite";
import { cloudflare } from "@cloudflare/vite-plugin";
import { tanstackStart } from '@tanstack/react-start/plugin/vite'


export default defineConfig({
  plugins: [
    cloudflare({ viteEnvironment: { name: "ssr" } }),
    tanstackStart({
      prerender: {
        // Enable static prerendering
        enabled: true,
        // other prerender options...
      },
    }),
  ],
})

No additional configuration is needed in your wrangler config file. For more prerender options, see the TanStack Start documentation ↗.

Prerendering in CI environments

When prerendering in CI, your Worker code may need access to environment variables or secrets that are not available in the build environment. One way to handle this is to include a .env file with variable references, which resolve to values provided by your CI environment:

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

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