> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sevalla.com/llms.txt
> Use this file to discover all available pages before exploring further.
> ## Agent Instructions
> These are the docs for Sevalla, a platform for deploying applications, databases, static sites, object storage and load balancers. The dashboard is at https://app.sevalla.com.
> Bold text in steps is an exact dashboard label.
> To act on a Sevalla account, prefer the Sevalla MCP server (https://mcp.sevalla.com/mcp, see https://docs.sevalla.com/ai-agents/overview.md), then the Sevalla CLI (https://docs.sevalla.com/developer-tools/cli.md), then the REST API (https://api-docs.sevalla.com, OpenAPI spec at https://api.sevalla.com/v3/openapi.json).
> Every page index is at https://docs.sevalla.com/llms.txt.
# Deploy TanStack Start
> Deploy a TanStack Start application to Sevalla from a Git repository with the Nitro Node.js server, a start script and NIXPACKS_SPA_CADDY set to false.
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](/git/overview).
* Node.js 24 or later on your computer.
## Create the project
Create a project with the TanStack CLI and its Nitro deployment adapter:
```bash theme={null}
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:
```ts vite.config.ts theme={null}
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:
```bash theme={null}
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](/applications/builds/nixpacks), 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](/guides/javascript/overview#pin-the-node-js-version). |
The Nitro server takes its port from `NITRO_PORT` or, when that isn't set, from [`PORT`](/guides/javascript/overview#listen-on-the-port-environment-variable), 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](#deploy-to-sevalla).
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:
```bash theme={null}
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
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.
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**.
Click the **Overview** tab, then click **Deploy now** under **Recent deployments**. Check the **Branch** and click **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](/applications/deployments#deploy-automatically-on-push).
## Verify the deployment
1. 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**.
2. Click the domain under the application's name, for example `storefront-x7k2m.sevalla.app`. The starter's home page opens, rendered on the server.
If the deployment fails, open it on the **Deployments** tab and read its build log, then see [Troubleshoot builds and deployments](/applications/troubleshooting/builds-and-deployments). If the [runtime logs](/applications/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](/applications/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](/applications/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](/applications/scaling) the web process first. See [Custom domains](/domains/overview).
## Connect a database
Create a [database](/databases/create) in the same location as the application, then [connect the application to it](/databases/connect#connect-an-application) 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](/databases/connect#environment-variables-an-internal-connection-adds)), and they apply at the next deployment. Read them in server functions with `process.env.DB_URL`.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.