Build Artifact

Why It Matters

Uploading the wrong folder is the most common publishing mistake there is. Push the source directory and visitors get a file listing or a page of raw Markdown; push the artifact and they get the site. Artifacts are also the unit worth keeping, because a 2 MB output folder from last Tuesday is a complete working copy of the site as it stood on Tuesday — which is the whole reason rollback is possible. Treating the artifact as disposable keeps repositories small, too. Committing a rebuilt output folder on every change fills the history with thousands of files a machine can regenerate in forty seconds.

How It Works

A generator reads your source files and writes finished ones into an output directory. On the way it resolves imports, concatenates modules, strips comments and whitespace, and renames files with a content hash, so 'main.js' becomes something like 'main.4f2ab9c1.js'. Those hashed names let a cache hold each file for a year, because a changed file arrives under a new name rather than as a new version of an old one. The tool then rewrites the references inside the HTML to point at the hashed names. Whatever lands in that directory — markup, styles, scripts, fonts, images, a robots file copied straight through — is the artifact. Zip it, or point a deployment at it, and there is nothing else to do.

Real-World Example

Common Mistakes

• ✕Uploading the project folder instead of the output folder — visitors get source files and a directory listing rather than a working site
• ✕Committing the build output to version control — it doubles the size of every change and produces merge conflicts in files nobody wrote
• ✕Editing a file inside the output folder to make a quick fix — the next build overwrites it, and the change is gone with no trace of why

Related Terms