Build Step
Definition
A build step is one run of a tool that reads your sources and writes a website. In practice it is a single command — npm run build, hugo, eleventy — behind which sit several jobs: compiling TypeScript or Sass, rendering Markdown through templates, bundling and minifying assets, copying images, and writing everything into an output folder named dist, build, public or _site. A static site generator is one kind of build step; a bundler is another; many projects run both in sequence. The step either succeeds and leaves a complete folder, or fails with an error and leaves nothing you should upload. Crucially it happens on your machine or a build server, not when a visitor arrives, which is precisely what separates a static site from an application server.
Why It Matters
The build is where mistakes are supposed to surface: a missing import, a broken internal link, a type error, an image referenced but never added. Catching those at build time costs a minute; catching them after publishing costs however long it takes somebody to notice and tell you. It is also the step that makes the output small, since minification and tree shaking happen here rather than in the browser. The risk is that builds are not as reproducible as people assume — a machine with a different Node version or a stale lockfile can produce different output from the same source, which is why a failed build on someone else's laptop is such a familiar afternoon. Worth remembering as well: plenty of sites need no build step at all, and adding one to a folder of hand-written HTML buys nothing.
How It Works
The command runs in the project root and reads a config file — vite.config.js, hugo.toml, astro.config.mjs — to learn where sources live and where output should go. It walks the sources, transforms each kind of file with the right tool, resolves the dependency graph from the entry point, and writes results into the output folder, usually wiping that folder first so nothing stale survives. Filenames in the output normally include a content hash, and the HTML is rewritten to reference those hashed names. The build artifact left behind is the only thing that ever needs uploading; source files, node_modules and config stay where they are.
Real-World Example
A developer maintains a product site in Astro. The build takes eleven seconds and produces a 'dist' folder of 3.4 MB — HTML for twenty-two pages, hashed CSS and JS, and optimised images. There is no repository or pipeline involved: they drag 'dist' onto 99helpers and it is live at plume-app.99helpers.site within seconds. For a sister project of four hand-written HTML files there is no build at all, and the folder upload is identical in every other respect.
Common Mistakes
- ✕Uploading the project folder rather than the output folder — visitors then get source files, or a 404, because no server assembles anything for them
- ✕Forgetting to rebuild after editing a source file — the change is real but the output folder still holds the previous version, so the published site never moves
- ✕Adding a build step to a site that does not need one — a folder of plain HTML gains nothing but a toolchain that can break
Related Terms
Static Site Generator
A static site generator is a tool that turns content and templates into a folder of finished HTML files. Hugo, Eleventy, Astro, Jekyll and Next.js in export mode are the common ones.
Build Artifact
A build artifact is the set of files a build produces — the finished HTML, CSS, JavaScript and images that actually get served. It is what you publish, not the source you edit.
Minification
Minification strips everything from CSS, JavaScript and HTML that a browser does not need — spaces, line breaks, comments, long variable names — leaving smaller files that behave identically.
Continuous Deployment
Continuous deployment means every accepted change is published automatically, with nobody pressing a publish button. A change that passes its checks goes live on its own.
Folder Upload
Sending a whole directory to a host in one go, with its internal structure intact, rather than picking files one at a time. Every file arrives at the same place in the tree it started in.
Put a file online in seconds
Drop in a document, an image, a page or a whole static website and share the link — free, with no build step and no server to set up.
Host a file free →