> ## 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 JavaScript applications

> How Node.js, Bun and Deno projects run on Sevalla as applications or static sites: builds, the PORT variable, start commands and Node.js versions, with one guide per framework.

Sevalla runs JavaScript and TypeScript projects in two ways: as an [application](/applications/overview), a server built from your Git repository that runs on Node.js, Bun or Deno, or as a [static site](/static-sites/overview), the HTML, CSS and JavaScript files a build produces, served from Cloudflare's edge. The guides in this section take one framework each from an empty folder to a running deployment.

## Guides

| Guide | What you deploy | Hosted as |
| - | - | - |
| [Astro](/guides/javascript/astro) | An Astro site built to static files, or rendered on demand with the Node.js adapter | Static site or application |
| [Bun](/guides/javascript/bun) | An HTTP server on `Bun.serve()` | Application |
| [Deno](/guides/javascript/deno) | An HTTP server on `Deno.serve()`, built from a Dockerfile | Application |
| [EmDash](/guides/javascript/emdash) | The EmDash CMS with PostgreSQL, object storage and edge caching | Application |
| [Express](/guides/javascript/express) | An Express 5 server | Application |
| [Fastify](/guides/javascript/fastify) | A Fastify 5 server | Application |
| [NestJS](/guides/javascript/nestjs) | A NestJS 12 application | Application |
| [Next.js](/guides/javascript/nextjs) | A Next.js 16 application with `next start`, or a static export | Application or static site |
| [Nuxt](/guides/javascript/nuxt) | A Nuxt 4 application on Nitro's Node.js server, or a generated static site | Application or static site |
| [Puppeteer](/guides/javascript/puppeteer) | A Node.js service that drives headless Chrome, built from a Dockerfile | Application |
| [Remix](/guides/javascript/remix) | A Remix 3 application, or a React Router application upgraded from Remix 2 | Application |
| [SvelteKit](/guides/javascript/sveltekit) | A SvelteKit 3 application with the Node.js adapter | Application |
| [TanStack Start](/guides/javascript/tanstack-start) | A TanStack Start application on Nitro's Node.js server | Application |
| [Turborepo](/guides/javascript/turborepo) | Two applications from one Turborepo monorepo | Applications |
| [Object storage](/guides/javascript/object-storage) | Uploads, downloads and presigned URLs from Node.js with the AWS SDK | Any application |
| [Redis](/guides/javascript/redis) | A cache in a Sevalla Redis or Valkey database with ioredis | Any application |

## Application or static site

Choose by whether the project needs a server when a request arrives.

| | Application | Static site |
| - | - | - |
| What runs | A web process started by a command, such as `npm start` | No server: Cloudflare serves the files the build wrote |
| Use it for | Server-side rendering, API routes, authentication, WebSockets, background work | Sites that build to files: Astro by default, a Next.js static export, `nuxt generate`, Vite single-page apps |
| Built by | The application's [build strategy](/applications/builds/overview), Nixpacks by default | The static site build, with the **Node version** and **Build command** you set |
| Default domain | `*.sevalla.app` | `*.sevalla.page` |
| First deployment | Starts when you click **Deploy now** | Starts as soon as you create the static site |
| Cost | Billed by process size and usage, see [Pricing](/billing/pricing) | Free up to 100 GB of bandwidth and 600 build minutes a month |

## How Sevalla builds an application

New applications built from Git use Nixpacks 1.41, which reads `package.json`:

| Step | What Nixpacks does |
| - | - |
| Package manager | Uses the `packageManager` field. Without it, picks pnpm for `pnpm-lock.yaml`, Yarn for `yarn.lock`, Bun for `bun.lock` or `bun.lockb`, and npm otherwise. |
| Install | Runs `npm ci` (`npm i` without a `package-lock.json`), `pnpm i --frozen-lockfile`, `yarn install --frozen-lockfile` or `bun i --no-save`. Dev dependencies are installed too, so build tools in `devDependencies` work. |
| Build | Runs the `build` script, if there is one. |
| Start | Uses the `start` script, otherwise the file in `main`, otherwise `index.js`. |

Nixpacks sets `NODE_ENV=production` in the image. Environment variables marked **Available during buildtime** reach the build, so `NIXPACKS_*` variables such as `NIXPACKS_BUILD_CMD` and `NIXPACKS_START_CMD` change what it does (see [Nixpacks](/applications/builds/nixpacks)).

