Unable to run preview or deploy TanStack Start app with SSR (Coolify self-host)

[Nodzimo]

Which project does this relate to?

Start

Describe the bug

Hi! I have a question about running and deploying a TanStack Start app with SSR.
I wanted to start my new project using TanStack Start, spent a few days trying — but I couldn’t even get the preview server to run or deploy the app to Coolify.
The documentation and examples are very confusing and unclear, in my opinion. I’ve re-read them multiple times, but nothing worked.

1. Preview / Production build problem

I created a project using:
bun create @tanstack/start@latest

In the prompts, I chose the standard setup:

• Tailwind
• TanStack Query, Form, Table
• Hosting: none (because I’m self-hosting via Coolify)

The project scaffolds correctly, bun dev works, and the app runs fine in the browser.

But how do I run it in preview / production mode?

When I run:
vite preview

and open http://localhost:4173, I get:
Cannot GET /

Browser console:
GET http://localhost:4173/ 404 (Not Found)

How am I supposed to start the preview server and test SSR/SSG?
For example, in Next.js this works out of the box with next start.
There’s no clear documentation explaining how to run a production preview for TanStack Start.

2. Deploying to Coolify (self-hosted PaaS)

I’m hosting apps on Coolify, which is basically a self-hosted Vercel:

Next.js apps deploy there perfectly — one click, no manual configuration.

But when I try to deploy the same TanStack Start project to Coolify, the app builds and deploys — but opening it in a browser gives:
GET https://domain-example.com/ net::ERR_HTTP_RESPONSE_CODE_FAILURE 404 (Not Found)

So what should I do to deploy TanStack Start just like Next.js?

I’ve read the Hosting section of the docs several times, but I still don’t understand what exactly is required for deployment:

• Is the Nitro plugin required?
• If yes, should I use the bun preset?
• If yes, what comes next?

Why does only dev mode work, but preview and deployed builds fail?

3. Attempt with Nitro plugin

I tried copying the server implementation example from the documentation,
installed the @tanstack/nitro-v2-vite-plugin with the nitroV2Plugin({ preset: 'bun' }), and ran: ASSET_PRELOAD_VERBOSE_LOGGING=true bun run server.ts

The server starts and responds, but the app loads without any styles (plain HTML), screen:

Repository: https://github.com/Nodzimo/tss-dep
Here’s the repo I’m trying to run in preview and deploy via Coolify.

Summary

I really wanted to start my new project on TanStack Start, but after a few days of trying I simply couldn’t get it to start — not in preview, not in production.
dev mode works perfectly, but everything else fails.

Please help clarify how this is supposed to work,
and whether deploying on self-hosted platforms like Coolify is currently supported.

Thanks 🙏

Your Example Website or App

https://github.com/Nodzimo/tss-dep

Steps to Reproduce the Bug or Issue

1. bun create @tanstack/start@latest
2. "preview": "vite preview" / Deploy to Coolify
3. Error: Cannot GET /

Expected behavior

As a developer, I expected to be able to run a production preview or deploy the app somewhere without needing divine intervention.

Ideally, I’d also expect TanStack Start to actually... well, start 😅

Screenshots or Videos

No response

Platform

• @tanstack/react-start: 1.132.0
• OS: Windows
• Browser: any
• Browser Version: latest
• Bundler: vite
• Bundler Version: 7.1.7

Additional context

No response

[onlywei]

I'm very confused by this as well. How do I run the tanstack start app in NON-dev mode? In the docs there's a vite build script, but what do we do after we run vite build...?

I browsed the dist directory that got created after vite build, and I found a dist/server/server.js, but running node dist/server/server.js doesn't start the server at all.

[Nodzimo]

running node dist/server/server.js doesn't start the server at all.

Same here — I get exactly the same behavior.
After running vite build, I can see dist/server/server.js, but running
node dist/server/server.js just exits immediately with Process finished with exit code 0 and nothing starts.

So far I haven’t found a way to make the app actually run in non-dev mode either.

[onlywei]

@Nodzimo I got the answer on the discord. The answer is that Tanstack Start is unopinionated when it comes to which production server you want to use. The vite build step produces a module that you can import into whatever server you want -- Express, Fastify, Nitro, etc. Here's their example of them doing it Express.

I'm going to use Fastify.

Another thing I'll note is that I'm not going to do that whole if (DEVELOPMENT) block you see in their example. I'm still going to use vite dev for development, and only use my Fastify server for staging/production.

[chiroro-jr]

Wouldn't it be better to provide a default production server or something. I spent hours trying to figure out why node ./dist/server/server.js was just exiting. I don't think anything is said about this in the docs too.

[jvst-aj]

For anyone else having the same problem and are confused as well, here is what I understood by doing some research and exploring some examples online. Please take it with a grain of salt since I'm not a fucking expert and I could be wrong, but I hope this helps you to understand better how things work on Tanstack Start and lay out some expectations.

First, let's remember that Start is built on top of Vite, which is both a development server and build tool. This is important to have in mind, since Vite provides you with a good development experience with features like Hot Module Replacement (HMR) and also allows you to create a production build that allows you to deploy static sites or SPAs. However, Vite is not meant to be used as a production server that supports SSR - that's why we have Tanstack Start that provides that SSR functionality on top - but we still need to integrate Vite with another tool that acts as the production server to deliver that SSR functionality from our Start application, and since Tanstack Start is built on top of Vite, well, it inherits the need for that integration too. You can read more about it here: https://vite.dev/guide/ssr.html

