Skip to content

Update TanStack Workers guide to use the Cloudflare Vite plugin #25529

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 9 commits into from
Oct 1, 2025
Merged

Update TanStack Workers guide to use the Cloudflare Vite plugin #25529

Changes from 7 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
a83cab9
Update TanStack Workers guide to use the Cloudflare Vite plugin
dario-piotrowicz Sep 30, 2025
5b0dbdd
Apply suggestion from @jamesopstad
dario-piotrowicz Sep 30, 2025
a0fb3f3
amend incorred deployment instructions
dario-piotrowicz Sep 30, 2025
0621183
Apply suggestions from code review
dario-piotrowicz Sep 30, 2025
33d66fe
Apply suggestions from code review
dario-piotrowicz Sep 30, 2025
e46808b
add missing imports
dario-piotrowicz Sep 30, 2025
080b305
simplify and fix guide by using example app instead of the tanstack cli
dario-piotrowicz Oct 1, 2025
f4e0639
remove extra heading
dario-piotrowicz Oct 1, 2025
a37a994
Apply suggestions from code review
dario-piotrowicz Oct 1, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
247 changes: 64 additions & 183 deletions src/content/docs/workers/framework-guides/web-apps/tanstack.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,224 +8,105 @@ tags: ["full-stack"]
description: Create a TanStack Start application and deploy it to Cloudflare Workers with Workers Assets.
---

import { WranglerConfig, Steps, PackageManagers, Details } from "~/components";
import {
Badge,
Description,
InlineBadge,
Render,
PackageManagers,
} from "~/components";

