Open History to see the last commit
1---
2id: hosting
3title: Hosting
4description: Deploy TanStack Start with Vite or Rsbuild using hosting guides for Cloudflare, Netlify, Railway, Vercel, Node.js, and other runtimes.
5---
6β
7Hosting is the process of deploying your application to the internet so that users can access it. This is a critical part of any web development project, ensuring your application is available to the world. TanStack Start supports Vite and Rsbuild, giving you flexible build outputs for different hosting providers and runtimes.
8β
9## What should I use?
10β
11TanStack Start is **designed to work with any hosting provider**, so if you already have a hosting provider in mind, you can deploy your application there using the full-stack APIs provided by TanStack Start.
12β
13However, since hosting is one of the most crucial aspects of your application's performance, reliability, and scalability, we recommend using one of our **Official Hosting Partners**: [Cloudflare](https://www.cloudflare.com?utm_source=tanstack), [Netlify](https://www.netlify.com?utm_source=tanstack), or [Railway](https://railway.com?utm_source=tanstack).
14β
15## Deployment
16β
17Once you've chosen a deployment target, you can follow the deployment guidelines below to deploy your TanStack Start application to the hosting provider of your choice:
18β
19- [`cloudflare-workers`](#cloudflare-workers--official-partner): Deploy to Cloudflare Workers
20- [`netlify`](#netlify--official-partner): Deploy to Netlify
21- [`railway`](#railway--official-partner): Deploy to Railway
22- [`nitro`](#nitro): Deploy using Nitro
23- [`vercel`](#vercel): Deploy to Vercel
24- [`node-server`](#nodejs--docker): Deploy to a Node.js server
25- [`bun`](#bun): Deploy to a Bun server
26- [`appwrite-sites`](#appwrite-sites): Deploy to Appwrite Sites
27- ... and more to come!
28β
29### Cloudflare Workers β _Official Partner_
30β
31<a href="https://www.cloudflare.com?utm_source=tanstack" alt="Cloudflare Logo">
32 <picture>
33 <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/tanstack/tanstack.com/main/src/images/cloudflare-white.svg" width="280">
34 <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/tanstack/tanstack.com/main/src/images/cloudflare-black.svg" width="280">
35 <img alt="Cloudflare logo" src="https://raw.githubusercontent.com/tanstack/tanstack.com/main/src/images/cloudflare-black.svg" width="280">
36 </picture>
37</a>
38β
39When deploying to Cloudflare Workers, you'll need to complete a few extra steps before your users can start using your app.
40The official Cloudflare Workers setup currently uses Vite through `@cloudflare/vite-plugin`.
41β
421. Install `@cloudflare/vite-plugin` and `wrangler`
43β
44```bash
45pnpm add -D @cloudflare/vite-plugin wrangler
46```
47β
482. Add the Cloudflare plugin to your `vite.config.ts` file
49β
50```ts
51// vite.config.ts
52import { defineConfig } from 'vite'
53import { tanstackStart } from '@tanstack/react-start/plugin/vite'
54import { cloudflare } from '@cloudflare/vite-plugin'
55import viteReact from '@vitejs/plugin-react'
56β
57export default defineConfig({
58 plugins: [
59 cloudflare({ viteEnvironment: { name: 'ssr' } }),
60 tanstackStart(),
61 viteReact(),
62 ],
63})
64```
65β
663. Add a `wrangler.jsonc` config file
67β
68```json
69{
70 "$schema": "node_modules/wrangler/config-schema.json",
71 "name": "tanstack-start-app",
72 "compatibility_date": "2025-09-02",
73 "compatibility_flags": ["nodejs_compat"],
74 "main": "@tanstack/react-start/server-entry"
75}
76```
77β
784. Modify the scripts in your `package.json` file
79β
80```json
81{
82 "scripts": {
83 "dev": "vite dev",
84 "build": "vite build && tsc --noEmit",
85 // ============ π remove this line ============
86 "start": "node .output/server/index.mjs",
87 // ============ π add these lines ============
88 "preview": "vite preview",
89 "deploy": "npm run build && wrangler deploy",
90 "cf-typegen": "wrangler types"
91 }
92}
93```
94β
955. Login with Wrangler to authenticate with your Cloudflare account.
96β
97```bash
98npx wrangler login
99```
100β
101or if using pnpm:
102β
103```bash
104pnpm dlx wrangler login
105```
106β
107To check current user use `wrangler whoami`.
108β
1096. Deploy
110β
111```bash
112pnpm run deploy
113```
114β
115Deploy your application to Cloudflare Workers using their one-click deployment process, and you're ready to go!
116β
117A full TanStack Start example for Cloudflare Workers is available [here](https://github.com/TanStack/router/tree/main/examples/react/start-basic-cloudflare).
118β
119### Netlify β _Official Partner_
120β
121<a href="https://www.netlify.com?utm_source=tanstack" alt="Netlify Logo">
122 <picture>
123 <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/tanstack/tanstack.com/main/src/images/netlify-dark.svg" width="280">
124 <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/tanstack/tanstack.com/main/src/images/netlify-light.svg" width="280">
125 <img alt="Netlify logo" src="https://raw.githubusercontent.com/tanstack/tanstack.com/main/src/images/netlify-light.svg" width="280">
126 </picture>
127</a>
128β
129The official Netlify setup currently uses Vite through [`@netlify/vite-plugin-tanstack-start`](https://www.npmjs.com/package/@netlify/vite-plugin-tanstack-start), which configures your build for Netlify deployment and provides full Netlify production platform emulation in local dev:
130β
131```bash
132npm install --save-dev @netlify/vite-plugin-tanstack-start
133# or...
134pnpm add --save-dev @netlify/vite-plugin-tanstack-start
135# or yarn, bun, etc.
136```
137β
138```ts
139// vite.config.ts
140import { defineConfig } from 'vite'
141import { tanstackStart } from '@tanstack/react-start/plugin/vite'
142import netlify from '@netlify/vite-plugin-tanstack-start' // β add this
143import viteReact from '@vitejs/plugin-react'
144β
145export default defineConfig({
146 plugins: [
147 tanstackStart(),
148 netlify(), // β add this (anywhere in the array is fine)
149 viteReact(),
150 ],
151})
152```
153β
154Finally, use [Netlify CLI](https://developers.netlify.com/cli/) to deploy your app:
155β
156```bash
157npx netlify deploy
158```
159β
160If this is a new Netlify project, you'll be prompted to initialize it and build settings will be automatically configured for you.
161β
162For more detailed documentation, check out the full [TanStack Start on Netlify
163docs](https://docs.netlify.com/build/frameworks/framework-setup-guides/tanstack-start/).
164β
165#### Manual configuration
166β
167Alternatively, if you prefer manual configuration, you can add a `netlify.toml` file to your project root:
168β
169```toml
170[build]
171 command = "vite build"
172 publish = "dist/client"
173[dev]
174 command = "vite dev"
175 port = 3000
176```
177β
178Or you can set the above settings directly [in the Netlify
179app](https://docs.netlify.com/build/configure-builds/overview/#build-settings).
180β
181#### Other deployment methods
182β
183Netlify also supports other deployment methods, such as [continuous deployment from a git repo
184hosted on GitHub, GitLab, or
185others](https://docs.netlify.com/start/quickstarts/deploy-from-repository/), [starting from a
186template](https://docs.netlify.com/start/quickstarts/deploy-from-template/), [deploying or
187importing from an AI code generation
188tool](https://docs.netlify.com/start/quickstarts/deploy-from-ai-code-generation-tool/), and
189[more](https://docs.netlify.com/deploy/create-deploys/).
190β
191### Railway β _Official Partner_
192β
193<a href="https://railway.com?utm_source=tanstack" alt="Railway Logo">
194 <picture>
195 <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/tanstack/tanstack.com/main/src/images/railway-white.svg" width="280">
196 <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/tanstack/tanstack.com/main/src/images/railway-black.svg" width="280">
197 <img alt="Railway logo" src="https://raw.githubusercontent.com/tanstack/tanstack.com/main/src/images/railway-light.svg" width="280">
198 </picture>
199</a>
200β
201Railway provides instant deployments with zero configuration. Follow the [`Nitro`](#nitro) deployment instructions, then deploy to Railway:
202β
2031. Push your code to a GitHub repository
204β
2052. Connect your repository to Railway at [railway.com](https://railway.com?utm_source=tanstack)
206β
2073. Railway will automatically detect your build settings and deploy your application
208β
209Railway automatically provides:
210β
211- **Automatic deployments** on every push to your repository
212- **Built-in databases** (Postgres, MySQL, Redis, MongoDB)
213- **Preview environments** for pull requests
214- **Automatic HTTPS** and custom domains
215β
216For more details, see [Railway's documentation](https://docs.railway.com).
217β
218### Nitro
219β
220[Nitro](https://nitro.build/) is an agnostic layer that allows you to deploy TanStack Start applications to [a wide range of hostings](https://nitro.build/deploy).
221β
222**β οΈ The [`nitro/vite`](https://nitro.build/) plugin natively integrates with Vite Environments API as the underlying build tool for TanStack Start. It is still under active development and receives regular updates. Please report any issues you encounter with reproduction so they can be investigated.**
223β
2241. Install `nitro`:
225β
226```bash
227npm install nitro
228```
229β
2302. Add the `nitro/vite` plugin to your `vite.config.ts` file:
231β
232```tsx
233import { tanstackStart } from '@tanstack/react-start/plugin/vite'
234import { defineConfig } from 'vite'
235import { nitro } from 'nitro/vite'
236import viteReact from '@vitejs/plugin-react'
237β
238export default defineConfig({
239 plugins: [tanstackStart(), nitro(), viteReact()],
240})
241```
242β
243#### Performance Tip: FastResponse
244β
245If you're deploying to Node.js with Nitro (which uses [srvx](https://srvx.h3.dev/) under the hood), you can get a ~5% throughput improvement by replacing the global `Response` constructor with srvx's optimized `FastResponse`.
246β
247First, install srvx:
248β
249```bash
250npm install srvx
251```
252β
253Then add this to your server entry point (`src/server.ts`):
254β
255```ts
256import { FastResponse } from 'srvx'
257globalThis.Response = FastResponse
258```
259β
260This works because srvx's `FastResponse` includes an optimized `_toNodeResponse()` path that avoids the overhead of the standard Web `Response` to Node.js conversion. This optimization only applies to Node.js deployments using Nitro/h3/srvx.
261β
262### Vercel
263β
264Follow the [`Nitro`](#nitro) deployment instructions.
265Deploy your application to Vercel using their one-click deployment process, and you're ready to go!
266β
267### Node.js / Docker
268β
269Use the Node.js deployment shape that matches your build tool.
270β
271<!-- ::start:tabs variant="bundler" -->
272β
273# Vite
274β
275Follow the [`Nitro`](#nitro) deployment instructions. Use the `node` command to start your application from the server from the build output files.
276β
277Ensure `build` and `start` npm scripts are present in your `package.json` file:
278β
279```json
280 "build": "vite build",
281 "start": "node .output/server/index.mjs"
282```
283β
284# Rsbuild
285β
286An Rsbuild production build emits client assets in `dist/client` and a server bundle in `dist/server/index.js`. The server bundle exports a fetch-style Start server entry:
287β
288```ts
289type ServerEntry = {
290 fetch(request: Request): Response | Promise<Response>
291}
292```
293β
294To run it on Node.js, serve `dist/client` as static assets and forward all other requests to the server entry's `fetch` handler. `srvx` is one way to do that:
295β
296```sh
297npm install srvx
298```
299β
300```json
301 "build": "rsbuild build",
302 "start": "srvx --prod -s ../client dist/server/index.js"
303```
304β
305Express or any other custom Node.js server works too, as long as it serves the client assets and calls the server entry's `fetch` handler for dynamic requests.
306β
307If your server entry is emitted as `dist/server/server.js`, use that path instead of `dist/server/index.js`.
308β
309<!-- ::end:tabs -->
310β
311Then you can run the following command to build your application:
312β
313```sh
314npm run build
315```
316β
317You can start your application by running:
318β
319```sh
320npm run start
321```
322β
323### Bun
324β
325> [!IMPORTANT]
326> Currently, the Bun specific deployment guidelines only work with React 19. If you are using React 18, please refer to the [Node.js](#nodejs--docker) deployment guidelines.
327β
328Make sure that your `react` and `react-dom` packages are set to version 19.0.0 or higher in your `package.json` file. If not, run the following command to upgrade the packages:
329β
330```sh
331bun install react@19 react-dom@19
332```
333β
334For Vite builds, follow the [`Nitro`](#nitro) deployment instructions.
335Depending on how you invoke the build, you might need to set the `'bun'` preset in the Nitro configuration:
336β
337```ts
338// vite.config.ts
339import { tanstackStart } from '@tanstack/react-start/plugin/vite'
340import { defineConfig } from 'vite'
341import { nitro } from 'nitro/vite'
342import viteReact from '@vitejs/plugin-react'
343β
344export default defineConfig({
345 plugins: [tanstackStart(), nitro({ preset: 'bun' }), viteReact()],
346})
347```
348β
349#### Production Server with Bun
350β
351Alternatively, you can use a custom server implementation that leverages Bun's native APIs.
352β
353We provide a reference implementation that demonstrates one approach to building a production-ready Bun server. This example uses Bun-native functions for optimal performance and includes features like intelligent asset preloading and memory management.
354β
355**This is a starting point - feel free to adapt it to your needs or simplify it for your use case.**
356β
357**What this example demonstrates:**
358β
359- Serving static assets using Bun's native file handling
360- Hybrid loading strategy (preload small files, serve large files on-demand)
361- Optional features like ETag support and Gzip compression
362- Production-ready caching headers
363β
364**Quick Setup:**
365β
3661. Copy the [`server.ts`](https://github.com/tanstack/router/blob/main/examples/react/start-bun/server.ts) file from the example repository to your project root (or use it as inspiration for your own implementation)
367β
3682. Build your application:
369β
370 ```sh
371 bun run build
372 ```
373β
3743. Start the server:
375β
376 ```sh
377 bun run server.ts
378 ```
379β
380**Configuration (Optional):**
381β
382The reference server implementation includes several optional configuration options via environment variables. You can use these as-is, modify them, or remove features you don't need:
383β
384```sh
385# Basic usage - just works out of the box
386bun run server.ts
387β
388# Common configurations
389PORT=8080 bun run server.ts # Custom port
390ASSET_PRELOAD_VERBOSE_LOGGING=true bun run server.ts # See what's happening
391```
392β
393**Available Environment Variables:**
394β
395| Variable | Description | Default |
396| -------------------------------- | -------------------------------------------------- | ----------------------------------------------------------------------------- |
397| `PORT` | Server port | `3000` |
398| `ASSET_PRELOAD_MAX_SIZE` | Maximum file size to preload into memory (bytes) | `5242880` (5MB) |
399| `ASSET_PRELOAD_INCLUDE_PATTERNS` | Comma-separated glob patterns for files to include | All files |
400| `ASSET_PRELOAD_EXCLUDE_PATTERNS` | Comma-separated glob patterns for files to exclude | None |
401| `ASSET_PRELOAD_VERBOSE_LOGGING` | Enable detailed logging | `false` |
402| `ASSET_PRELOAD_ENABLE_ETAG` | Enable ETag generation | `true` |
403| `ASSET_PRELOAD_ENABLE_GZIP` | Enable Gzip compression | `true` |
404| `ASSET_PRELOAD_GZIP_MIN_SIZE` | Minimum file size for Gzip (bytes) | `1024` (1KB) |
405| `ASSET_PRELOAD_GZIP_MIME_TYPES` | MIME types eligible for Gzip | `text/,application/javascript,application/json,application/xml,image/svg+xml` |
406β
407<details>
408<summary>Advanced configuration examples</summary>
409β
410```sh
411# Optimize for minimal memory usage
412ASSET_PRELOAD_MAX_SIZE=1048576 bun run server.ts
413β
414# Preload only critical assets
415ASSET_PRELOAD_INCLUDE_PATTERNS="*.js,*.css" \
416ASSET_PRELOAD_EXCLUDE_PATTERNS="*.map,vendor-*" \
417bun run server.ts
418β
419# Disable optional features
420ASSET_PRELOAD_ENABLE_ETAG=false \
421ASSET_PRELOAD_ENABLE_GZIP=false \
422bun run server.ts
423β
424# Custom Gzip configuration
425ASSET_PRELOAD_GZIP_MIN_SIZE=2048 \
426ASSET_PRELOAD_GZIP_MIME_TYPES="text/,application/javascript,application/json" \
427bun run server.ts
428```
429β
430</details>
431β
432**Example Output:**
433β
434```txt
435π¦ Loading static assets from ./dist/client...
436 Max preload size: 5.00 MB
437β
438π Preloaded into memory:
439 /assets/index-a1b2c3d4.js 45.23 kB β gzip: 15.83 kB
440 /assets/index-e5f6g7h8.css 12.45 kB β gzip: 4.36 kB
441β
442πΎ Served on-demand:
443 /assets/vendor-i9j0k1l2.js 245.67 kB β gzip: 86.98 kB
444β
445β
Preloaded 2 files (57.68 KB) into memory
446π Server running at http://localhost:3000
447```
448β
449For a complete working example, check out the [TanStack Start + Bun example](https://github.com/TanStack/router/tree/main/examples/react/start-bun) in this repository.
450β
451### Appwrite Sites
452β
453When deploying to [Appwrite Sites](https://appwrite.io/products/sites), you'll need to complete a few steps:
454β
4551. **Create a TanStack Start app** (or use an existing one)
456β
457```bash
458npx @tanstack/cli@latest create
459```
460β
4612. **Push your project to a GitHub repository**
462β
463Create a [GitHub repository](https://github.com/new) and push your code.
464β
4653. **Create an Appwrite project**
466β
467Head to [Appwrite Cloud](https://cloud.appwrite.io) and sign up if you haven't already, then create your first project.
468β
4694. **Deploy your site**
470β
471In your Appwrite project, navigate to the **Sites** page from the sidebar. Click on the **Create site**, select **Connect a repository**, connect your GitHub account and select your repository.
472β
4731. Select the **production branch** and **root directory**
4742. Verify **TanStack Start** is selected as the framework
4753. Confirm the build settings:
476 - **Install command:** `npm install`
477 - **Build command:** `npm run build`
478 - **Output directory:** `./dist` (if you're using Nitro, this should be `./.output`)
479β
4804. Add any required **environment variables**
4815. Click **Deploy**
482β
483After successful deployment, click the **Visit site** button to see your deployed application.