{"id":13413727,"url":"https://github.com/gobuffalo/packr","last_synced_at":"2025-10-21T04:47:35.194Z","repository":{"id":37588133,"uuid":"85126896","full_name":"gobuffalo/packr","owner":"gobuffalo","description":"The simple and easy way to embed static files into Go binaries.","archived":true,"fork":false,"pushed_at":"2021-12-04T19:53:01.000Z","size":731,"stargazers_count":3410,"open_issues_count":67,"forks_count":194,"subscribers_count":43,"default_branch":"master","last_synced_at":"2025-01-15T06:58:52.325Z","etag":null,"topics":["build","gobuffalo","packr"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gobuffalo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null},"funding":{"github":"markbates","patreon":"buffalo"}},"created_at":"2017-03-15T22:24:53.000Z","updated_at":"2025-01-07T02:59:58.000Z","dependencies_parsed_at":"2022-07-31T11:48:04.148Z","dependency_job_id":null,"html_url":"https://github.com/gobuffalo/packr","commit_stats":null,"previous_names":[],"tags_count":130,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gobuffalo%2Fpackr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gobuffalo%2Fpackr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gobuffalo%2Fpackr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gobuffalo%2Fpackr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gobuffalo","download_url":"https://codeload.github.com/gobuffalo/packr/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":235424925,"owners_count":18988316,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["build","gobuffalo","packr"],"created_at":"2024-07-30T20:01:47.539Z","updated_at":"2025-10-05T17:31:30.327Z","avatar_url":"https://github.com/gobuffalo.png","language":"Go","readme":"**NOTICE: Please consider migrating your projects to\n[embed](https://pkg.go.dev/embed) which is native file embedding feature of Go,\nor github.com/markbates/pkger. It has an idiomatic API, minimal dependencies, a stronger test suite (tested directly against the std lib counterparts), transparent tooling, and more.**\n\nhttps://blog.gobuffalo.io/introducing-pkger-static-file-embedding-in-go-1ce76dc79c65\n\n# Packr (v2)\n\n[![GoDoc](https://godoc.org/github.com/gobuffalo/packr/v2?status.svg)](https://godoc.org/github.com/gobuffalo/packr/v2)\n[![Actions Status](https://github.com/gobuffalo/packr/workflows/Tests/badge.svg)](https://github.com/gobuffalo/packr/actions)\n\nPackr is a simple solution for bundling static assets inside of Go binaries. Most importantly it does it in a way that is friendly to developers while they are developing.\n\nAt this moment, supported go versions are:\n\n* 1.16.x\n* 1.17.x\n\neven though it may (or may not) working well with older versions.\n\n## Intro Video\n\nTo get an idea of the what and why of Packr, please enjoy this short video: [https://vimeo.com/219863271](https://vimeo.com/219863271).\n\n## Library Installation\n\n### Go 1.16 and above\n\n```console\n$ go install github.com/gobuffalo/packr/v2@v2.8.3\n```\n\nor\n\n```console\n$ go install github.com/gobuffalo/packr/v2@latest\n```\n\n### Go 1.15 and below\n\n```console\n$ go get -u github.com/gobuffalo/packr/...\n```\n\n## Binary Installation\n\n### Go 1.16 and above\n\n```console\n$ go install github.com/gobuffalo/packr/v2/packr2@v2.8.3\n```\n\nor\n\n```console\n$ go install github.com/gobuffalo/packr/v2/packr2@latest\n```\n\n### Go 1.15 and below\n\n```console\n$ go get -u github.com/gobuffalo/packr/packr2\n```\n\n## New File Format FAQs\n\nIn version `v2.0.0` the file format changed and is not backward compatible with the `packr-v1.x` library.\n\n#### Can `packr-v1.x` read the new format?\n\nNo, it can not. Because of the way the new file format works porting it to `packr-v1.x` would be difficult. PRs are welcome though. :)\n\n#### Can `packr-v2.x` read `packr-v1.x` files?\n\nYes it can, but that ability will eventually be phased out. Because of that we recommend moving to the new format.\n\n#### Can `packr-v2.x` generate `packr-v1.x` files?\n\nYes it can, but that ability will eventually be phased out. Because of that we recommend moving to the new format.\n\nThe `--legacy` command is available on all commands that generate `-packr.go` files.\n\n```bash\n$ packr2 --legacy\n```\n\n## Usage\n\n### In Code\n\nThe first step in using Packr is to create a new box. A box represents a folder on disk. Once you have a box you can get `string` or `[]byte` representations of the file.\n\n```go\n// set up a new box by giving it a name and an optional (relative) path to a folder on disk:\nbox := packr.New(\"My Box\", \"./templates\")\n\n// Get the string representation of a file, or an error if it doesn't exist:\nhtml, err := box.FindString(\"index.html\")\n\n// Get the []byte representation of a file, or an error if it doesn't exist:\nhtml, err := box.Find(\"index.html\")\n```\n\n### What is a Box?\n\nA box represents a folder, and any sub-folders, on disk that you want to have access to in your binary. When compiling a binary using the `packr2` CLI the contents of the folder will be converted into Go files that can be compiled inside of a \"standard\" go binary. Inside of the compiled binary the files will be read from memory. When working locally the files will be read directly off of disk. This is a seamless switch that doesn't require any special attention on your part.\n\n#### Example\n\nAssume the follow directory structure:\n\n```\n├── main.go\n└── templates\n    ├── admin\n    │   └── index.html\n    └── index.html\n```\n\nThe following program will read the `./templates/admin/index.html` file and print it out.\n\n```go\npackage main\n\nimport (\n  \"fmt\"\n\n  \"github.com/gobuffalo/packr/v2\"\n)\n\nfunc main() {\n  box := packr.New(\"myBox\", \"./templates\")\n\n  s, err := box.FindString(\"admin/index.html\")\n  if err != nil {\n    log.Fatal(err)\n  }\n  fmt.Println(s)\n}\n```\n\n### Development Made Easy\n\nIn order to get static files into a Go binary, those files must first be converted to Go code. To do that, Packr, ships with a few tools to help build binaries. See below.\n\nDuring development, however, it is painful to have to keep running a tool to compile those files.\n\nPackr uses the following resolution rules when looking for a file:\n\n1. Look for the file in-memory (inside a Go binary)\n1. Look for the file on disk (during development)\n\nBecause Packr knows how to fall through to the file system, developers don't need to worry about constantly compiling their static files into a binary. They can work unimpeded.\n\nPackr takes file resolution a step further. When declaring a new box you use a relative path, `./templates`. When Packr receives this call it calculates out the absolute path to that directory. By doing this it means you can be guaranteed that Packr can find your files correctly, even if you're not running in the directory that the box was created in. This helps with the problem of testing, where Go changes the `pwd` for each package, making relative paths difficult to work with. This is not a problem when using Packr.\n\n---\n\n## Usage with HTTP\n\nA box implements the [`http.FileSystem`](https://golang.org/pkg/net/http/#FileSystem) interface, meaning it can be used to serve static files.\n\n```go\npackage main\n\nimport (\n\t\"net/http\"\n\n\t\"github.com/gobuffalo/packr/v2\"\n)\n\nfunc main() {\n\tbox := packr.New(\"someBoxName\", \"./templates\")\n\n\thttp.Handle(\"/\", http.FileServer(box))\n\thttp.ListenAndServe(\":3000\", nil)\n}\n```\n\n---\n\n## Building a Binary\n\nBefore you build your Go binary, run the `packr2` command first. It will look for all the boxes in your code and then generate `.go` files that pack the static files into bytes that can be bundled into the Go binary.\n\n```\n$ packr2\n```\n\nThen run your `go build command` like normal.\n\n*NOTE*: It is not recommended to check-in these generated `-packr.go` files. They can be large, and can easily become out of date if not careful. It is recommended that you always run `packr2 clean` after running the `packr2` tool.\n\n#### Cleaning Up\n\nWhen you're done it is recommended that you run the `packr2 clean` command. This will remove all of the generated files that Packr created for you.\n\n```\n$ packr2 clean\n```\n\nWhy do you want to do this? Packr first looks to the information stored in these generated files, if the information isn't there it looks to disk. This makes it easy to work with in development.\n\n---\n\n## Debugging\n\nThe `packr2` command passes all arguments down to the underlying `go` command, this includes the `-v` flag to print out `go build` information. Packr looks for the `-v` flag, and will turn on its own verbose logging. This is very useful for trying to understand what the `packr` command is doing when it is run.\n\n---\n\n## FAQ\n\n### Compilation Errors with Go Templates\n\nQ: I have a program with Go template files, those files are named `foo.go` and look like the following:\n\n```\n// Copyright {{.Year}} {{.Author}}. All rights reserved.\n// Use of this source code is governed by a BSD-style\n// license that can be found in the LICENSE file.\n\npackage {{.Project}}\n```\n\nWhen I run `packr2` I get errors like:\n\n```\nexpected 'IDENT', found '{'\n```\n\nA: Packr works by searching your `.go` files for [`github.com/gobuffalo/packr/v2#New`](https://godoc.org/github.com/gobuffalo/packr/v2#New) or [`github.com/gobuffalo/packr/v2#NewBox`](https://godoc.org/github.com/gobuffalo/packr/v2#NewBox) calls. Because those files aren't \"proper\" Go files, Packr can't parse them to find the box declarations. To fix this you need to tell Packr to ignore those files when searching for boxes. A couple solutions to this problem are:\n\n* Name the files something else. The `.tmpl` extension is the idiomatic way of naming these types of files.\n* Rename the folder containing these files to start with an `_`, for example `_templates`. Packr, like Go, will ignore folders starting with the `_` character when searching for boxes.\n\n### Dynamic Box Paths\n\nQ: I need to set the path of a box using a variable, but `packr.New(\"foo\", myVar)` doesn't work correctly.\n\nA: Packr attempts to \"automagically\" set it's resolution directory when using [`github.com/gobuffalo/packr/v2#New`](https://godoc.org/github.com/gobuffalo/packr/v2#New), however, for dynamic paths you need to set it manually:\n\n```go\nbox := packr.New(\"foo\", \"|\")\nbox.ResolutionDir = myVar\n```\n\n### I don't want to pack files, but still use the Packr interface.\n\nQ: I want to write code that using the Packr tools, but doesn't actually pack the files into my binary. How can I do that?\n\nA: Using [`github.com/gobuffalo/packr/v2#Folder`](https://godoc.org/github.com/gobuffalo/packr/v2#Folder) gives you back a `*packr.Box` that can be used as normal, but is excluded by the Packr tool when compiling.\n\n### Packr Finds No Boxes\n\nQ: I run `packr2 -v` but it doesn't find my boxes:\n\n```\nDEBU[2019-03-18T18:48:52+01:00] *parser.Parser#NewFromRoots found prospects=0\nDEBU[2019-03-18T18:48:52+01:00] found 0 boxes\n```\n\nA: Packr works by parsing `.go` files to find [`github.com/gobuffalo/packr/v2#Box`](https://godoc.org/github.com/gobuffalo/packr/v2#Box) and [`github.com/gobuffalo/packr/v2#NewBox`](https://godoc.org/github.com/gobuffalo/packr/v2#NewBox) declarations. If there aren't any `.go` in the folder that `packr2` is run in it can not find those declarations. To fix this problem run the `packr2` command in the directory containing your `.go` files.\n\n### Box Interfaces\n\nQ: I want to be able to easily test my applications by passing in mock boxes. How do I do that?\n\nA: Packr boxes and files conform to the interfaces found at [`github.com/gobuffalo/packd`](https://godoc.org/github.com/gobuffalo/packd). Change your application to use those interfaces instead of the concrete Packr types.\n\n```go\n// using concrete type\nfunc myFunc(box *packr.Box) {}\n\n// using interfaces\nfunc myFunc(box packd.Box) {}\n```\n","funding_links":["https://github.com/sponsors/markbates","https://patreon.com/buffalo"],"categories":["HarmonyOS","Resource Embedding","开源类库","Go","Misc","资源嵌入","Open source library","Relational Databases","嵌入的资源"],"sub_categories":["Windows Manager","HTTP Clients","构建编译","Advanced Console UIs","查询语","Build And Compile","HTTP客户端","交流"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgobuffalo%2Fpackr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgobuffalo%2Fpackr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgobuffalo%2Fpackr/lists"}