Skip to content

Commit e9a7e35

Browse files
dario-piotrowiczjamesopstad
dario-piotrowicz
and
jamesopstad
authored
Update TanStack Workers guide to use the Cloudflare Vite plugin (#25529)
Note: this is a temporary update to the guide (which is currently incorrect), we're working on enabling C3 to generate TanStack applications to streamline the process for developers, once that's ready we'll update again this guide accordingly --------- Co-authored-by: James Opstad <[email protected]>
1 parent 8aa779d commit e9a7e35

File tree

1 file changed

+64
-183
lines changed
  • src/content/docs/workers/framework-guides/web-apps

1 file changed

+64
-183
lines changed

‎src/content/docs/workers/framework-guides/web-apps/tanstack.mdx‎

Lines changed: 64 additions & 183 deletions
Original file line numberDiff line numberDiff line change
@@ -8,224 +8,105 @@ tags: ["full-stack"]
88
description: Create a TanStack Start application and deploy it to Cloudflare Workers with Workers Assets.
99
---
1010

11-
import { WranglerConfig, Steps, PackageManagers, Details } from "~/components";
11+
import {
12+
Badge,
13+
Description,
14+
InlineBadge,
15+
Render,
16+
PackageManagers,
17+
} from "~/components";
1218

13-
## What is TanStack Start?
19+
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/)).
1420

15-
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.
21+
## 1. Set up a new project
1622

17-
## Create a new TanStack Start
23+
Start by cloning the Cloudflare example from the official TanStack repository.
1824

19-
TanStack Start Beta has significantly improved Cloudflare compatibility compared to the Alpha version, making deployment and development much more straightforward.
25+
<PackageManagers
26+
type="dlx"
27+
pkg="gitpick"
28+
args="TanStack/router/tree/main/examples/react/start-basic-cloudflare my-tanstack-app"
29+
/>
2030

21-
<Steps>
31+
After setting up your project, change your directory by running the following command:
2232

23-
1. **Create a new TanStack Start project**
33+
```sh
34+
cd my-tanstack-app
35+
```
2436

25-
```sh
26-
npx gitpick TanStack/router/tree/main/examples/react/start-basic start-basic
27-
cd start-basic
28-
npm install
29-
```
30-
31-
<Details header="How is this project set up?">
32-
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.
33-
</Details>
37+
And install the project's dependencies with:
3438

35-
2. **Develop locally**
39+
<PackageManagers type="install" />
3640

37-
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/`
41+
## 2. Develop locally
3842

39-
<PackageManagers type="run" args="dev" />
43+
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.
4044

41-
</Steps>
45+
<PackageManagers type="run" args="dev" />
4246

43-
## Preparing for Deployment to Cloudflare Workers
47+
## 3. Deploy your Project
4448

45-
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.
49+
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/).
4650

47-
<Steps>
51+
To deploy your application you will first need to build it:
4852

49-
1. **Configure Vite for Cloudflare compatibility**
53+
<PackageManagers type="run" args="build" />
5054

51-
Update your `vite.config.ts` file to use the `cloudflare-module` target for a compatible build:
55+
Once it's been built you can deploy it via:
5256

53-
```ts title="vite.config.ts" {14}
54-
import { tanstackStart } from "@tanstack/react-start/plugin/vite";
55-
import { defineConfig } from "vite";
56-
import tsConfigPaths from "vite-tsconfig-paths";
57+
<PackageManagers type="run" args="deploy" />
5758

