Roots CSS Pipeline
Roots css pipeline is an asset pipeline for css files which optionally concatenates and/or minifies css files for production builds.
Note: This project is in early development, and versioning is a little different. Read this for more details.
- make sure you are in your roots project directory
npm install css-pipeline --save
app.coffeefile to include the extension, as such
css_pipeline = require('css-pipeline') module.exports = extensions: [css_pipeline(files: "assets/css/**", out: 'css/build.css', minify: true)]
This extension provides a way for you to pass it a list of css files that you want to include in your project, allows you to optionally concatenate, minify, and/or hash them, and exposes a
css function to all views that prints the path or paths to your css file or files.
In general, this plugin is used in two ways, "development" and "production" modes. In development, the files are just linked through without concatenation or minification. In production, the files are concatenated, minifed, and a single file is linked. You can switch between these seamlessly using different plugin options and without having to change any view code at all.
Since the extension aims to be flexible to as many styles as possible, there are often a few different ways to do things, which are walked through below.
The first step is usually specifying which files you need in your project. This can be done either in app.coffee by passing a minimatch string or array of minimatch strings as the
files option, or in a separate file we call a manifest file by passing a path to the manifest file as a
manifest option, and having the manifest file contain a yaml-formatted array of minimatch strings. Let's look at an example of how each of these two would look, starting with using the
files key. But first, here's how our css files are organized for these examples:
assets ˻ css ˻ main.styl ˻ vendor ˻ bootstrap ˻ bootstrap.min.css ˻ extra.min.css ˻ bootstrap.plugin.min.css
Ok, now a couple possible configurations using the
css_pipeline = require('css-pipeline') # this example uses a single globstar path module.exports = extensions: [css_pipeline(files: 'assets/css/**/*')]
css_pipeline = require('css-pipeline') # this example uses an array of paths module.exports = extensions: [ css_pipeline(files: ['assets/css/vendor/**', 'assets/css/main.styl']) ]
You can pass
files either a string or array of strings, they should point to paths in your project source, and they can include globstars that are parsed by minimatch if you want. If you are using an array, the scripts will be loaded in the order that the array is in. For any globstar matches that a minimatch string makes, the files are loaded in an arbitrary order. So if your
main.styl file depended on bootstrap, the second example would be a more reliable way to load the two scripts to ensure that bootstrap loads before main.styl.
Now let's look at an example of using a manifest file, assuming that we now have a manifest file in our css folder like this:
assets ˻ css ˻ manifest.yml ˻ main.styl ˻ vendor ˻ bootstrap ˻ bootstrap.min.css ˻ extra.min.css ˻ bootstrap.plugin.min.css
And that the manifest file might look like this:
# manifest.yml - vendor/bootstrap/* - vendor/bootstrap.plugin.min.css - main.styl
And your roots config might look like this:
# app.coffee css_pipeline = require('css-pipeline') module.exports = extensions: [css_pipeline(manifest: "assets/css/manifest.yml")]
The manifest file's contents are just a yaml array, and it's parsed in the same way as if you had passed an array to the
files key. You might have also noticed that the root for all the file paths in the manifest file is the directory that the manifest file is in itself, so we didn't have to specify
assets/css on each one.
You can name the manifest file whatever you'd like, the filename and extension don't matter as long as the contents are valid yaml.
Injecting Scripts Into Views
When you use this extension, it will expose a function called
css to all your view files. When you call this function, the extension will drop in one or more link tags pointing to your scripts. If you specified an
out path, it will build all your input files into that file and drop a single link tag pointing to it. If not, it will link to each of your input files.
Note that the
css function accepts one optional argument, which is a path to prefix any injected scripts with. So for example if you wanted to have stylesheets load from the root of the site, you could pass in
/. By default, it would be the relative path
css/master.css, but calling with
/ would make it
Here's an example of using the
css function. This example uses jade but this will also work with any other templating language.
//- index.jade p here's my great website != css()
Now let's take a look at some sample output. With this configuration:
# app.coffee css_pipeline = require('css-pipeline') module.exports = extensions: [css_pipeline(files: 'assets/css/**', out: 'css/build.css')]
You would see this output, with the build file having all your input's matches concatenated together.
<!-- public/index.html --> <p>here's my great website</p> <link rel='stylesheet' href='/css/build.css' />
And without the
out path, as such:
# app.coffee css_pipeline = require('css-pipeline') module.exports = extensions: [css_pipeline(files: 'assets/css/**')]
You might see output like this, with each file loaded on its own:
<!-- public/index.html --> <p>here's my great website</p> <link rel='stylesheet' href='/css/foo.css' /> <link rel='stylesheet' href='/css/bar.css' /> <link rel='stylesheet' href='/css/baz.css' />
If you require absolute paths because your project has a nested structure as created by roots-dynamic-content you can pass
'/' to the helper like so:
//- layout.jade extended by posts/hello_world.jade != css('/')
String or array of strings (minimatch supported) pointing to one or more file paths to be built.
A path, relative to the roots project's root, to a manifest file (explained above), which contains a list of strings (minimatch supported) pointing to one more more file paths to be built.
If provided, all input files will be concatenated to this single path. Default is
Minfifies the output. Default is
Options to be passed into the minifier. Only does anything useful when minify is true. Possible options can be seen here.
Boolean, and only works when
out is also defined. Hashes the file contents and appends to the filename. This is typically used for cache-busting. Always puts the hash before the final extension, for example
file.x.y.HASH.css. The hash is a lengthy string of random numbers and letters, and the name change is automatically reflected by the
css function in your views. Default is