Build settings
This page covers changing how your project builds after import: build command, output directory, production branch, and framework — and the workflow PR that some changes open in your repo.
Prerequisite: a project.
What you can change
Open your project's Settings tab (/projects/<id>/settings):
| Field | What it does |
|---|---|
| Build command | The command the workflow runs (e.g. npm run build) |
| Output directory | Where the built site lives (e.g. out, dist) |
| Production branch | The branch whose pushes trigger deploys (defaults to main) |
| Framework | Next.js (static export), Next.js, React (Vite), Vue, Nuxt, or Static HTML |
| Deploy target | IPFS (the only option for now) |
If the panel shows "Unlock your encryption key" instead of the form, sign the unlock prompt on the Overview tab first — build settings live inside your project's encrypted record, so editing them needs the key.
Saving can open a PR in your repo
Your build configuration is baked into the deploy workflow file committed in your repo. When you save a change that alters that file (build command, output directory, branch, framework), the app regenerates it and opens a pull request in your repo with the update. Until you merge it, deploys keep using the old configuration — a Finish setup card on the Settings page links to the pending PR, and Merge & deploy merges it and kicks off a deploy in one click.
If your change doesn't affect the workflow file, no PR opens and the save just applies.
If saving succeeds but the workflow update fails (you'll see a warning saying deploys use the previous build config), click Save again to retry.
Changing the production branch
After the branch-change PR merges, deploys trigger on pushes to the new branch only. Pushes to the old branch stop deploying; anything already in-flight finishes normally.
Framework is sticky — use Re-detect
The framework set at import (or by you) never auto-updates, so a refactor in your repo can't silently change how your site builds. If your repo has changed framework (say you migrated to Next.js), click Re-detect from repo:
- The app inspects your repo at the current branch head
- A diff shows only what changed (e.g. "Framework: Static HTML → Next.js")
- Apply fills the form — review it, then Save as usual (Apply alone saves nothing)
Verification
- The Settings form reflects your saved values after a reload
- If a PR was opened: it's merged and the Finish setup card is gone
- The next deploy uses the new configuration (check the build command in the Actions log)
What can go wrong
| Symptom | Cause | Fix |
|---|---|---|
| Saved a change but deploys behave as before | The workflow PR isn't merged | Merge it — Merge & deploy in the app, or on GitHub |
| Build fails right after changing settings | The new command or output dir doesn't match the repo | Check the Actions log; Re-detect from repo to get back to known-good values |
| Settings tab asks for an unlock | Encryption key isn't unlocked in this browser | Sign the unlock prompt on the Overview tab |