One case surprises framework users: when a project uses Vite with React, Vue, Svelte without SvelteKit, Preact, Lit, Solid or Qwik, Nixpacks treats it as a single-page app and serves the build output with Caddy instead of running the `start` script. Server-rendered frameworks built on Vite, such as TanStack Start, need the variable `NIXPACKS_SPA_CADDY` set to `false`.

You can switch to [Railpack](/applications/builds/railpack) (Beta), which installs the newest Node.js release that matches `engines`, or to a [Dockerfile](/applications/builds/dockerfile), on the application's **Settings** tab with **Update build strategy**. The Deno, Puppeteer and EmDash guides use a Dockerfile.

## Listen on the PORT environment variable

Sevalla sets the `PORT` environment variable in the web process to the process's port, `8080` by default, and sends every request for the application's domains to that port. Sevalla's value replaces a `PORT` variable that you set yourself. Your server must:

* Read the port from `process.env.PORT` (`Deno.env.get("PORT")` in Deno).
* Listen on all network interfaces (`0.0.0.0`), not on `localhost` or `127.0.0.1`.

| Server | Reads `PORT` | Listens on all interfaces |
| - | - | - |
| `next start`, Nitro (Nuxt, TanStack Start), SvelteKit `adapter-node`, `react-router-serve`, `Bun.serve()` | Yes | Yes |
| Express `app.listen(port)`, NestJS `app.listen(port)`, Node.js `server.listen(port)` | When you pass `process.env.PORT` | Yes |
| Astro `@astrojs/node` | Yes | Only with `server.host: true` in `astro.config.mjs` |
| Fastify | When you pass `process.env.PORT` | Only with `host: "0.0.0.0"` |
| `Deno.serve()` | When you pass `Deno.env.get("PORT")` | With `hostname: "0.0.0.0"` |

To use another port, update it on the application's **Networking** tab: under **Expose HTTP traffic**, click **Update port**. Sevalla then sets `PORT` to the new value. See [Networking](/applications/networking).

## Set the start command

The web process runs the start command of the image the build produced. With Nixpacks, that's the `start` script in `package.json`, which every guide sets. To run something else without changing the repository, open the application's **Processes** tab, open the web process's menu, click **Update process** and fill in **Custom start command**. The change applies at the next deployment. See [Processes](/applications/processes).

## Pin the Node.js version

Nixpacks installs Node.js 18 unless the project asks for another version, and the current releases of Astro, Next.js, Nuxt, SvelteKit, React Router, Remix, TanStack Start, Puppeteer and EmDash don't run on Node.js 18. Pin Node.js 24 in `package.json`:

```bash theme={null}
npm pkg set engines.node="24.x"
```

Nixpacks takes the version from the first of these that's set: the `NIXPACKS_NODE_VERSION` environment variable, `engines.node` in `package.json`, `.nvmrc`, then `.node-version`. It only resolves the major version: for a range, it picks the newest even major version the range allows, from 14 to 24, and installs one fixed release of it.

| Major version | Release Nixpacks 1.41 installs |
| - | - |
| 24 | 24.10.0 |
| 22 | 22.14.0 |

A range such as `^22.22.0` therefore gets Node.js 22.14.0, which frameworks that need 22.22 reject. Use `24.x`.

Static sites don't read `engines` or `.nvmrc`. Sevalla installs the **Node version** chosen in the static site's build settings, **Latest LTS** by default. See [Node versions](/static-sites/build-settings#node-versions).

## Build a static site

A static site build installs the dependencies with the package manager your lockfile names, runs the **Build command** in the **Root directory**, and publishes the **Publish directory**, which is relative to the root directory. See [How a build runs](/static-sites/build-settings#how-a-build-runs).

When you create a static site from a private repository, Sevalla reads `package.json` and fills in the build command and publish directory for the frameworks it recognizes, including Astro (`dist`), Next.js (`out`) and Nuxt (`.output/public`, built with `npm run generate`). See [Framework detection](/static-sites/build-settings#framework-detection) for the full list.

## Keep the application stateless

Each deployment starts new instances from a new image, so files written to an instance's disk are gone after the next deployment, and instances don't share memory when you run more than one. Keep state outside the process:

* Sessions and cached data in Redis: see [Use Redis from Node.js](/guides/javascript/redis).
* Uploaded files in object storage: see [Use object storage from Node.js](/guides/javascript/object-storage).
* Data in a [database](/databases/overview), reached over an [internal connection](/databases/connect).

When an application needs files on disk, attach [persistent storage](/applications/disks).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.