Co-authored-by: Claude <noreply@anthropic.com> Co-authored-by: Manuel Schiller <manuel.schiller@caligano.de> Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
11 KiB
| id | title |
|---|---|
| hosting | Hosting |
Hosting 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 is built on Vite, a powerful dev/build platform that allows us to make it possible to deploy your application to any hosting provider.
What should I use?
TanStack 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.
However, 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 or Netlify.
Deployment
Warning
The page is still a work in progress. We'll keep updating this page with guides on deployment to different hosting providers soon!
Once 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:
cloudflare-workers: Deploy to Cloudflare Workersnetlify: Deploy to Netlifyvercel: Deploy to Vercelrailway: Deploy to Railwaynitro: Deploy to a Nitro servernode-server: Deploy to a Node.js serverbun: Deploy to a Bun server- ... and more to come!
Cloudflare Workers ⭐ Official Partner
Cloudflare Workers
When deploying to Cloudflare Workers, you'll need to complete a few extra steps before your users can start using your app.
- Update
vite.config.ts
Add the cloudflare plugin to your vite.config.ts file.
// vite.config.ts
import { defineConfig } from 'vite'
import { tanstackStart } from '@tanstack/react-start/plugin/vite'
import { cloudflare } from '@cloudflare/vite-plugin'
import viteReact from '@vitejs/plugin-react'
export default defineConfig({
plugins: [
cloudflare({ viteEnvironment: { name: 'ssr' } }),
tanstackStart(),
viteReact(),
],
})
- Add a
wrangler.jsonconfig file
{
"$schema": "node_modules/wrangler/config-schema.json",
"name": "tanstack-start-app",
"compatibility_date": "2025-09-02",
"compatibility_flags": ["nodejs_compat"],
"main": "@tanstack/react-start/server-entry",
"vars": {
"MY_VAR": "Hello from Cloudflare"
}
}
Deploy your application to Cloudflare Workers using their one-click deployment process, and you're ready to go!
Netlify ⭐ Official Partner
Netlify
Install and add the @netlify/vite-plugin-tanstack-start plugin, which configures your build for Netlify deployment and provides full Netlify production platform emulation in local dev.
// vite.config.ts
import { defineConfig } from 'vite'
import { tanstackStart } from '@tanstack/react-start/plugin/vite'
import netlify from '@netlify/vite-plugin-tanstack-start'
import viteReact from '@vitejs/plugin-react'
export default defineConfig({
plugins: [tanstackStart(), netlify(), viteReact()],
})
Add a netlify.toml file to your project root:
[build]
command = "vite build"
publish = "dist/client"
Deploy your application using their one-click deployment process, and you're ready to go!
Vercel
⚠️ During TanStack Start 1.0 release candidate phase, we currently recommend using:
- @tanstack/nitro-v2-vite-plugin (Temporary Compatibility Plugin) - A temporary compatibility plugin for using Nitro v2 as the underlying build tool for TanStack Start.
- Nitro v3's Vite Plugin (BETA) - A BETA plugin for officially using Nitro v3 as the underlying build tool for TanStack Start.
Using Nitro v2
⚠️ @tanstack/nitro-v2-vite-plugin is a temporary compatibility plugin for using Nitro v2 as the underlying build tool for TanStack Start. Use this plugin if you experience issues with the Nitro v3 plugin. It does not support all of Nitro v3's features and is limited in it's dev server capabilities, but should work as a safe fallback, even for production deployments for those who were using TanStack Start's alpha/beta versions.
If you want to use this plugin with bun please make sure to use isolated installs.
import { tanstackStart } from '@tanstack/react-start/plugin/vite'
import { defineConfig } from 'vite'
import tsConfigPaths from 'vite-tsconfig-paths'
import viteReact from '@vitejs/plugin-react'
import { nitroV2Plugin } from '@tanstack/nitro-v2-vite-plugin'
export default defineConfig({
plugins: [
tsConfigPaths({ projects: ['./tsconfig.json'] }),
tanstackStart(),
nitroV2Plugin(),
viteReact(),
],
})
Using Nitro v3 (BETA)
⚠️ The nitro vite plugin is an official BETA plugin from the Nitro team for using Nitro v3 as the underlying build tool for TanStack Start. It is still in development and is receiving regular updates.
This package needs to be installed as follows:
"nitro": "npm:nitro-nightly",
import { tanstackStart } from '@tanstack/react-start/plugin/vite'
import { defineConfig } from 'vite'
import tsConfigPaths from 'vite-tsconfig-paths'
import viteReact from '@vitejs/plugin-react'
import { nitro } from 'nitro/vite'
export default defineConfig({
plugins: [
tsConfigPaths({ projects: ['./tsconfig.json'] }),
tanstackStart(),
nitro(),
viteReact(),
],
})
Deploy your application to Vercel using their one-click deployment process, and you're ready to go!
Node.js / Railway / Docker
TanStack Start builds to a node server by default. Use the node command to start your application from the server from the build output files.
// vite.config.ts
import { tanstackStart } from '@tanstack/react-start/plugin/vite'
import { defineConfig } from 'vite'
export default defineConfig({
plugins: [tanstackStart()],
})
Ensure build and start npm scripts are present in your package.json file:
"build": "vite build",
"start": "node .output/server/index.mjs"
Then you can run the following command to build your application:
npm run build
You can start your application by running:
npm run start
Bun
Important
Currently, the Bun specific deployment guidelines only work with React 19. If you are using React 18, please refer to the Node.js deployment guidelines.
Make 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:
bun install react@19 react-dom@19
Ensure your vite.config.ts file is correct:
// vite.config.ts
import { defineConfig } from 'vite'
import { tanstackStart } from '@tanstack/react-start/plugin/vite'
import viteReact from '@vitejs/plugin-react'
export default defineConfig({
plugins: [tanstackStart(), viteReact()],
})
Production Server with Bun
To run TanStack Start applications in production with Bun, you need a custom server implementation.
We've created an optimized production server that provides intelligent static asset loading with configurable memory management.
Features:
- Hybrid loading strategy: Small files (<5MB by default) are preloaded into memory, large files are served on-demand
- Configurable file filtering: Use include/exclude patterns to control which files are preloaded
- Production-ready caching headers: Automatic optimization for static assets
- Memory-efficient: Smart memory management prevents excessive RAM usage
Quick Setup:
-
Copy the
server.tsfile from the example in this repository to your project root -
Build your application:
bun run build -
Start the server:
bun run server.ts
Configuration:
The server can be configured using environment variables:
# Basic usage
bun run server.ts
# Custom port
PORT=8080 bun run server.ts
# Optimize for minimal memory usage (1MB preload limit)
STATIC_PRELOAD_MAX_BYTES=1048576 bun run server.ts
# Preload only critical assets
STATIC_PRELOAD_INCLUDE="*.js,*.css" \
STATIC_PRELOAD_EXCLUDE="*.map,vendor-*" \
bun run server.ts
# Debug mode with verbose logging
STATIC_PRELOAD_VERBOSE=true bun run server.ts
Environment Variables:
PORT: Server port (default: 3000)STATIC_PRELOAD_MAX_BYTES: Maximum file size to preload in bytes (default: 5242880 = 5MB)STATIC_PRELOAD_INCLUDE: Comma-separated glob patterns for files to includeSTATIC_PRELOAD_EXCLUDE: Comma-separated glob patterns for files to excludeSTATIC_PRELOAD_VERBOSE: Enable detailed logging (set to "true")
Example Output:
📦 Loading static assets from ./dist/client...
Max preload size: 5.00 MB
📁 Preloaded into memory:
/assets/index-a1b2c3d4.js 45.23 kB │ gzip: 15.83 kB
/assets/index-e5f6g7h8.css 12.45 kB │ gzip: 4.36 kB
💾 Served on-demand:
/assets/vendor-i9j0k1l2.js 245.67 kB │ gzip: 86.98 kB
✅ Preloaded 2 files (57.68 KB) into memory
🚀 Server running at http://localhost:3000
For a complete working example, check out the TanStack Start + Bun example in this repository.