Building

Development

Headstart can be instructed to do a couple of things. To get an overview printed out in your command line, just run headstart or hs, or just continue reading.

To make a regular build, ie. compiling Sass, injecting assets into the HTML files, etc., run the following command:

headstart build

This is great if you wanted to make the task runner build just once, but if you are developing and you want to build continuously with browser auto-refreshing enabled, you can run:

headstart build --serve

This will serve your development files on a static server and print out both a local and a network URL for you that you can copy-paste into your browser. Also, no more refreshing! It's all taken care of for you. Open the printed network url on multiple devices and try scrolling and clicking. All the connected clients are effortlessly synced, and all your changes will be applied automatically.

Taking it one step further, you could also have Headstart automatically open up a browser and a code editor for you:

headstart build --serve --open --edit

The shorthand version of the instruction above would look like this:

hs build --s --o --e

The browser and editor, and much more, can be configured from your project config file.


Production

When you're done developing, it's time to introduce your project to the public. This is usually when you would start optimizing (eg. concatenating, minifying, revisioning, etc.). Headstart will do all of those things for you, requiring only the use of the production flag:.

headstart build --production

Using that flag makes the build engine do the following things (taking the configuration file into account):

Tip: The production build can also be used with the --serve flag.


Configuring your build

The config.json file that comes with the boilerplate enables you to customize the building engine on a per-project basis. Here is a commented version of that file (don't put comments in your own config file though).

{
    // Which browser to open when the `--open` flag is set
    // Depending on your OS, this could also be:
    // "google-chrome" or "chrome" or "google chrome"
    "browser": "Google Chrome",

    // Which editor to open when the `--edit` flag is set
    // Depending on your OS and version, this could also be:
    // "Sublime Text 2" or ... (no further tests done)
    "editor": "Sublime Text",

    // Minify your templates
    // eg. remove comments, collapse whitespace, ...
    "minifyHTML": false,

    // Combine media queries where possible
    // Gzipping takes care of repeating strings, so this isn't
    // really necessary
    "combineMediaQueries": false,

    // Check your javascript syntax and output the results
    // Configured through `./.jshintrc`
    // All options here: http://www.jshint.com/docs/options/
    "hint": true,

    // Validate your files through W3C and ouput the results
    "w3c": false,

    // Folder where the assets folder should be built to
    "export_assets": "export",

    // Folder where the individual templates should be built to
    "export_templates": "export",

    // Folder where the miscellaneous assets should be built to
    // Usually identical to "export_assets"
    "export_misc": "export",

    // Assemple templates during build
    // Turn this off when eg. a back-end will do the assembly
    "assemble_templates": true,

    // Prefix injected script and link tags
    // eg. "{{Url::asset('/')}}" for Laravel
    "template_asset_prefix": "",

    // Turn on revisioning to get better caching
    "revisionCaching": false
}

Optional configuration

Some extra options that aren't included in the configuration file by default:

{
    [...],

    // Uncss compares your CSS with the template pages and strips
    // out unused bits. Use together with the next option.
    //
    // Note: this feature doesn't play well with Sass @extends,
    // and has never produced good results for me. Therefore, it
    // will get deprecated by the next major release (v2.0).
    "useUncss": false,

    // If you use javascript to dynamically add
    // classes, you can prevent Uncss from stripping their styles
    // by listing selectors here
    "uncssIgnore": [],

    // You can set a custom port if want to or need to because
    // the default port (3000) is already taken
    "port": 1234,

    // You can enable a proxy if you want browser-sync to work
    // through a different host (eg. when viewing your project
    // through your MAMP/XAMP localhost)
    "proxy": "localhost/my-laravel-project/public",

    // Use a different name for the assets folder
    "assetsFolder": "assets",
    
    // Configure how your HTML will be minified
    // Default settings show below
    // All options here: https://github.com/kangax/html-minifier#options-quick-reference
    "htmlminOptions" : {
        "removeComments":                true,
        "collapseWhitespace":            true,
        "collapseBooleanAttributes":     true,
        "removeAttributeQuotes":         true,
        "useShortDoctype":               true,
        "removeScriptTypeAttributes":    true,
        "removeStyleLinkTypeAttributes": true,
        "minifyJS":                      true,
        "minifyCSS":                     true
    }

    [...]
}

Next step: Extra Services