|Docs

Deploy a TanStack Start App

deploymentfrontendtanstackfullstack

TanStack Start is a full-stack React framework built on TanStack Router. It provides file-based routing, server functions, SSR, and streaming out of the box. TanStack Start uses Vinxi as its server runtime, which builds on Nitro.

This guide covers how to deploy a TanStack Start app to Railway in three ways:

  1. From a GitHub repository.
  2. Using the CLI.
  3. Using a Dockerfile.

Create a TanStack Start app

Note: If you already have a TanStack Start app locally or on GitHub, skip to Deploy the TanStack Start app to Railway.

Ensure Node is installed, then create a new project:

Follow the prompts to choose your preferred options.

Run the app locally

Open http://localhost:3000 to see your app.

Deploy the TanStack Start app to Railway

TanStack Start builds a Node.js server that handles SSR, server functions, and static asset serving. It deploys as a standard Node service on Railway.

Deploy from the CLI

  1. Install the Railway CLI:
  2. Initialize a Railway Project:
    • Run the command below in your TanStack Start app directory.
    • Follow the prompts to name your project.
    • After the project is created, click the provided link to view it in your browser.
  3. Deploy the Application:
    • Use the command below to deploy your app:
    • This command will scan, compress and upload your app's files to Railway. You'll see real-time deployment logs in your terminal.
    • Once the deployment completes, go to View logs to check if the service is running successfully.
  4. Set Up a Public URL:
    • Navigate to the Networking section under the Settings tab of your new service.
    • Click Generate Domain to create a public URL for your app.

Deploy from a GitHub repo

  1. Create a New Project on Railway:
    • Go to Railway to create a new project.
  2. Deploy from GitHub:
    • Select Deploy from GitHub repo and choose your repository.
      • If your Railway account isn't linked to GitHub yet, you'll be prompted to do so.
  3. Deploy the App:
    • Click Deploy to start the deployment process.
    • Once deployed, a Railway service will be created for your app, but it won't be publicly accessible by default.
  4. Verify the Deployment:
    • Once the deployment completes, go to View logs to check if the server is running successfully.
  5. Set Up a Public URL:
    • Navigate to the Networking section under the Settings tab of your new service.
    • Click Generate Domain to create a public URL for your app.

Use a Dockerfile

If Railpack does not detect the start command correctly, use a Dockerfile:

TanStack Start (via Vinxi/Nitro) builds into a .output directory. The server entry point is .output/server/index.mjs.

Deploy via the CLI or from GitHub. Railway automatically detects the Dockerfile and uses it to build and deploy the app.

Port configuration

TanStack Start's Vinxi server listens on port 3000 by default. To make it respect Railway's PORT variable, check your app.config.ts:

If the server does not bind to the correct port, set a custom start command:

Server functions

TanStack Start server functions run on the Node.js server, not in the browser. They can access environment variables, databases, and other server-side resources:

Server functions have access to all Railway service variables. Only variables with the VITE_ prefix are available in client-side code, since TanStack Start uses Vite. See Manage environment variables in frontend builds for details.

Add a Postgres database

  1. In your Railway project, click + New, then Database, then PostgreSQL.
  2. Add the connection string to your TanStack Start service:

Use an ORM like Prisma or Drizzle to query the database from server functions and loaders.

Next steps