Build settings, environment variables and failed builds

You can change build settings under Build and deployment on your project's Settings screen, and environment variables on the Environment Variables screen. Changed settings and variables apply from the next deployment. Deployments that have already finished are not affected, so start a new deployment or redeploy to apply them right away.

Which build settings can I change?

• Framework: choosing one fills in that framework's default build command and output directory.
• Root directory: set this when your app lives in a folder other than the repository root.
• Install command: leave it empty and we pick one automatically from your lockfile.
• Build command: the command to run for the build.
• Output directory: the folder where static files end up after the build. Its contents are what gets deployed.
• Node.js version: choose 18, 20 or 22.
• SPA fallback: sends paths that do not exist to index.html. Turn it on for apps that use client side routing.

How is the package manager chosen?

If the install command is empty, we decide based on your lockfile.

• pnpm-lock.yaml present: pnpm install --frozen-lockfile
• yarn.lock present: yarn install
• bun.lockb or bun.lock present: bun install
• package-lock.json present: npm ci
• Only package.json, no lockfile: npm install

We look for the lockfile in the root directory first, then in the repository root. If you need something different, enter the install command yourself.

How do I deploy a monorepo?

When importing the repository, enter the folder that contains your app (for example apps/web) as the root directory on the Configure project screen and click Detect again. The framework is then detected again from that folder's package.json. You can also import the same repository several times as separate projects, each with a different root directory.

How do I add environment variables?

On the Environment Variables screen, click Add variable, or use Paste .env to add the contents of a .env file all at once.

• Applies to: choose Production, Preview or both. For Preview you can name a specific branch; leave it empty to apply to every preview branch.
• Secret: once saved with this on, the value can no longer be viewed on screen. To change it, enter a new value.
• Naming rules: only letters, numbers and underscores (_) are allowed, and the name cannot start with a number. Some names used by the build environment, such as PATH and HOME, and names starting with PX_ cannot be used.

Environment variables are injected at build time. Because your site is deployed as static files, any value that ends up in the build output can be visible in visitors' browsers. Do not use keys that must stay private in your frontend code.

Where can I see the build logs?

Click a deployment in the deployment list to open its details, which include the Build logs. They update live while the build runs, and Copy logs copies everything.

My build fails

Start with the error at the bottom of the log. The most common causes are:

1. Output directory missing or empty: the build ran but there are no files in the output directory you set. Point it at the folder your framework actually writes to. For example, Angular 17 and later outputs to dist/<project name>/browser.
2. Next.js server features: without output: 'export' in next.config, or when using SSR, API routes or middleware, a static export is not possible.
3. Output over the limit: a single deployment's output can be up to 500MB and 20,000 files. Leave out large videos or source files.
4. Build timeout: each plan has a build timeout (Free 10 minutes, Pro 30 minutes, Ultra and above 45 minutes).
5. Lockfile out of sync: npm ci and pnpm install --frozen-lockfile fail if package.json and the lockfile do not match. Update the lockfile locally and commit it.
6. Missing environment variables: check that the variables your build needs exist for the right target (Production or Preview).

After fixing the settings, push again or use Redeploy from the deployment menu to rebuild the same commit.

My build is stuck on "Queued (build slot)"

All of your plan's concurrent build slots are in use. This is not an error: the build starts automatically as soon as an earlier build finishes and a slot frees up. You can also free a slot by stopping a less urgent build with Cancel deployment.

I pushed but no deployment was created

• If the commit message contains [skip deploy], [skip ci] or [ci skip], that push is not deployed.
• If Automatic deploys is off in Settings, pushes do not deploy. Deploy manually from the Deployments tab.
• If Preview deployments is off, branches other than the production branch are not deployed.
• For security, pull requests from forked repositories are not deployed.
• New deployments are also blocked once you have used your deployment limit for the last 24 hours or are over your project limit. See Plan limits, access tokens and projects.

If you need help

Open a support request, choose Parallax Cloud as the service, and include the project name, the ID or address of the failed deployment and the error part of the build log. If any secret values appear in the log, remove them before sending. We will never ask for your access tokens or secret values.