Supported Frameworks and Runtimes In Orbit

Orbit builds any project that installs with npm, yarn or pnpm and produces a folder of files or a Node.js server, and it detects the framework and package manager for you so most projects deploy with no build configuration at all. This guide covers what gets detected, the settings each common framework needs, when you have to turn on server mode, and how to pick a Node.js version.

What Orbit Detects Automatically

When a build runs, Orbit records what it found and shows it back to you:

Framework, on the deployment detail page and as a badge on deployment cards on the project overview.
Package manager, chosen from your lockfile: package-lock.json gives npm, yarn.lock gives yarn, pnpm-lock.yaml gives pnpm.

The build settings in Settings are all optional. Leave a field blank and its placeholder tells you what will be used instead: Install command shows npm ci (auto-detected), Build command shows npm run build (auto-detected), and Output directory shows dist (auto-detected).

Build settings in Orbit project settings

Commit exactly one lockfile. If both package-lock.json and yarn.lock are in the repository, the package manager Orbit picks may not be the one you use locally, and you get an install that behaves differently from your machine for no visible reason. Delete the one you are not using.

Settings By Framework

These are the values each framework needs. Where Orbit ships a starter template for the framework, the template uses exactly these settings.

Framework	Build command	Output directory	Server mode
Next.js, static export	`npm run build`	`out`	Off
Next.js, SSR or ISR	`npm run build`	`.next`	On
Astro, static	`astro build`	`dist`	Off
Astro, server or hybrid	`astro build`	`dist`	On
Vite (React, Vue, Svelte)	`npm run build`	`dist`	Off
SvelteKit	`npm run build`	`build`	Depends on adapter
Nuxt 3	`npm run build`	`.output`	On
Remix	`npm run build`	`build`	On
Express or a plain Node API	`npm run build`	`dist`	On
Create React App	`npm run build`	`build`	Off
Plain HTML or a static generator	leave blank, or your generator's command	`.` or the folder it writes	Off

Vite always writes to dist unless you have set build.outDir in vite.config.ts. Astro's output folder is dist in every mode; what changes between modes is whether you need server mode, not where the files land.

Server Mode

Server mode is a toggle in Settings, under Runtime. When it is on, Orbit keeps the build machine alive running npm start after each deploy instead of serving a folder of static files.

Turn it on for Next.js with SSR, Remix, Nuxt, an Express API, and anything else that is not a static export. Leave it off for a genuinely static build.

It applies from the next deploy, not to the deployment that is currently live.

The classic symptom of a missing server mode is a site where the home page loads perfectly and every dynamic route returns a 404. The build succeeded, the files were published, and there is simply no server running to answer the routes. If that is what you are seeing, turn on server mode and redeploy before you change anything else.

Node.js Version

Set Node.js version in Settings under Build settings. Enter the major version number only: 18, 20 or 22. Leave it blank to use the platform default.

The version applies to both the build and, when server mode is on, the runtime.

Pin the version explicitly rather than relying on the default. A dependency that requires a newer Node than the default fails the install with an error that does not obviously say so, and pinning removes a whole class of "it worked yesterday" build failures.

Monorepos

Set Root directory to the subdirectory containing the app, for example apps/web. Orbit changes into that directory before running your install and build commands.

It also does something you want but might not expect: pushes that only change files outside that path are skipped automatically. A monorepo with four Orbit projects therefore rebuilds only the apps a commit actually touched.

Each environment can override the root directory separately, under Staging: build overrides in Settings, which is useful when staging builds a different workspace.

Custom Build Settings

Override anything in Settings, under Build settings:

Field	Example	Notes
Install command	`npm ci`	Or `yarn install --frozen-lockfile`, `pnpm install --frozen-lockfile`
Build command	`npm run build:prod`	Run exactly as written
Output directory	`dist/client`	The folder published after the build
Root directory	`apps/frontend`	Monorepo subdirectory
Node.js version	`20`	Major version only

Blank means auto-detect. Click Save on the Build settings card to apply.

Staging can override any of these independently, in the Staging: build overrides section. A field left blank there inherits the project-level value, so you can change just the build command for staging and leave everything else alone.

Build Cache

Orbit caches node_modules between builds on the Liftoff and Apex plans. When the cache is used, the deployment shows a Cache hit badge and the install phase is far shorter. A build without it shows Cold build.

To force a full reinstall, open Settings, then Clear build cache, and confirm. The next deployment for each environment runs a full install from scratch. This cannot be undone, and the build after it will be slow.

Build Machine Resources

The build machine size depends on your plan, which matters for large builds:

Plan	vCPU	RAM	Disk	Time limit
Launch	1	1 GB	4 GB	30 minutes
Liftoff	2	2 GB	8 GB	30 minutes
Apex	4	4 GB	16 GB	30 minutes

A build that runs out of memory or fills its disk fails with that failure category named on the deployment page. Raising NODE_OPTIONS=--max-old-space-size helps only up to the machine's actual RAM.

Starting From a Template

If you want a working deployment before you have a repository, use a starter template. On New project, switch from Import Git Repo to Start from Template and pick one: Next.js with shadcn/ui, an Astro marketing site, the Remix Indie Stack, a SvelteKit starter, a minimal Nuxt 3 app, or an Express REST API. Orbit copies the template, applies the right build settings, and deploys it.