You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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 tools like Nitro and Vite.
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.
16
16
17
17
## Create a new TanStack Start
18
18
19
-
TanStack provides a start-basic project. We'll use this starter project to create a new TanStack Start application.
19
+
TanStack Start Beta has significantly improved Cloudflare compatibility compared to the Alpha version, making deployment and development much more straightforward.
20
20
21
21
<Steps>
22
22
@@ -27,10 +27,10 @@ TanStack provides a start-basic project. We'll use this starter project to creat
27
27
cd start-basic
28
28
npm install
29
29
```
30
-
31
-
<Detailsheader="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>
30
+
31
+
<Detailsheader="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>
34
34
35
35
2.**Develop locally**
36
36
@@ -46,34 +46,33 @@ Whether you created a new TanStack Start project or are using an existing projec
[`unenv`](https://github.com/unjs/unenv) is a package that normalizes runtime environments across Node.js, browsers, and edge runtimes like Cloudflare Workers. It’s essential for TanStack Router because certain Node.js APIs are unavailable in the Workers environment. `unenv` offers compatible replacements for those APIs.
52
-
53
-
[`nitro-cloudflare-dev`](https://github.com/nitrojs/nitro-cloudflare-dev) enables access to the Cloudflare runtime bindings like R2, D1, and other Cloudflare services in the development server.
target: "cloudflare-module", // Key configuration for Cloudflare compatibility
68
+
}),
69
+
],
70
+
});
72
71
```
73
72
74
-
This will set the correct build format and runtime environment for Cloudflare.
73
+
This single configuration change is all that's needed to make your TanStack Start application compatible with Cloudflare Workers.
75
74
76
-
3.**Add a Wrangler file**
75
+
2.**Add a Wrangler file**
77
76
78
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.
79
78
@@ -82,23 +81,45 @@ Whether you created a new TanStack Start project or are using an existing projec
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.
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:
The `deploy` script combines building and deploying in one command, while `cf-typegen` generates TypeScript types for your Cloudflare bindings.
122
+
102
123
4.**Build the application**
103
124
104
125
You must build your application before deploying it to Cloudflare Workers.
@@ -107,75 +128,104 @@ Whether you created a new TanStack Start project or are using an existing projec
107
128
108
129
5.**Deploy the application**
109
130
110
-
The command below will deploy your application to Cloudflare Workers and provide a deployment URL. Make sure to rebuild your application after making any changes to see those changes reflected in the deployment.
131
+
You can now use the deploy script to build and deploy your application in one command:
132
+
133
+
<PackageManagerstype="run"args={"deploy"} />
134
+
135
+
Alternatively, you can still deploy directly with Wrangler:
111
136
112
137
```sh
113
138
npx wrangler deploy
114
139
```
115
140
116
-
When making changes in the future ensure you rebuild your application. The deploy will deploy what is in your `.output/public` folder and that only gets updated when you run the build command.
117
-
118
141
</Steps>
119
142
120
143
## Using Cloudflare Bindings
121
144
122
145
<Steps>
123
146
124
-
1.**Create a helper function to get access to Cloudflare bindings**
147
+
1.**Generate TypeScript types for your bindings**
125
148
126
-
Create a helper function named `cloudflareBindings.ts`in the `src/utils` folder, and paste in the below code. You can create a `utils` folder in your project if you don't already have one. 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.
149
+
Before using Cloudflare bindings in your code, generate the TypeScript types to ensure proper type safety:
This command reads your `wrangler.jsonc` configuration and generates an `Env` interface with all your configured bindings.
130
154
131
-
interfaceCloudflareBindings {
132
-
CACHE:KVNamespace;
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
method from wrangler. This logic is placed under a check if
153
-
import.meta.env.DEV is true.
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.
154
195
</Details>
155
196
156
-
2.**Example using a Cloudflare Binding**
197
+
3.**Example using a Cloudflare Binding in Server Functions**
157
198
158
-
Now that you have a helper function to get access to your Cloudflare bindings, you can use them in your application.
199
+
Now that you have a helper function to get access to your Cloudflare bindings, you can use them in your server functions.
159
200
160
201
Remember bindings are only available on the server.
let growingAge =Number((awaitenv.CACHE.get("age")) ||0);
212
+
growingAge++;
213
+
awaitenv.CACHE.put("age", growingAge.toString());
214
+
return { name, randomNumber: growingAge };
215
+
});
167
216
```
168
217
169
-
A special thanks to GitHub user [backpine](https://github.com/backpine) for the code that supports Cloudflare Bindings in TanStack, which is demonstrated in their [TanStack Start on Workers example](https://github.com/backpine/tanstack-start-on-cloudflare-workers-v0).
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).
170
219
171
220
</Steps>
172
221
173
-
#### Optional: Update utils file with deployment URL
222
+
## Environment Handling
223
+
224
+
The TanStack Start Beta version provides seamless environment handling:
174
225
175
-
This step is required for the `/users` page to function properly in the `start-basic` example. Update the `/src/utils/users.tsx` file with the Cloudflare Workers deployment URL.
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)
176
228
177
-
```ts
178
-
exportconst DEPLOY_URL ="YOUR_DEPLOYMENT_URL";
179
-
```
229
+
This approach ensures your bindings are properly typed throughout your project and provides a smooth development experience.
180
230
181
231
By following the steps above, you will have deployed your TanStack Start application to Cloudflare Workers.
0 commit comments