Deploy TanStack Start

A TanStack Start application runs on Sevalla as an application: Nixpacks runs vite build from your Git repository, the Nitro plugin turns the build into a Node.js server in .output/, and the web process starts that server on the port that Sevalla sets in the PORT environment variable.

Before you begin

A Sevalla company with a payment method, and a GitHub, GitLab or Bitbucket account for the repository. See Git providers.
Node.js 24 or later on your computer.

Create the project

Create a project with the TanStack CLI and its Nitro deployment adapter:

npx @tanstack/cli@latest create storefront --deployment nitro --package-manager npm -y
cd storefront

The CLI adds the nitro() plugin to vite.config.ts, which makes vite build produce a server Sevalla can run. The generated file has more plugins and options; the parts that matter look like this:

vite.config.ts

import { defineConfig } from "vite";
import { tanstackStart } from "@tanstack/react-start/plugin/vite";
import viteReact from "@vitejs/plugin-react";
import { nitro } from "nitro/vite";

export default defineConfig({
  plugins: [tanstackStart(), nitro(), viteReact()],
});

For a project created without the adapter, run npm install nitro and add the plugin the same way.

Prepare the project for Sevalla

Add the start script and pin the Node.js version:

npm pkg set scripts.start="node .output/server/index.mjs" engines.node="24.x"

Field	Why Sevalla needs it
`scripts.start`	Nixpacks, the default build strategy, runs `npm run build` (`vite build`) and then starts the web process with `npm run start`. The project has no `start` script until you add it.
`engines.node`	Nixpacks installs Node.js 24 instead of its default, Node.js 18. See Pin the Node.js version.

The Nitro server takes its port from NITRO_PORT or, when that isn’t set, from PORT, which Sevalla sets to the web process’s port (8080 by default), and listens on all network interfaces. One more setting goes on the application instead of in the repository: Nixpacks treats any project that uses Vite with React as a single-page app, serves dist with Caddy and ignores the start script. The variable NIXPACKS_SPA_CADDY set to false turns that off. You add it in the deployment steps. Run npm run build && npm start and open http://localhost:3000 to check the production build locally. Then commit everything and push it to your Git provider:

git init
git add .
git commit -m "Prepare for Sevalla"
git branch -M main
git remote add origin https://github.com/acme/storefront.git
git push -u origin main

Deploy to Sevalla

Create the application

In the sidebar, click Applications, then click Create > Application. Under Source, click Private repository, then choose the Git provider, the Repository and the Branch. Under Location, choose a Data center. Keep the Size at H1 or choose a larger one, then click Create application. The application opens on its Overview tab with the status Not deployed yet: creating an application doesn’t deploy it.

Add the environment variable

Click the Environment variables tab, then click Add environment variables. Enter NIXPACKS_SPA_CADDY as the key and false as the value, keep Available during runtime and Available during buildtime selected, and click Add environment variables.

Deploy

Click the Overview tab, then click Deploy now under Recent deployments. Check the Branch and click Deploy.

Turn on auto-deploy

To deploy every push to the branch automatically, click the Settings tab, then click Update auto-deploy in the Auto-deploy section. Turn on Auto-deploy and click Update auto-deploy. See Deployments.

Verify the deployment

On the Deployments tab, wait for the deployment’s status to change to Deployed. The application’s status next to its name changes to Running.
Click the domain under the application’s name, for example storefront-x7k2m.sevalla.app. The starter’s home page opens, rendered on the server.

The application header with its name, Running status, repository, branch and the domain that opens the application

If the deployment fails, open it on the Deployments tab and read its build log, then see Troubleshoot builds and deployments. If the runtime logs show Caddy starting instead of the Nitro server, NIXPACKS_SPA_CADDY is missing or wasn’t available during the build: add it and deploy again.

Deploy changes

With Auto-deploy on, every push to the branch starts a deployment; otherwise, click Deploy now for each change. Each deployment builds the image, then replaces the web process’s instances. See Deployments.

Use environment variables

Add configuration on the application’s Environment variables tab. Server functions read variables with process.env when they run. Vite writes variables that start with VITE_ into the client bundle during the build, so keep Available during buildtime selected for them. Variables apply at the next deployment. See Environment variables.

Add a custom domain

To serve the application from your own domain, such as shop.example.com, add the domain on the application’s Domains tab and create the DNS records that Sevalla shows. Custom domains need a web process larger than H1, so scale the web process first. See Custom domains.

Connect a database

Create a database in the same location as the application, then connect the application to it with Add environment variables to the application turned on. Sevalla adds DB_URL, DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME and DB_PASSWORD to the application (what each one holds), and they apply at the next deployment. Read them in server functions with process.env.DB_URL.

Migrate

JavaScript

Python

Before you begin

Create the project

Prepare the project for Sevalla

Deploy to Sevalla

Verify the deployment

Deploy changes

Use environment variables

Add a custom domain

Connect a database

​Before you begin

​Create the project

​Prepare the project for Sevalla

​Deploy to Sevalla

​Verify the deployment

​Deploy changes

​Use environment variables

​Add a custom domain

​Connect a database

Before you begin

Create the project

Prepare the project for Sevalla

Deploy to Sevalla

Verify the deployment

Deploy changes

Use environment variables

Add a custom domain

Connect a database