## What is TanStack Start?
In this guide, you will create a new [TanStack Start](https://tanstack.com/start) application and deploy it to Cloudflare Workers (with the new [Workers Assets](/workers/static-assets/)).

TanStack Start is a full-stack React framework powered by TanStack Router. It provides a full-document SSR, streaming, server functions, bundling, and more using Vite and modern web standards.
## 1. Set up a new project

## Create a new TanStack Start
### Create the project

TanStack Start Beta has significantly improved Cloudflare compatibility compared to the Alpha version, making deployment and development much more straightforward.
Start by cloning the basic template from the official TanStack repository

<Steps>
<PackageManagers
type="dlx"
pkg="gitpick"
args="TanStack/router/tree/main/examples/react/start-basic-cloudflare my-tanstack-app"
/>

1. **Create a new TanStack Start project**
After setting up your project, change your directory by running the following command:

```sh
npx gitpick TanStack/router/tree/main/examples/react/start-basic start-basic
cd start-basic
npm install
```

<Details header="How is this project set up?">
This command will clone the TanStack Start basic project to your local machine, change directory to the project, and install the dependencies. TanStack [provides other examples](https://tanstack.com/start/latest/docs/framework/react/quick-start#examples) that you can use by replacing `start-basic` with the example you want to use.
</Details>
```sh
cd my-tanstack-app
```

2. **Develop locally**
And install the project's dependencies with:

After creating your project, run the following command in your project directory to start a local development server. By default this starts a local development server on `http://localhost:3000/`
<PackageManagers type="install" />

<PackageManagers type="run" args="dev" />
## 2. Develop locally

</Steps>
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.

## Preparing for Deployment to Cloudflare Workers
<PackageManagers type="run" args="dev" />

Whether you created a new TanStack Start project or are using an existing project, you'll need to make some changes to prepare for deployment to Cloudflare Workers.
## 3. Deploy your Project

<Steps>
Your project can be deployed to a `*.workers.dev` subdomain or a [Custom Domain](/workers/configuration/routing/custom-domains/), from your own machine or from any CI/CD system, including [Cloudflare's own](/workers/ci-cd/builds/).

1. **Configure Vite for Cloudflare compatibility**
To deploy your application you will first need to build it:

Update your `vite.config.ts` file to use the `cloudflare-module` target for a compatible build:
<PackageManagers type="run" args="build" />

```ts title="vite.config.ts" {14}
import { tanstackStart } from "@tanstack/react-start/plugin/vite";
import { defineConfig } from "vite";
import tsConfigPaths from "vite-tsconfig-paths";
Once it's been built you can deploy it via:

export default defineConfig({
server: {
port: 3000,
},
plugins: [
tsConfigPaths({
projects: ["./tsconfig.json"],
}),
tanstackStart({
target: "cloudflare-module", // Key configuration for Cloudflare compatibility
}),
],
});
```
<PackageManagers type="run" args="deploy" />

This single configuration change is all that's needed to make your TanStack Start application compatible with Cloudflare Workers.
If you're using CI, ensure you update your ["deploy command"](/workers/ci-cd/builds/configuration/#build-settings) configuration appropriately.

2. **Add a Wrangler file**
:::note

Create a `wrangler.jsonc` or `wrangler.toml` file in the root of your project, `wrangler.jsonc` is the recommended approach. This file is used to configure the Cloudflare Workers deployment.
After having built the application you can run the `preview` script to preview the built output locally before deploying it.
This can help you making sure that your application will work as intended once it's been deployed to the Cloudflare network:

<WranglerConfig>
<PackageManagers type="run" args="preview" />

```json
{
"$schema": "node_modules/wrangler/config-schema.json",
"name": "my-start-app",
"main": ".output/server/index.mjs",
"compatibility_date": "$today",
"compatibility_flags": ["nodejs_compat"],
"assets": {
"directory": ".output/public"
},
"observability": {
"enabled": true
},
"kv_namespaces": [
{
"binding": "CACHE",
"id": "<Your KV ID>"
}
]
}
```
:::

</WranglerConfig>

Note that the `directory` key is set to `.output/public`, which is the folder that will be filled with the build output. Additionally, the `main` key is set to `.output/server/index.mjs`, indicating to Cloudflare Workers where to locate the entry point for your application. The `kv_namespaces` section shows an example of how to configure a KV namespace binding.

3. **Add deployment scripts to package.json**

Add the following scripts to your `package.json` file to streamline deployment and type generation:

```json title="package.json
{
"scripts": {
...
"deploy": "npm run build && wrangler deploy",
"cf-typegen": "wrangler types --env-interface Env"
}
}
```

The `deploy` script combines building and deploying in one command, while `cf-typegen` generates TypeScript types for your Cloudflare bindings.

4. **Build the application**

You must build your application before deploying it to Cloudflare Workers.

<PackageManagers type="run" args={"build"} />

5. **Deploy the application**

You can now use the deploy script to build and deploy your application in one command:

<PackageManagers type="run" args={"deploy"} />

Alternatively, you can still deploy directly with Wrangler:

```sh
npx wrangler deploy
```

</Steps>

## Using Cloudflare Bindings

<Steps>

1. **Generate TypeScript types for your bindings**

Before using Cloudflare bindings in your code, generate the TypeScript types to ensure proper type safety:

<PackageManagers type="run" args={"cf-typegen"} />

This command reads your `wrangler.jsonc` configuration and generates an `Env` interface with all your configured bindings.

2. **Create a helper function to get access to Cloudflare bindings**

Create a helper function named `bindings.ts` in the `src/utils` folder (create the folder if it doesn't exist), and paste in the below code. The example assumes you have a KV namespace with a binding name of `CACHE` already created in your account and added to the wrangler file.


```ts title="src/utils/bindings.ts"

let cachedEnv: Env | null = null;

// This gets called once at startup when running locally
const initDevEnv = async () => {
const { getPlatformProxy } = await import("wrangler");
const proxy = await getPlatformProxy();
cachedEnv = proxy.env as unknown as Env;
};

if (import.meta.env.DEV) {
await initDevEnv();
}

/**
* Will only work when being accessed on the server. Obviously, CF bindings are not available in the browser.
* @returns
*/
export function getBindings(): Env {
if (import.meta.env.DEV) {
if (!cachedEnv) {
throw new Error(
"Dev bindings not initialized yet. Call initDevEnv() first."
);
}
return cachedEnv;
}
---

return process.env as unknown as Env;
}
```
## Bindings

<Details header="How is this code working?">
The helper function uses [getPlatformProxy](/workers/wrangler/api/#getplatformproxy) method from wrangler to provide access to your Cloudflare bindings during local development. The bindings are cached at startup for better performance. In production, bindings are accessed via `process.env`. Make sure you've run `npm run cf-typegen` to generate the `Env` types that this code references.
</Details>
Your TanStack Start application can be fully integrated with the Cloudflare Developer Platform, in both local development and in production, by using bindings.

3. **Example using a Cloudflare Binding in Server Functions**
You can use bindings simply by [importing the `env` object](https://developers.cloudflare.com/workers/runtime-apis/bindings/#importing-env-as-a-global) and accessing it in your server
side code.

Now that you have a helper function to get access to your Cloudflare bindings, you can use them in your server functions.
For example in the following way:

Remember bindings are only available on the server.
```tsx
import { createFileRoute } from "@tanstack/react-router";
import { createServerFn } from "@tanstack/react-start";
import { env } from "cloudflare:workers";

```ts
import { createServerFn } from "@tanstack/react-start";
import { getBindings } from "~/utils/bindings";
export const Route = createFileRoute("/")({
loader: () => getData(),
component: RouteComponent,
});

const personServerFn = createServerFn({ method: "GET" })
.validator((d: string) => d)
.handler(async ({ data: name }) => {
const env = getBindings();
let growingAge = Number((await env.CACHE.get("age")) || 0);
growingAge++;
await env.CACHE.put("age", growingAge.toString());
return { name, randomNumber: growingAge };
});
```
const getData = createServerFn().handler(() => {
// Use env here
});

A special thanks to GitHub user [backpine](https://github.com/backpine) for the code that supports Cloudflare Bindings in TanStack Start, which is demonstrated in their [TanStack Start Beta on Cloudflare example](https://github.com/backpine/tanstack-start-beta-on-cloudflare).
function RouteComponent() {
// ...
}
```

</Steps>
:::note

## Environment Handling
Running the `cf-typegen` script:

The TanStack Start Beta version provides seamless environment handling:
<PackageManagers type="run" args="cf-typegen" />

- **Development**: Bindings are accessed via [`getPlatformProxy()`](/workers/wrangler/api/#getplatformproxy) from Wrangler and cached at startup
- **Production**: Bindings are accessed via [`process.env`](/workers/runtime-apis/nodejs/process/#processenv)
Will populate the `env` object with the various bindings based on your configuration.

This approach ensures your bindings are properly typed throughout your project and provides a smooth development experience.
:::

By following the steps above, you will have deployed your TanStack Start application to Cloudflare Workers.
<Render file="frameworks-bindings" product="workers" />
Loading