Assets Management Package for web app in Go. The main purpose of it is to introduce some good practices already existed in Ruby on Rails' Assets Pipeline.
- Organize assets with the Include Directive.
- Pipeline for SASS and CoffeeScript in the runtime.
- Bundling and Fingerprinting Assets for production.
Get the package:
$ go get github.com/shaoshing/train
Install the command-line tool:
$ go build -o $GOPATH/bin/train github.com/shaoshing/train/cmd
$ npm install -g firstname.lastname@example.org $ npm install -g email@example.com
Prepare for the Pipeline feature
If planning to use SASS or CoffeeScript, you should run the
diagnose command to see whether your environment is fit for the feature. Otherwise, skip to the next section.
# Diagnose and follow the instructions to get your environment prepared $ train diagnose # If you experience `command not found` error, you should add $GOPATH/bin to $PATH # or run the command as follow: $ $GOPATH/bin/train
$ cd $GOPATH/src/github.com/shaoshing/train $ go run example/main.go # Visit localhost:8000 and play with the `include` directive and the SASS and CoffeeScript Pipeline.
In the example page, you can toggle the Include Directive feature, or try out the Pipeline feature by requesting a sass or coffee file.
Use it in your project
First, allow train to handle assets requests by adding handler to the http.ServeMux:
import "github.com/shaoshing/train" ... // Adding handler to the http.DefaultServeMux train.ConfigureHttpHandler(nil) http.ListenAndServe(":8000", nil)
For custom ServeMux that overwrites the DefaultServeMux, you will need to pass the mux to
mux := http.NewServeMux() ... train.ConfigureHttpHandler(mux) http.ListenAndServe(":8000", mux)
Next, add the helper functions to templates so that Train can generate assets links for you:
Now in your template file, you can use the above helpers to include your assets:
Train enforce the following assets hierarchy and generate asset paths accordingly:
Train allows you specify dependency inside asset file by using the
include directive, and when you include the file using Train's helper, Train will check the dependency and expand the file into related files.
Say you have the following files:
In the Train way, you can do it by specifying the dependency in app.js:
And then use the helper to include app.js:
When request for the html, the content will become:
To use the include directive in css is similar to js:
/* *= require stylesheets/base */ ...
SASS and CoffeeScript
The Include Directive is only available for js and css. However, SASS already has the @import directive, which is doing the same thing. For CoffeeScript, you will have to manage the dependencies in a regular way.
When handling js or css request, Train will first look for the asset file with the same extension in the assets folder. If the file cannot be found, it will keep searching for a alternative extension, which is .sass/.scss for .css and .coffee for .js . When found, Train will convert the file into the desired extension.
Take a look at an simple example:
├── assets │ ├── stylesheets │ │ ├── app.sass
In the html, you include the sass file as if it is a css file:
There are several configuration options related to the Pipeline feature:
// From SASS's doc: // When set to true, causes the line number and file where a selector is defined to be // emitted into the compiled CSS in a format that can be understood by the browser. Useful in // conjunction with [the FireSass Firebug extension](https://addons.mozilla.org/en-US/firefox/addon/103988) // for displaying the Sass filename and line number. train.Config.SASS.DebugInfo = true // false by default // From SASS's doc: // When set to true, causes the line number and file where a selector is defined to be emitted // into the compiled CSS as a comment. Useful for debugging, especially when using imports and mixins. train.Config.SASS.LineNumbers = true // false by default // Show SASS and CoffeeScript errors. train.Config.Verbose = true // false by default
Bundling and Fingerprinting Assets
You probably want to merge or convert the assets in production site for performance concern. This is done by running Train's command-line tool
train without any option:
$ cd project/root $ train -> clean bundled assets -> copy assets from assets -> bundle and compile assets -> compress assets -> Fingerprinting Assets
The following example is what were generated after running the
When Train detect the public/assets folder, it will disable the Include Directive and Pipeline features and serve from these static files directly. Template helpers will also stop expanding assets and generate with fingerprinted paths:
From Rails' Assets Pipeline Document:
Fingerprinting is a technique that makes the name of a file dependent on the contents of the file. When the file contents change, the filename is also changed. For content that is static or infrequently changed, this provides an easy way to tell whether two versions of a file are identical, even across different servers or deployment dates.
Checkout its document for more details about this technique.
Deploy to Production Server
There are two ways to deploy the Bundled and Fingerprinted assets to your server:
traincommand in the production server after each deployment. By doing this you can make sure to update public/assets to the latest. This is the simples way, but it requires your server have NodeJS and required npm if you are using the Pipeline feature.
traincommand in your local machine and upload the assets to the production server. With this way, the production server doesn't need to have NodeJS and required npm for the command.
Here is bash snippet to deploy assets using the second way:
SERVER="replace to your server's ssh address" SERVER_PUBLIC="replace to your server's public path" echo "Bundle assets" $GOPATH/bin/train if [[ $? != 0 ]] ; then echo "== fail to bundle assets" exit 1 fi echo "Copy assets to $SERVER" cd public tar zcf assets.zip assets scp assets.zip "$SERVER":assets.zip ssh $SERVER "tar mxf assets.zip && sudo cp -r assets/* $SERVER_PUBLIC/assets/ && rm assets.zip" rm -f assets.zip assets cd -
Train is production ready, and has been used in our production site Qortex. You are very welcome to report usage in your project.
Tested language / lib versions:
- Go: go1.2.1 darwin/amd64
- node-sass: 2.0.1
- CoffeeScript: 2.2.0
- Fork & Clone
- Make awesome changes (as well as tests)
- Run the tests
- Pull Request
Run the tests
- Install Go (1.2.1)
- Run all the tests
Train is released under the MIT License.