All jobs

Migrate From packr to Go's embed Package

Yes. An agent replaces packr boxes with go:embed, removes the packr2 build step from the Makefile and Dockerfile, and checks every embedded file loads.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

packr bundled static files into a Go binary before the standard library could, and it needed its own build tool to do it. Since Go 1.16 the embed package does the same with a comment directive and plain go build. The agent starts by listing the boxes and how the build depends on the tool. In an analytics server like usefathom/fathom, go.mod requires github.com/gobuffalo/packr/v2 v2.8.3 and there are two boxes: packr.NewBox("./migrations") in pkg/datastore/sqlstore/sqlstore.go, handed to sql-migrate as a PackrMigrationSource, and packr.NewBox("./../../assets/build") in pkg/api/routes.go, which serves the front end. The Makefile's docker target builds the binary with packr2 build, its clean target runs packr clean, and the Dockerfile runs go install github.com/gobuffalo/packr/v2/packr2@latest in its builder stage.

The migrations box converts directly. A //go:embed migrations directive on an embed.FS variable in the sqlstore package replaces the box, and sql-migrate at the version in go.mod already offers EmbedFileSystemMigrationSource, which takes that file system and a Root of migrations/ plus the driver name. The agent does not stop at a compile. It calls FindMigrations() for each of the three drivers and compares the counts with the directories on disk: 24 for mysql, 26 for postgres, 27 for sqlite3. An embed pattern that is one directory off compiles cleanly and finds nothing, and this application exits at startup with "Missing database migrations" when that happens.

The assets box cannot be converted where it stands. An embed pattern may not contain .., so pkg/api cannot reach assets/build two levels up. The agent adds a small Go package inside assets/ that embeds build and returns it through fs.Sub, and routes.go imports it. The handlers in pkg/api/http.go change their parameter from *packr.Box to http.FileSystem: box.Open keeps working for http.ServeContent, the http.FileServer(box) line stays, and box.Bytes("404.html") becomes an open and a copy.

Then comes the difference that breaks CI if nobody looks. assets/build is produced by gulp and listed in .gitignore, so it does not exist on a fresh checkout. packr resolved its boxes when the program ran, so make test passes today without the front end ever being built, and .github/workflows/test.yml relies on that: it sets up Go and runs make test, with no Node step. go:embed is resolved by the compiler. The agent shows each failure in turn: with the directory missing, go vet reports pattern all:build: no matching files found; with it present and empty, cannot embed directory build: contains no embeddable files. A committed assets/build/.gitkeep together with the all: prefix, which includes dot files, is what compiles on a clean checkout. The agent adds the .gitignore exception for that one file, replaces packr2 build with go build in the Makefile, removes the packr clean line and the install line from the Dockerfile, and runs go mod tidy, which drops packr and the modules only it needed.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Migrate this Go repository from gobuffalo/packr to the standard library embed package. List every packr.New, packr.NewBox and packr2 reference in Go files, the Makefile, Dockerfiles, CI workflows and docs, and every function that takes a *packr.Box. Read go.mod for the Go version and confirm it is at least 1.16. For each box, say what directory it bundles, whether that directory is committed or generated by another build step, and whether it sits below the package that uses it. Replace each box with an embed.FS declared in a package at or above the directory, since embed patterns cannot use '..'; add a small package next to the directory when needed. Change functions that took a box to take fs.FS or http.FileSystem and keep their behaviour. If a library was given the box (a migration runner, a template loader), use that library's embed or fs.FS source at the version already in go.mod. For a generated directory that is gitignored, make a clean checkout compile and pass go vet and the tests without running the generator, and show the compiler error you are avoiding. Prove the contents load: count embedded files per directory against the files on disk, and request each static route through the handler in a test. Replace packr2 build with go build in the Makefile and Dockerfile, delete packr clean and the packr2 install, run go mod tidy, then run go vet and the full test suite. Do not run Docker. Open a pull request.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

A pull request that touches pkg/datastore/sqlstore/sqlstore.go, pkg/api/routes.go, pkg/api/http.go, a new assets/assets.go, assets/build/.gitkeep, .gitignore, the Makefile, the Dockerfile, go.mod and go.sum. The description lists the two boxes with what replaced each, the migration counts per driver from the embedded file system next to the counts on disk, and the two compiler messages that explain why the placeholder file exists.

A reviewer should think about one runtime difference the description calls out. Files in an embed.FS report a zero modification time, so http.ServeContent no longer sends a Last-Modified header for them. This server sets its own Cache-Control: max-age=432000 on the index page and the tracker script, so browser caching of those still works, and conditional requests based on modification time do not. If that matters to you, the agent can add an ETag derived from the build in a follow-up message to the same session.

The description is explicit about what was not exercised. The Docker image is not built, because the sandbox has no Docker and the prompt rules it out, so the Dockerfile edit is checked by reading. The front end is not built with gulp either. The static routes are tested against a file placed in assets/build for the test, which proves the handlers and says nothing about the real bundle.

Run it on every repository that still imports packr

This is a one-time change for each repository, so start it from a script. Find the repositories whose go.mod names gobuffalo/packr, and send one POST /o/{org}/sessions for each with the body above and that repository in resources. Include a request_id that is a UUID v5 of the repository name, so rerunning the script returns the runs it already started.

If the key that starts them has a webhook_url, each finished run posts run.completed or run.failed to it with the session's URL, and the script does not need to poll.

The use case this job follows, with its automation and trigger: Upgrade dependencies weekly.

Why run it on Rush?

The edit to Go code is mechanical, and the risk sits in everything around it: a build that silently depended on a separate tool, a generated directory the compiler now needs, a CI job that never built the front end. Finding those means doing what CI does on a clean checkout, which is exactly the state a developer's machine is never in after the first make. The sandbox starts from a fresh clone with no build output, so the missing directory error appears for the agent before it appears for your pipeline.

The run also proves the bundled content, which a compile cannot. Counting embedded migrations per driver and requesting each static route are quick checks, and their output stays in the transcript, so the pull request's claim that nothing was dropped from the binary is backed by numbers.

Frequently asked questions

Can go:embed include files from a parent directory?

No. A pattern is relative to the package directory and may not contain .. or start with a slash. The usual fix is a small package placed beside the files that embeds them and exports the file system, which is what the agent adds.

Do I still need packr2 or any build step?

No. go build reads the //go:embed directives itself. The agent removes the packr2 install and build commands from the Makefile and Dockerfile, and go mod tidy removes the module.

My embedded directory is generated and gitignored. What happens on a clean checkout?

Compilation fails, where packr only failed at runtime. The directory has to exist and hold a file the pattern can match. A committed placeholder plus the all: prefix keeps go vet and go test working before the generator has run; the real build still has to run the generator first.

Does it work with sql-migrate, or other libraries that accepted a packr box?

Most have an equivalent that takes an embed.FS or fs.FS. sql-migrate has EmbedFileSystemMigrationSource. The agent uses what the version in your go.mod provides and upgrades the library only when it has no such source.

More jobs like this: Upgrade dependencies weekly

Keep reading