Configuring your build command and output directory
Configuring your build command and output directory
Getting Orbit to build your project correctly comes down to three fields in your project Settings: Build command, Output directory, and Install command. When left blank, Orbit auto-detects sensible defaults, but many first-deploy failures happen because the auto-detected values do not match your framework's actual output.
Where to find the settings
Navigate to Orbit -> [your project] -> Settings and scroll to the Build settings section. You will see five fields:
| Field | What it does | Example default |
|---|---|---|
| Install command | How to install dependencies before building | npm ci |
| Build command | The command that produces your output | npm run build |
| Output directory | The folder Orbit publishes after the build | dist |
| Root directory | For monorepos - the subdirectory that contains your app | (blank = repo root) |
| Node.js version | Major Node version to use | 20 |
Leave any field blank to let Orbit auto-detect. Save the section by clicking Save at the bottom of the Build settings card.
Framework defaults
Next.js
Next.js has two modes in Orbit: static export and server mode.
Static export (output: 'export' in next.config.js):
- Build command:
npm run build - Output directory:
out
Server mode (SSR/ISR) - this is most Next.js apps:
- Enable the Server mode toggle in Settings under the Runtime section
- Build command:
npm run build - Output directory:
.next(Orbit handles the rest automatically) - Without server mode enabled, your Next.js app will be served as static files and dynamic routes will 404.
Astro
Astro's output depends on your output setting in astro.config.mjs:
output: 'static'(default): output directory isdistoutput: 'server'oroutput: 'hybrid': requires server mode on and output directorydist- Build command:
npm run build(default) orastro build
Vite (React, Vue, Svelte)
- Build command:
npm run buildorvite build - Output directory:
dist - Vite always outputs to
distby default unless you have overriddenbuild.outDirinvite.config.ts.
Plain HTML / static sites
- Leave install command blank if you have no
package.json - Leave build command blank - Orbit will serve the root of your repo as-is, or set a custom build step if you use a static site generator
- Output directory:
.(the root) or whatever folder your generator creates
Create React App
Create React App was deprecated upstream and is not recommended for new projects, but if you have an existing project:
- Build command:
npm run build - Output directory:
build
Common gotchas
"Build succeeded but the site shows a 404" - Your output directory is wrong. Check what folder your build actually creates and set it explicitly. For Vite it is dist, for Next.js static export it is out, for Create React App it is build.
"Module not found" errors on first deploy - The install step did not run, or is running with the wrong package manager. Set the install command explicitly to npm ci, yarn install --frozen-lockfile, or pnpm install --frozen-lockfile.
Monorepo: only one app is deploying - Set the Root directory to the subdirectory of your app, for example apps/web. Orbit will change into that directory before running your install and build commands, and will skip deploys for pushes that only change files outside that path.
Wrong Node.js version - If your build needs a specific version, set the Node.js version field to the major version number only: 18, 20, or 22. Defaults to the latest LTS if blank.
Staging environment overrides
If your project has a staging environment, the Settings page shows a separate Staging: build overrides section. Any field left blank in that section inherits from the main Build settings. Use this to run a different build command in staging, for example npm run build:staging.