How to Deploy TanStack Start with Docker and Bun
Tanstack Start is quickly becoming the go to framework for developers who want the power of Tanstack Router with full stack capabilities. It's bleeding edge, it's fast, and the DX is incredible.
But let's be real: moving from npm run dev on your laptop to a robust, containerized production environment is where the headaches usually start.
In this guide, we aren't just going to "make it run". We are going to build a high performance deployment pipeline using Docker and Bun. We will implement a custom asset server that caches files in RAM, handles compression, and serves your app at lightning speeds.
0. The Prerequisite (Don't Skip This!)
Before we touch a single Dockerfile, there is one crucial requirement.
According to the official Tanstack Start documentation, deploying with Bun currently requires React 19. If your project is still on React 18, the server might crash or behave unpredictably.
Make sure to upgrade your dependencies first:
Ready? Let's build.
1. The Foundation: Vite Configuration
First, we need to make sure Vite is ready for production. We want to ensure our path aliases (like @/components) work correctly and that we strip out console logs so our production logs stay clean.
Here is the vite.config.ts setup:
2. The Secret Sauce: A Custom Bun Server
This is the cool part. We aren't just going to run node server.js. We are going to use a custom script that leverages Bun's native speed.
This script (based on the official reference implementation) acts as a smart asset server. it loads samll files (like icons, CSS, and small JS chunks) directly into memory (RAM).
Why?
Create a file named server.ts in your project root and paste this in:
(Make sure to use the full server.ts code provided in the materials section to get the full caching benefits!)
3. The Dockerfile: Small & Efficient
We will use a Multi-Stage Build. This keeps our final Docker image tiny because we don't include all the build tools (like Typescript or Vite) in the final container, only what's needed to run the app.
Key Technical Detail: Pay attention to the ARG section. Vite needs environment variables (like your API URL) available during the build process to "bake" them into the client-side Javascript.
4. Orchestration: Docker Compose
Finally, let's tie it all together. Using Docker Compose makes it easy to manage environment variables and ports.
We also added a healthcheck. This ensures that if the server crashes or hangs, Docker knows about it and can restart it automatically.
Conclusion
And there you have it. You aren't just running a development server in a container. You have a highly optimized, memory-caching, Bun-powered production environment.
Quick Recap:
Now, just create your .env file, run docker compose up --build -d, and watch your Tanstack Start app fly!