58-
export default defineConfig({
59-
server: {
60-
port: 3000,
61-
},
62-
plugins: [
63-
tsConfigPaths({
64-
projects: ["./tsconfig.json"],
65-
}),
66-
tanstackStart({
67-
target: "cloudflare-module", // Key configuration for Cloudflare compatibility
68-
}),
69-
],
70-
});
71-
```
59+
If you're using CI, ensure you update your ["deploy command"](/workers/ci-cd/builds/configuration/#build-settings) configuration appropriately.
7260

73-
This single configuration change is all that's needed to make your TanStack Start application compatible with Cloudflare Workers.
61+
:::note
7462

75-
2. **Add a Wrangler file**
63+
After having built the application you can run the `preview` script to preview the built output locally before deploying it.
64+
This can help you making sure that your application will work as intended once it's been deployed to the Cloudflare network:
7665

77-
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.
66+
<PackageManagers type="run" args="preview" />
7867

79-
<WranglerConfig>
68+
:::
8069

81-
```json
82-
{
83-
"$schema": "node_modules/wrangler/config-schema.json",
84-
"name": "my-start-app",
85-
"main": ".output/server/index.mjs",
86-
"compatibility_date": "$today",
87-
"compatibility_flags": ["nodejs_compat"],
88-
"assets": {
89-
"directory": ".output/public"
90-
},
91-
"observability": {
92-
"enabled": true
93-
},
94-
"kv_namespaces": [
95-
{
96-
"binding": "CACHE",
97-
"id": "<Your KV ID>"
98-
}
99-
]
100-
}
101-
```
102-
103-
</WranglerConfig>
104-
105-
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.
106-
107-
3. **Add deployment scripts to package.json**
108-
109-
Add the following scripts to your `package.json` file to streamline deployment and type generation:
110-
111-
```json title="package.json
112-
{
113-
"scripts": {
114-
...
115-
"deploy": "npm run build && wrangler deploy",
116-
"cf-typegen": "wrangler types --env-interface Env"
117-
}
118-
}
119-
```
120-
121-
The `deploy` script combines building and deploying in one command, while `cf-typegen` generates TypeScript types for your Cloudflare bindings.
122-
123-
4. **Build the application**
124-
125-
You must build your application before deploying it to Cloudflare Workers.
126-
127-
<PackageManagers type="run" args={"build"} />
128-
129-
5. **Deploy the application**
130-
131-
You can now use the deploy script to build and deploy your application in one command:
132-
133-
<PackageManagers type="run" args={"deploy"} />
134-
135-
Alternatively, you can still deploy directly with Wrangler:
136-
137-
```sh
138-
npx wrangler deploy
139-
```
140-
141-
</Steps>
142-
143-
## Using Cloudflare Bindings
144-
145-
<Steps>
146-
147-
1. **Generate TypeScript types for your bindings**
148-
149-
Before using Cloudflare bindings in your code, generate the TypeScript types to ensure proper type safety:
150-
151-
<PackageManagers type="run" args={"cf-typegen"} />
152-
153-
This command reads your `wrangler.jsonc` configuration and generates an `Env` interface with all your configured bindings.
154-
155-
2. **Create a helper function to get access to Cloudflare bindings**
156-
157-
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.
158-
159-
160-
```ts title="src/utils/bindings.ts"
161-
162-
let cachedEnv: Env | null = null;
163-
164-
// This gets called once at startup when running locally
165-
const initDevEnv = async () => {
166-
const { getPlatformProxy } = await import("wrangler");
167-
const proxy = await getPlatformProxy();
168-
cachedEnv = proxy.env as unknown as Env;
169-
};
170-
171-
if (import.meta.env.DEV) {
172-
await initDevEnv();
173-
}
70+
---
17471

175-
/**
176-
* Will only work when being accessed on the server. Obviously, CF bindings are not available in the browser.
177-
* @returns
178-
*/
179-
export function getBindings(): Env {
180-
if (import.meta.env.DEV) {
181-
if (!cachedEnv) {
182-
throw new Error(
183-
"Dev bindings not initialized yet. Call initDevEnv() first."
184-
);
185-
}
186-
return cachedEnv;
187-
}
72+
## Bindings
18873

189-
return process.env as unknown as Env;
190-
}
191-
```
74+
Your TanStack Start application can be fully integrated with the Cloudflare Developer Platform, in both local development and in production, by using bindings.
19275

193-
<Details header="How is this code working?">
194-
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.
195-
</Details>
76+
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
77+
side code.
19678

197-
3. **Example using a Cloudflare Binding in Server Functions**
79+
For example in the following way:
19880

199-
Now that you have a helper function to get access to your Cloudflare bindings, you can use them in your server functions.
81+
```tsx
82+
import { createFileRoute } from "@tanstack/react-router";
83+
import { createServerFn } from "@tanstack/react-start";
84+
import { env } from "cloudflare:workers";
20085

201-
Remember bindings are only available on the server.
86+
export const Route = createFileRoute("/")({
87+
loader: () => getData(),
88+
component: RouteComponent,
89+
});
20290

203-
```ts
204-
import { createServerFn } from "@tanstack/react-start";
205-
import { getBindings } from "~/utils/bindings";
91+
const getData = createServerFn().handler(() => {
92+
// Use env here
93+
});
20694

207-
const personServerFn = createServerFn({ method: "GET" })
208-
.validator((d: string) => d)
209-
.handler(async ({ data: name }) => {
210-
const env = getBindings();
211-
let growingAge = Number((await env.CACHE.get("age")) || 0);
212-
growingAge++;
213-
await env.CACHE.put("age", growingAge.toString());
214-
return { name, randomNumber: growingAge };
215-
});
216-
```
95+
function RouteComponent() {
96+
// ...
97+
}
98+
```
21799

218-
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).
100+
See `src/routes/index.tsx` for an example.
219101

220-
</Steps>
102+
:::note
221103

222-
## Environment Handling
104+
Running the `cf-typegen` script:
223105

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

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

229-
This approach ensures your bindings are properly typed throughout your project and provides a smooth development experience.
110+
:::
230111

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

0 commit comments

Comments
 (0)