> ## 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 Next.js

> Deploy a Next.js 16 application to Sevalla from a Git repository with next build and next start, or publish a static export as a free static site.

A Next.js application runs on Sevalla as an application: Nixpacks runs `next build` from your Git repository, and the web process runs `next start`, the Next.js server, which supports every Next.js feature. A site that needs no server can instead be [exported to static files](#deploy-a-static-export) and published as a static site.

## 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 default options (TypeScript, Tailwind CSS, ESLint and the App Router):

```bash theme={null}
npx create-next-app@latest storefront --yes
cd storefront
```

The project comes with a `.gitignore`, a Git repository and the scripts Sevalla uses: `build` runs `next build` and `start` runs `next start`.

## Prepare the project for Sevalla

Pin the Node.js version:

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

Nixpacks, the default [build strategy](/applications/builds/nixpacks), installs Node.js 18 without it, and Next.js 16 needs Node.js 20.9 or later.

Nothing else needs to change. `next start` takes its port 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.

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

<Steps>
  <Step title="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.
  </Step>

  <Step title="Deploy">
    Click the **Overview** tab, then click **Deploy now** under **Recent deployments**. Check the **Branch** and click **Deploy**.
  </Step>

  <Step title="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](/applications/deployments#deploy-automatically-on-push).
  </Step>
</Steps>

## 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 Next.js starter page opens.

<Frame>
  <img className="block dark:hidden" src="https://assets.sevalla.com/screenshots/light/app-overview-address.png" alt="The application header with its name, Running status, repository, branch and the domain that opens the application" width="1192" />

  <img className="hidden dark:block" src="https://assets.sevalla.com/screenshots/dark/app-overview-address.png" alt="The application header with its name, Running status, repository, branch and the domain that opens the application" width="1192" />
</Frame>

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). A build that stops with a message about the Node.js version means `engines.node` isn't set.

## 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. Next.js reads server-side variables at runtime, but it writes variables that start with `NEXT_PUBLIC_` into the JavaScript bundle during `next build`, so keep **Available during buildtime** selected for them and deploy again after you change one. See [Environment variables](/applications/environment-variables).

## Cache pages and assets

Next.js gives the files under `/_next/static/` content hashes, so they're safe to cache for a long time. Turn on the CDN on the application's **Networking** tab to serve static assets from Cloudflare's servers, and edge caching to serve rendered pages from there too. Edge caching suits pages that are the same for every visitor. See [CDN and edge caching](/applications/caching).

## Deploy a static export

When every page can be built ahead of time, Next.js can export the site to HTML, CSS and JavaScript files, and Sevalla publishes them as a [static site](/static-sites/overview), free up to 100 GB of bandwidth a month. A static export doesn't support features that need a server, such as Server Actions, Proxy (formerly middleware), cookies and Incremental Static Regeneration. See the [list of unsupported features](https://nextjs.org/docs/app/guides/static-exports#unsupported-features).

Set the output mode in `next.config.ts`:

```ts next.config.ts theme={null}
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  output: "export",
  trailingSlash: true,
  images: { unoptimized: true },
};

export default nextConfig;
```

| Option | Why |
| - | - |
| `output: "export"` | `next build` writes the site to the `out` folder. |
| `trailingSlash: true` | Each page becomes `about/index.html`, which a static site serves at `/about`. Without it, Next.js writes `about.html`, and `/about` returns `404` unless you turn on [pretty URLs](/static-sites/redirects#pretty-urls). |
| `images: { unoptimized: true }` | The `next/image` component can't optimize images without a server. |

Push the change, then create the static site:

<Steps>
  <Step title="Choose the repository">
    In the sidebar, click **Static sites**, then click **Create static site**. Under **Source**, click **Private repository**, then choose the **Git provider**, the **Repository** and the **Branch**.
  </Step>

  <Step title="Check the build settings">
    Under **Build settings**, Sevalla shows **Framework detected: Next.js** and fills in the values. Check them:

    | Field | Value |
    | - | - |
    | **Build site before publishing** | On |
    | **Node version** | **Latest LTS** |
    | **Build command** | `npm run build` |
    | **Root directory** | Empty, for the repository root |
    | **Publish directory** | `out` |
  </Step>

  <Step title="Create the static site">
    Enter a **Name** under **Details**, then click **Create static site**. Sevalla starts the first deployment right away, and deploys every push to the branch while **Auto-deploy** is on.
  </Step>
</Steps>

When the deployment's status changes to **Deployed**, click **Visit site** on the static site's **Overview** tab. If the deployment fails, see [Troubleshoot static sites](/static-sites/troubleshooting). See [Build settings](/static-sites/build-settings) for every field.

## 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. Static sites have a **Domains** tab too. 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 code with `process.env.DB_URL`.


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