OrbitsDocs
esc
    Open Orbits
    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

    SettingWhat it doesDefault
    FrameworkWhich framework the app uses, for defaults and the label on the project.Detected
    Node.js versionThe Node.js version for the build and the app.22
    Root directoryThe app's folder in the repository. Commands run there, and the output directory is relative to it../
    Install commandInstalls dependencies.From the lock file
    Build commandBuilds the app.Your build script
    Output directoryFor a static site, the folder of files to serve.Per framework
    Skip a build whenThe 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:

    Terminal
    $ git diff --quiet HEAD^ HEAD -- ./apps/storefront

    git 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;
    • git and the Node.js image the build uses;
    • ORBITS_GIT_COMMIT_SHA, ORBITS_GIT_COMMIT_REF (the branch) and ORBITS_ENV (production or preview), and the same values as VERCEL_GIT_COMMIT_SHA, VERCEL_GIT_COMMIT_REF and VERCEL_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:

    VariableValue
    CI1
    SITE_URLThe 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_URLKeys 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.

    Was this page helpful?

    Updated