Skip to content

Latest commit

 

History

History
100 lines (76 loc) · 3.93 KB

README.md

File metadata and controls

100 lines (76 loc) · 3.93 KB
Raw

go-asset-pipeline

This is a CSS & JS asset pipeline written in Golang.

Neovim Gopher

Why?

In Rails you have an asset pipeline where all Javascript and Stylesheets are minified so they load quicker, uniquely identified for cache-friendliness, and aggregated into a single file to lower the number of requests required to view a website.

Most existing Golang-based solutions are either purpose-built for a specific use case or simply lack features.

How is this different?

You provide a list of files that you would like to be compiled into one file, in the order you'd like them compiled in, and the library will combine, optionally minify them using https://github.com/tdewolff/minify, and generate an output file with the sha256 signature of the file in the filename. Your application can consume the generated byte buffers and handle them as you please, or you can have the library write the files out to a specified directory.

How do I use it?

The simplest use case is to generate assets offline for use in a Golang web application. For example:

package main

import precompiler "github.com/plentiform/go-asset-pipeline"

func main() {
	precompileResult, _ := precompiler.Compile(precompiler.Config{
		Files: []string{
			"assets/css/font-awesome.css",
			"assets/css/bootstrap.css",
			"assets/css/app.css",
			"assets/css/components/*",
			"assets/js/jquery.js",
			"assets/js/bootstrap.js",
			"assets/js/app.js",
			"assets/js/tasks/*",
		},
		Minify:    true,
		OutputDir: "assets/",
	})
  cssHash := precompileResult[precompiler.CSS].Hash
  jsHash := precompileResult[precompiler.JS].Hash
}

This will produce files like:

/assets/css/app-55d3344ad20eb62608617d8c6c80ed662647a8d11b600a522f7cfe85c1e3ed58.min.css
/assets/js/app-9db393ed26ecff7f3c64a37df9168c09036d1f1d1bf380a74f442106e4101629.min.js

Note that the hash (fingerprint) will change every time you make a change to the underlying CSS or JS file and recompile. Here's how to automatically pass the updated hash to your templates:

  t, err := template.ParseFiles("templates/your_template.html", "templates/your_other_template.html")
  if err != nil {
    http.Error(w, err.Error(), http.StatusInternalServerError)
    return err
  }
  vars := map[string]interface{}{}
  vars["cssHash"] = cssHash
  vars["jsHash"] = jsHash
  return t.Execute(w, vars)

Then reference the new hash in your template:

<html>
  <head>
    <link rel="stylesheet" href="/assets/css/app-{{ .cssHash }}.min.css">
    <script type="text/javascript" src="/assets/js/app-{{ .jsHash }}.min.js"></script>

Important: Currently only Javascript (.js) and CSS (.css) files are supported (it will not compile Sass).

Config key Use
Files An array of strings representing paths to files you want compiled
Minify Bool, optionally minify the files with https://github.com/tdewolff/minify
OutputDir String, the directory you'd like to write the compiled files to (with trailing slash)

Note that if an output dir is specified, "css" and "js" subdirectories will be used/created to hold the resulting files. Leaving it blank will cause it to not write any files to disk.

Compile() returns map[FileType]*CompileResult, error where FileType is one of the supported types, e.g. precompiler.CSS, precompiler.JS and CompileResult is

type CompileResult struct {
	Bytes      []byte
	Hash       string
	OutputPath string
}

for use with handling the assets yourself if you don't want the library writing them to a file.

Other integrations

If used as an offline generation tool, the resulting files can be used with a bindata/packr-style bundling system so that the app can be deployed as a single binary.

Credit

This project is a fork of go-assetprecompiler by Chris Pickett.