Embedding Assets with go:embed

The status page ships as server plus a static/ directory. The first deploy forgets the directory and the page serves 404s; the second environment has a stale copy of the CSS from last month. The service itself is 9 MB — everything it needs to serve is small and read-only. The question is not whether the files can live in the binary. It is why they were ever outside it.

go:embed copies files into the binary at compile time. The directive precedes a variable declaration, and the variable's type decides what you get:

package web

import (
	"embed"
	"net/http"
)

//go:embed dist/index.html dist/assets/*
var assets embed.FS

//go:embed robots.txt
var robotsTxt string

//go:embed logo.png
var logoPNG []byte

func Handler() http.Handler {
	return http.FileServerFS(assets)
}

Three types cover almost every use. embed.FS is a read-only fs.FS, so anything that accepts a filesystem — http.FileServerFS, fs.WalkDir, fs.ReadFile, template parsing — accepts it unchanged. A string suits text you interpolate (a version stamp, a robots file). A []byte suits binary blobs you hand to a decoder. The directive is validated at build time: a pattern that matches nothing is a compile error, not a runtime surprise.

The serving line is the payoff. http.FileServerFS(assets) mounts the embedded tree as an http.Handler with no os.Open, no working-directory assumption, and no directory to ship. The binary is the deployment artifact, and it is complete — the failure mode where the container starts without its static folder stops existing.

Two properties of embedding shape when to reach for it. Content is baked at compile time: edit dist/index.html and nothing changes until you rebuild, which is why local frontend development usually keeps a runtime override. And the bytes live in the executable's read-only data segment: they cost memory once per process image (the operating system shares those pages across processes), they bloat the binary you distribute, and they cannot be updated without a new binary.

A development switch keeps both workflows honest:

func Handler(dir string) http.Handler {
	if dir != "" {
		return http.FileServer(http.Dir(dir)) // live reload in dev
	}
	return http.FileServerFS(assets)
}

-static-dir dist during frontend work, empty in production. The production path never reads the disk, so the artifact you test is the artifact you ship — the same single-artifact reasoning that drives scratch containers in Containerizing Go Services.

A team embeds //go:embed static and ships. On the developer's machine the build works; in CI the CSS 404s — or the reverse: CI fails with "no matching files found" for a file that plainly exists locally. Both have the same root cause: the tree go build sees is not the tree in version control. Generated files missing from the repository, or junk files present only locally, are invisible until the build runs somewhere else. Embed patterns have precise rules, and knowing them prevents both the missing-file and the shipped-surprise cases.

Naming a directory embeds the whole subtree, recursively. //go:embed static includes static/css/app.css and everything below it. Naming a file embeds exactly that file. Patterns support * and ? through path.Match semantics, but with an important exclusion: a wildcard that matches a directory's contents skips files whose names begin with . or _.

The all: prefix disables that exclusion. Compare:

//go:embed templates            // skips templates/.env and templates/_partial.html
var withDefault embed.FS

//go:embed all:templates        // includes dotfiles and underscore files
var withEverything embed.FS

That rule protects you more often than it hurts: .git, .DS_Store, and editor droppings stay out of the binary by default. It bites when a legitimate asset begins with _ — some static-site generators emit _headers — and the symptom is a runtime fs.ErrNotExist for a file that plainly exists on disk.

What cannot be embedded is as important as what can. Patterns may not contain . or .. elements, may not start or end with /, and may not reference files outside the package's module — //go:embed ../../etc/passwd does not compile. Symlinks are not followed: a symlink pointing outside the tree simply does not match. These constraints turn the embed directive into a small auditable surface: anything in the binary had to be a real, in-repo file at build time.

That last property flips the usual secret worry on its head, with one exception. Because the directive only takes real files, you cannot accidentally embed a runtime-mounted secret — but you can accidentally commit a file and then embed it. //go:embed .env.local bakes tokens into an artifact that travels through registries and is trivially unpacked with strings. The rule: embed only files whose contents you would paste into a pull request, and let CI grep the source for go:embed directives next to secret-looking filenames. For runtime configuration that must stay out of the binary, load it from the environment or a mounted file as described in Configuration and Secrets Handling.

For everything else — templates, migration SQL, certificate fixtures, a wasm runtime — embedding is the honest default: the files are versioned with the code that reads them, and a mismatch between the two becomes impossible.

Embedding introduces two costs that are easy to accept blindly: stale content and a bigger binary. Both are manageable once measured.

Freshness is a build-system problem. The directive is evaluated when the package compiles, so any change to an embedded file must trigger a rebuild. Go's build cache keys on file contents for embedded files, so go build after editing dist/index.html does produce a new binary — but a Makefile that only reruns go build when *.go files change will happily skip it. The fix is boring: make the asset build a prerequisite of go build, or always rebuild in CI. The failure mode to watch for is the dev server serving runtime files while production serves embedded ones; if the two paths diverge for long enough, the embedded copy is a surprise at the worst moment. Keeping one function that returns fs.FS, with the dev/production switch inside it, keeps the divergence to a single reviewed line.

Size is a measurement, not a feeling. A go build -o app followed by ls -l before and after adding the directive gives the exact cost, and for a web UI the dominant term is images — a single 400 KB hero image can outweigh all the code. Compression is not applied to embedded content, so the practical lever is the same one any static host uses: shrink the assets. When a large asset set changes often, the halfway house is embedding the shell of the page and fetching bulk data at runtime, which keeps single-artifact deploys without shipping megabytes per release.

Tests can see embedded files, and that is the point. Because embed.FS satisfies fs.FS, handlers built on it are testable with httptest and fstest:

func TestIndexServed(t *testing.T) {
	h := Handler()
	srv := httptest.NewServer(h)
	defer srv.Close()

	res, err := http.Get(srv.URL + "/index.html")
	if err != nil {
		t.Fatal(err)
	}
	defer res.Body.Close()
	if res.StatusCode != http.StatusOK {
		t.Fatalf("got %d, want 200", res.StatusCode)
	}
}

The test runs against the exact bytes production will serve — no fixture directory, no cd into the repo root, no skipped-test-when-file-missing logic. When a test needs a modified tree (missing file, unusual names), testing/fstest.MapFS builds one in memory; that combination is the same recipe as the handler tests in Testing HTTP with httptest.

The habit worth keeping: treat embedded assets as part of the API surface. They are shipped, cached, and versioned with the binary, so a change to them deserves the same review and the same test as a change to the code that reads them.