Build and deployBuild settings
Build settings
The install, build and output settings, the root directory, the Node.js version, skipping builds with an ignored build step, the build cache, and the warnings a deployment can carry.
Orbits fills in a project's build settings from what it detects when you import the repository. You change them on the Configure step, or later in the project's Settings under Build ("Orbits found these in package.json. Change them only if your build needs something different.").
Changes apply from the next deployment. Deployments already built keep the settings they were built with: redeploy to rebuild with the new ones. Changing settings is for owners and admins.
The settings
| Setting | What it does | Default |
|---|---|---|
| Framework | Which framework the app uses, for defaults and the label on the project. | Detected |
| Node.js version | The Node.js version for the build and the app. | 22 |
| Root directory | The app's folder in the repository. Commands run there, and the output directory is relative to it. | ./ |
| Install command | Installs dependencies. | From the lock file |
| Build command | Builds the app. | Your build script |
| Output directory | For a static site, the folder of files to serve. | Per framework |
| Skip a build when | The ignored build step, below. | None |
An empty field means "use the detected default". Through the API, sending null for a build field goes back to the default. The settings card shows who changed a setting last, and when.
Root directory
Set it to the folder that holds the app's package.json, such as apps/web. In a monorepo, the lock file and the packageManager field are still found at the repository root, so a pnpm or Yarn workspace installs as it should. The output directory must stay inside the root directory.
If Orbits finds nothing to deploy (no package.json, and no index.html to serve as it is), the build fails with "Nothing to deploy". Point the root directory at the app's folder.
Output directory
Only static sites use it: it's the folder the build writes the site to, like dist or build. If the build finishes without creating it, the deployment fails at Uploading with "No dist directory to serve". If the folder has no index.html, the build log says so and the home page answers 404.
Server apps don't use an output directory: they're run with their start command (see server apps).
Ignored build step
Skip a build when is a shell command Orbits runs after cloning, in the repository, before installing anything. If it exits with 0, the build is skipped: the deployment ends canceled, saying why, and nothing changes in production. Any other exit code builds as usual.
It's most useful in a monorepo, where every push builds every app made from the repository. To build an app only when its own folder changed:
$ git diff --quiet HEAD^ HEAD -- ./apps/storefrontgit diff --quiet exits 0 when nothing changed, so the build is skipped.
What the command gets:
- the repository, cloned two commits deep, so
HEAD^is the previous commit; gitand the Node.js image the build uses;ORBITS_GIT_COMMIT_SHA,ORBITS_GIT_COMMIT_REF(the branch) andORBITS_ENV(productionorpreview), and the same values asVERCEL_GIT_COMMIT_SHA,VERCEL_GIT_COMMIT_REFandVERCEL_ENV, so scripts written for Vercel work as they are.
It has two minutes. A command that runs longer is stopped and the commit builds. The project's own environment variables aren't given to it yet.
Build cache
Orbits keeps each project's package manager cache (npm, pnpm, Yarn or Bun) between builds, so installs after the first are faster. It's keyed by your lock file. If the cache can't be read, the build carries on without it.
The framework's own build cache, such as Next.js's .next/cache, isn't carried between builds.
To build without the cache, redeploy with Clean build instead of Use the build cache. That helps when a cached package is out of date or a build behaves differently from a clean checkout.
Environment variables at build time
The build gets the project's variables for its environment (Production for production deployments, Preview for previews). Frameworks bake variables meant for the browser into the build (NEXT_PUBLIC_*, VITE_* and the like), so changing one of those needs a redeploy to take effect.
Orbits also sets:
| Variable | Value |
|---|---|
CI | 1 |
SITE_URL | The address the build is for: the project's production address for production, the deployment's own address for a preview. A variable you set yourself wins. |
ORBITS_FLAGS, ORBITS_WORKFLOWS, ORBITS_API_URL | Keys for flags and workflows, and the API address. A variable you set yourself wins. |
A variable whose value contains a line break is skipped, with a line in the build log; multi-line values (such as a PEM key) aren't supported yet. See environment variables.
Deployment warnings
A deployment can build fine and still be missing something. Orbits checks two things and shows what it finds as warnings on the deployment's page. Neither fails the build.
Variables the code uses but the build didn't have
Before building, Orbits scans your source (not node_modules or build output) for the public variables frontends bake in:
import.meta.env.VITE_*process.env.NEXT_PUBLIC_*REACT_APP_*PUBLIC_*
Any it finds that weren't set for the deployment's environment, nor in a committed .env or .env.production, are listed under Missing variables:
VITE_SUPABASE_ANON_KEY and VITE_SUPABASE_URL are used in the code but not set for Production. The build bakes them in, so this deployment runs without them.
Your code may have a fallback, which is why it's a warning. To fix it, add the variables for that environment and redeploy.
A page that broke as it loaded
A few seconds after a deployment is ready, Orbits opens its home page in a browser to take the screenshot. If the page threw uncaught errors as it loaded (the first three are shown), or its first screen came out blank, the deployment says so: "The page threw an error" or "The page came out blank". A blank page with a missing-variable warning beside it usually means the app needs those variables to start.
A later screenshot replaces this check.
Through the API
Build settings are the build object on a project, and the Node.js version is node_version. See the projects API.