Need help with broccoli?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.
aletheia-icu

Description

Using brotli compression to embed static files in Go.

525 Stars 16 Forks MIT License 66 Commits 9 Opened issues

Services available

Need anything else?

🥦 Broccoli

go get -u aletheia.icu/broccoli

GoDoc Travis Go Report Card codecov.io

Broccoli uses brotli compression to embed a virtual file system of static files inside Go executables.

A few reasons to pick broccoli over the alternatives:

  • ⚡️ The average is 13-25% smaller binary size due to use of superior compression algorithm, brotli.
  • 💾 Broccoli supports bundling of multiple source directories, only relies on
    go generate
    command-line interface and doesn't require configuration files.
  • 🔑 Optional decompression is something you may want; when it's enabled, files are decompressed only when they are read the first time.
  • 🚙 You might want to target
    wasm/js
    architecture.
  • 📰 There is
    -gitignore
    option to ignore files, already ignored by your existing .gitignore files.

Performance

Admittedly, there are already many packages providing similar functionality out there in the wild. Tim Shannon did an overall pretty good overview of them in Choosing A Library to Embed Static Assets in Go, but it should be outdated by at least two years, so although we subscribe to the analysis, we cannot guarantee whether if it's up–to–date. Most if not all of the packages mentioned in the article, rely on gzip compression and most of them, unfortunately are not compatible with

wasm/js
architecture, due to some quirk that has to do with their use of
http
package. This, among other things, was the driving force behind the creation of broccoli.

The most feature-complete library from the comparison table seems to be fileb0x.

How does broccoli compare to flexb0x?

Feature

fileb0x broccoli
compression gzip brotli (-20% avg.)
optional decompression yes yes
compression levels yes yes (1-11)
different build tags for each file yes no
exclude / ignore files glob glob
unexported vars/funcs optional optional
virtual memory file system yes yes
http file system yes yes
replace text in files yes no
glob support yes yes
regex support no no
config file yes no
update files remotely yes no
.gitignore support no yes

How does it compare to others?

Broccoli seems to outperform the existing solutions.

We did benchmarks, please feel free to review them and correct us whenever our methodology could be flawed.

Usage

$ broccoli
Usage: broccoli [options]

Broccoli uses brotli compression to embed a virtual file system in Go executables.

Options: -src folder[,file,file2] The input files and directories, "public" by default. -o Name of the generated file, follows input by default. -var=br Name of the exposed variable, "br" by default. -include .html,.css Wildcard for the files to include, no default. -exclude *.wasm Wildcard for the files to exclude, no default. -opt Optional decompression: if enabled, files will only be decompressed on the first time they are read. -gitignore Enables .gitignore rules parsing in each directory, disabled by default. -quality [level] Brotli compression level (1-11), the highest by default.

Generate a broccoli.gen.go file with the variable broccoli: //go:generate broccoli -src assets -o broccoli -var broccoli

Generate a regular public.gen.go file, but include all .wasm files: //go:generate broccoli -src public -include=".wasm"

How broccoli is used in the user code: ```go //go:generate broccoli -src=public,others -o assets

func init() { br.Walk("public", func(path string, info os.FileInfo, err error) error { // walk... return nil }) }

func main() { http.ListenAndServe(":8080", br.Serve("public")) } ```

Credits

License: MIT

We would like to thank brotli development team from Google and Andy Balholm, for his c2go pure-Go port of the library. Broccoli itself is an effort of a mentoring experiment, lead by @tucnak on the foundation of Aletheia.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.