Deploy a static site with a push

Which projects it detects

If your repository has a package.json with a build script and one of these tools, it recognizes the project on its own: Vite, Create React App, Vue CLI, Angular, Astro, Gatsby, Docusaurus, Eleventy, VuePress or Parcel. If there is no package.json but there are HTML files, it publishes the folder as it is.

How it is built

1. It picks the package manager from your lock file: pnpm-lock.yaml, yarn.lock, bun.lock or package-lock.json.
2. It uses the Node version from .nvmrc, .node-version or engines.node (18, 20, 22 or 24); if you do not ask for one, it uses Node 22.
3. It installs the dependencies following the lock file and runs build.
4. It looks for the output in the framework’s own folder or, if that is missing, in dist, build, out, public or _site.

What you can change

In the app’s advanced settings you can set the install command, the build command, the output folder and whether the site is a single-page application (SPA). If you set the output folder and it does not exist, the build fails with a clear message instead of guessing another one.

How it is served

• Over HTTPS from the first deployment.
• In an SPA, routes that are not files return index.html; a file that does not exist answers 404.
• HTML is always revalidated, so a new deployment shows up right away; files with a hash in the name (for example app-3f9a1c2b.js) are cached as immutable.
• Files that start with .env or .git are not served.

Environment variables in the build

Only variables with a public prefix are passed to the build: VITE_, REACT_APP_, NEXT_PUBLIC_, PUBLIC_ and GATSBY_. The rest of your variables reach neither the build nor the final image.

If the build fails

The log shows the cause and what to do. The most common cases: the package.json has no build script; the lock file does not match the package.json (run the install on your machine and push the updated file); or the build does not produce an output folder with files (set it in the advanced settings).

Other guides

• Deploy an app with a Dockerfile — Your container as is: port, health check, logs and limits.
• Use your own domain — The DNS records to create and how the HTTPS certificate is issued.
• One deployment per branch — Each linked branch with its own address and, if you want, its own domain.