Skip to content
Source
Sign inSign up
TanStack/router
Open History to see the last commit

hosting.md

483 lines18.0 KB

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
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"
76```
77​
784. Modify the scripts in your `package.json` file
79​
80```json
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 }
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>
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.