Embedding Assets with embed

A compiled Go program is a single executable file. The templates, CSS and images it serves are not inside it. By default they are read from disk while the program runs, which means two things to deploy and a directory layout to get right. Miss one file and the program only fails at the first request. The //go:embed directive copies files into the executable at build time, so there is one file to ship.

How to write it

Put a comment of the form //go:embed pattern directly above a package-level variable. Only blank lines and other comments may sit between them. The variable's type decides what you get. string or []byte holds one file. embed.FS holds many, and is a read-only file system you can hand to anything that accepts an fs.FS, such as template.ParseFS or http.FileServerFS. Embedding arrived in Go 1.16.

Both import spellings exist for a reason. With embed.FS you write import "embed" because your code names the type. With a string or []byte variable the code never mentions the package, so you write import _ "embed". The underscore means: load this package, I will not refer to it.

Pattern rules

Patterns are relative to the directory holding the source file. They cannot contain .., cannot leave the module, and do not follow symlinks. A pattern matching nothing is a build error. Names beginning with a dot or an underscore are skipped unless the pattern starts with all: (Go 1.18).

Paths keep the directory

//go:embed static gives you static/style.css, not style.css. fs.Sub(assets, "static") returns a file system rooted inside that directory, so URLs do not repeat the name.

package main

import (
	"embed"
	"fmt"
	"io/fs"
	"log"
	"net/http"
	"net/http/httptest"
)

// Next to this file, create a directory "static" holding one file,
// static/style.css, containing exactly: body{margin:0}
//
//go:embed static
var staticFiles embed.FS

func main() {
	// Paths inside the embedded file system keep the directory name.
	css, err := staticFiles.ReadFile("static/style.css")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("read: %s\n", css)

	// fs.Sub drops the "static/" prefix so the URL does not repeat it.
	assets, err := fs.Sub(staticFiles, "static")
	if err != nil {
		log.Fatal(err)
	}
	rec := httptest.NewRecorder()
	http.FileServerFS(assets).ServeHTTP(rec, httptest.NewRequest("GET", "/style.css", nil))
	fmt.Printf("served: %d %s\n", rec.Code, rec.Body.String())
}

// Output:
// read: body{margin:0}
// served: 200 body{margin:0}

package main

import (
	"embed"
	"html/template"
	"log"
	"os"
)

//go:embed templates/*.html
var templateFiles embed.FS

// Parsed once at start-up. ParseFS (Go 1.16) takes the patterns a second
// time, matched against the embedded file system rather than the disk.
// template.Must panics on a parse error, which is what you want at start-up.
var pages = template.Must(template.ParseFS(templateFiles, "templates/*.html"))

func main() {
	// A template's name is the base name of its file, not the full path.
	if err := pages.ExecuteTemplate(os.Stdout, "home.html", "Ada"); err != nil {
		log.Fatal(err)
	}
}

// With templates/home.html containing: <h1>Hello {{.}}</h1>
//
// Output:
// <h1>Hello Ada</h1>

package main

import (
	"database/sql"
	_ "embed" // the directive needs this package; the code never names it
)

// A single pattern and a string variable: the file's text, nothing else.
//
//go:embed schema.sql
var schema string

func createTables(db *sql.DB) error {
	// schema is an ordinary string, so it goes straight to the database.
	_, err := db.Exec(schema)
	return err
}

package ui

import (
	"embed"
	"io/fs"
	"net/http"
)

//go:embed all:dist
var frontend embed.FS

// Handler serves the built frontend from inside the binary. Without the
// all: prefix (Go 1.18) the build would skip dist/_next and dist/.vite,
// and the page would load with no JavaScript and no error anywhere.
func Handler() (http.Handler, error) {
	assets, err := fs.Sub(frontend, "dist")
	if err != nil {
		return nil, err
	}
	return http.FileServerFS(assets), nil
}