The build system

A deployment starts as a directory of source files and ends as a set of Functions plus a set of static assets. The build system is what happens in between, and it runs identically whether you pushed to Git, dropped a folder into the console, or ran gigadrive deploy.

Detection

Before anything is installed, the build works out what it is looking at: a config file at the project root if you have one, under any of the names Configuration lists, plus your dependency manifest, which is what identifies a framework. Frameworks are tried in priority order, every detector of a framework must match, and the first match wins.

The merge is all-or-nothing per section, which is the part that catches people out. One routes entry in your config replaces the framework's entire route table, and one functions entry replaces every entrypoint the framework would have generated. There is no per-route or per-Function override. env is the exception: it merges key by key with your value winning, and the merged map is then never applied to anything. Environment variables covers what does reach a build and a Function.

The last row is more forgiving than it sounds: an index.html at the root is enough to be treated as a static site, and the platform writes a two-line config for you and publishes the directory as edge assets.

The build sandbox

The build runs in a single-use sandbox, isolated from every other build, with npm, pnpm, yarn, bun, git, Composer and php-cli already installed. Nothing from a previous deployment is present except the build cache.

Source arrives one of three ways: a repository without submodules as a tarball with no .git directory, which is faster than cloning; a repository with submodules as a shallow clone; an uploaded ZIP unpacked in place. The Git access token is passed to individual commands rather than left in the environment, so your install and build scripts never see it.

Then, from the repository root so that workspace layouts resolve:

1. The package manager is detected from packageManager in package.json, then devEngines, then the lockfile, defaulting to npm. Composer runs too if a composer.lock is present.
2. Dependencies are installed with the frozen-lockfile form of that package manager, falling back to the unfrozen form if that fails.
3. The build runs, from your root directory. A string build script in package.json is run as <package manager> run build. If there is none, the build step is skipped and the project is packaged as it stands.

Read that third point twice. The build command is not configurable: no console field, no API field and no config key changes it, so control the build through your build script.

A build that fails on a recognisable transient network error is retried once. A build that has not finished within 25 minutes is stopped.

The build cache

The cache holds package-manager stores and framework incremental state, such as .next/cache. It never holds a completed build output, so a cached build still builds. The point is to skip the download and the recompute, not the work.

The cache key is a hash of the dependency state: your lockfile, the package manager and its declared version, the application, and the root directory. The Git ref and the build environment variables are not part of it, because nothing in the cache depends on them. Two consequences follow.

• Every branch of an application shares one cache, and rotating a secret never causes a cold build.
• A project with no lockfile gets no cache at all, because there is nothing stable to key on.

The whole thing is best effort. A corrupt archive, an exhausted quota or a failed upload is written to the deployment log and the build continues cold, so a cache problem never fails a deployment. Build cache covers the per-plan size limits and those log lines.

What a deployment contains

Packaging turns the built tree into an immutable artifact:

• Functions. One per entrypoint, each carrying its runtime, memory, maximum duration and the files its dependency trace pulled in.
• Static assets. Every file under your assets directory, uploaded to object storage and registered as either an exact path or a prefix covering a subtree.
• A route table. The mapping from request paths to Functions, assets, redirects and proxy targets.
• Hostnames. A permanent one for this deployment, plus the aliases it takes over when it goes live.

Nothing in that list can change afterwards. Redeploying builds a new artifact rather than editing an old one, so a deployment's own hostname always serves the exact build it was created from. The artifact is capped at 8 GiB, checked both compressed and extracted.

Builds walks through reading a build log and the statuses a deployment moves through.