precompiler

README

go-assetprecompiler

This is a web asset compiler written in Golang to be used in a web asset pipeline.

Why?

Coming from Rails, I was used to having all my Javascript and CSS assets precompiled as well as uniquely identified for cache-friendliness and lowering the number of requests required to view a website.

The only Golang-based solutions I was able to find were either purpose-built for a specific use case or simply didn't have the features I needed.

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/parnic/go-assetprecompiler"

func main() {
    precompiler.Compile(precompiler.Config{
        Files: []string{
            "assets/css/bootstrap.default.css",
            "assets/css/font-awesome.css",
            "assets/css/application.css",
            "assets/js/jquery.js",
            "assets/js/popper.js",
            "assets/js/bootstrap.js",
            "assets/js/moment.js",
            "assets/js/application.js",
        },
        Minify:    true,
        OutputDir: "assets/",
        FilePrefix: "app-",
    })
}

Currently only Javascript (.js) and CSS (.css) files are supported.

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)
FilePrefix	String, what, if anything, should be prefixed onto the output filenames

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.

Once the compiled files have been generated, you would set your HTML file/template to use them with e.g.:

<link rel="stylesheet" href="/assets/css/app-55d3344ad20eb62608617d8c6c80ed662647a8d11b600a522f7cfe85c1e3ed58.min.css">
<script src="/assets/js/app-9db393ed26ecff7f3c64a37df9168c09036d1f1d1bf380a74f442106e4101629.min.js"></script>

Or create a template function to retrieve the correct filenames so you don't have to update your template every time you re-generate.

Gin-gonic middleware

There is a https://github.com/gin-gonic/gin middleware available to automatically set a Cache-Control header for infinite lifetime of these assets. You can use it like:

r := gin.New()
r.Static("/assets", "assets")
r.Use(precompiler.GinMiddleware("/assets"))

Where "/assets" is the base path (with leading slash) for all assets on your website. Note that every request starting with this path will have very long cache headers set, not just CSS/JS files.

Other integrations

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

Contributions

Contributions are quite welcome. This is a fairly simple helper library at the moment, but I'd be happy to implement any customizations for it to work for other peoples' apps than just my own.

Documentation

Index

• func Compile(config Config) (map[FileType]*CompileResult, error)
• func GinMiddleware(assetPath string) gin.HandlerFunc
• type CompileResult
• type Config
• type FileType

Functions

func Compile

func Compile(config Config) (map[FileType]*CompileResult, error)

Compile compiles files indicated by the config into a single file per type

func GinMiddleware

func GinMiddleware(assetPath string) gin.HandlerFunc

GinMiddleware is used to set the cache-control header for all files under the specified asset path (including leading slash)

Types

type CompileResult

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

CompileResult holds the results of compilation

type Config

type Config struct {
	// Files is a list of files to precompile together
	Files []string
	// Minify specifies whether minification should happen along with concatenation
	Minify bool
	// OutputDir if specified will cause the result to be written to this directory
	OutputDir string
	// FilePrefix is a string that will be prefixed on the files if OutputDir is specified
	FilePrefix string
}

Config holds information on how to run the compiler

type FileType

type FileType string

FileType represents a supported file extension (without the .)

const (
	CSS FileType = "css"
	JS  FileType = "js"
)

supported file types