Now, Tanstack Start is unopinionated about the production server to be used, so it's up to you to decide what to choose. What Tanstack Start build output does (vite build), is to create a handler that will be the entry point to all the business logic your application supports, that's what "./dist/server/server.js" exports, but how you expose that logic to the public is up to you. That handler is basically a function that could be converted to a handler that works on any environment such as Node; and once you are done with that, you can attach that handler to any Node server, such as Express. This way, the handler will serve as middleware for your Express application and Express is just going to redirect requests to it. Vite has a middleware mode for this purpose, which I guess tells vite "Hey you are not the main server, so setup things accordingly to delegate main server tasks to someone else (such as exposing ports I guess)".

Here is an example of how to setup all of this with Express, I've commented the code for further explanation and link references to vite docs.

// server.ts (root)
import express from "express"
import { toNodeHandler } from "srvx/node"

// Detect environment
const DEVELOPMENT = process.env.NODE_ENV === "development"
const PORT = Number.parseInt(process.env.PORT || "3000")

// Create express app
const app = express()

if (DEVELOPMENT) {
  // Vite is imported dynamically only when DEVELOPMENT is true.
  // That avoids bundling or requiring Vite in production, since we don’t need it there.
  const vite = await import("vite")

  // Create vite server in middleware mode
  // See: https://vite.dev/config/server-options.html#server-middlewaremode
  const viteDevServer = await vite.createServer({
    server: { middlewareMode: true },

    // Disable Vite's own HTML serving logic.
    // This allows your custom Express server to control routing and SSR.
    // See: https://vite.dev/guide/ssr.html#setting-up-the-dev-server
    appType: "custom",
  })

  // Use vite's connect instance as middleware for express
  // This enables Vite to intercept requests, compile modules on the fly,
  // and provide HMR (Hot Module Replacement) in development.
  // See: https://vite.dev/guide/ssr.html#setting-up-the-dev-server
  app.use(viteDevServer.middlewares)

  app.use(async (req, res, next) => {
    try {
      // Dynamically load the SSR server entry on each request.
      // This allows hot reload of server code in development.
      const { default: serverEntry } =
        await viteDevServer.ssrLoadModule("./src/server.ts")

      // Convert TanStack Start's fetch-style handler to an Express handler.
      const handler = toNodeHandler(serverEntry.fetch)

      // Handle the request with the SSR handler
      await handler(req, res)
    } catch (error) {
      // Fix stack traces so Vite points to original source code
      if (typeof error === "object" && error instanceof Error) {
        viteDevServer.ssrFixStacktrace(error)
      }
      next(error)
    }
  })
} else {
  // Import the prebuilt SSR handler from the production build.
  const { default: handler } = await import("./dist/server/server.js")

  // Convert TanStack Start's fetch-style handler to an Express handler.
  const nodeHandler = toNodeHandler(handler.fetch)

  // Serve static assets (JS, CSS, images) from the built client directory.
  app.use(express.static("dist/client"))

  // Handle all other requests via SSR.
  // Any request not matched by static assets will be rendered
  // using the TanStack Start server handler.
  app.use(async (req, res, next) => {
    try {
      await nodeHandler(req, res)
    } catch (error) {
      next(error)
    }
  })
}

// Boot server
app.listen(PORT, () => {
  console.log(`Server is running on http://localhost:${PORT}`)
})

And here are my scripts on package.json file:

    "dev": "cross-env NODE_ENV=development tsx server.ts",
    "build": "vite build",
    "start": "cross-env NODE_ENV=production tsx server.ts",

Please, do not confuse my root server.ts file (the one that my package.json scripts run), with Tanstack Start server.ts inside src directory, these are different files but it just happened I just called them the same. You can name the root server.ts file however you want, just make sure to update your package.json scripts accordingly.

The server.ts file inside src directory should contain the below code as per the docs say (See: https://tanstack.com/start/latest/docs/framework/react/guide/server-entry-point), and is the file that is gonna be loaded as the SSR module on development by our ROOT server.ts file.

// src/server.ts
import handler from '@tanstack/react-start/server-entry'

export default {
  fetch(request: Request) {
    return handler.fetch(request)
  },
}

Hope this helps:)

[jwtrhs]

I followed the example from https://tanstack.com/start/latest/docs/framework/react/guide/hosting#nitro and came up with this for my vite.config.ts:

import { tanstackStart } from "@tanstack/react-start/plugin/vite";
import viteReact from "@vitejs/plugin-react";
import { nitro } from "nitro/vite";
import tsConfigPaths from "vite-tsconfig-paths";
import { defineConfig } from "vitest/config";

export default defineConfig(({ mode }) => ({
  plugins: [
    tsConfigPaths({ projects: ["./tsconfig.json"] }),
    tanstackStart({ srcDirectory: "src" }),
    mode === "production" ? nitro() : null, // Using the nitro plugin breaks vitest, so only enable it in production
    viteReact(),
  ],
}));

I found running vitest would crash with the nitro plugin, so I only load it in production mode (i.e. when building the production bundle).

With this config, I can successfully do pnpm build and node .output/server/index.mjs to start the production server.

[onlywei]

I made a Fastify plugin to use Fastify as the production server: https://www.npmjs.com/package/fastify-tanstack-start