An opinionated pipeline, modelled after the Rails asset pipeline. Designed for the benefits of speed, and access to CommonJS modules

Usage no npm install needed!

<script type="module">
  import pinionPipeline from '';


What is pinion?

  • Opinionated - modeled to mimic the rails asset pipeline, tasks are default to just work
  • Fast - designed for speed
  • Customisable - the pinionfile allows tweaking of the pipeline to match your workspace

pinion was born to replace the Rails asset pipeline, in a Rails workspace. Benefits over the Rails asset pipeline include:

  • speed
  • modernness (support for CommonJS)
  • less "magic" (everything is a gulp task)


npm install pinion-pipeline will install the package locally

npm install -g pinion-pipeline will provide a pinion CLI for you to use. Or, you can just $(npm bin)/pinion in your local workspace.


pinion's CLI is designed to mimic gulp.

  • pinion is equivalent to pinion default
  • pinion x runs the task x
  • pinion x y z runs the tasks x, y, and then z

Sample pinionfile.js

Not much is required to get going with simple tasks

module.exports = {
  tasks: {
    // build from src/javascripts/app.js to bin/bundle.js
    js: {
      entries: {
        bundle: ['app.js']

    // build from src/stylesheets/*.{scss,css} to bin/*.css
    css: {},

    // build from src/images/* to bin/*
    images: {}

But we can be more verbose for greater control

module.exports = {
  root: {
    src: './app/assets',
    dest: './public/assets'

  tasks: {

    js: {
      // with our `root`, this means take stuff from ./app/assets/javascripts
      src: 'javascripts',
      // and output it to ./public/assets
      dest: '.',

      // this will create a `shared.js` file of common code, to keep multiple files small
      extractSharedJs: true,

      // take a.js and b.js, and compile it to bundle.js
      entries: {
        bundle: ['./a.js', './b.js']

      // since we have locally `npm install jquery`d, we can set it up as a global
      globals: {
        jquery: ['

, 'jQuery']

      // Look for all *.js and *.coffee files
      extensions: ['js', 'coffee']

    // compile our SCSS
    css: {
      src: 'stylesheets',
      dest: '.',

      // options to pass to `gulp-autoprefixer`
      autoprefixer: {
        browsers: ['last 3 version']

      // options to pass to `gulp-sass`
      sass: {
        indentedSyntax: false

      extensions: ['scss', 'css']

    // images are minified
    images: {
      // split the images task into mutliple sub-tasks
      taskArray: [
        { src: 'images' },
        { src: 'vendor/images' },
      dest: '.'



Depending on the NODE_ENV, tasks perform differently. As a rule of thumb:

  • NODE_ENV=production - assets are minified and optimised as much as possible
  • NODE_ENV=development or no NODE_ENV - assets are left alone and just moved where possible, and map files are generated


Configurable tasks

Tasks with omitted configuration in the pinionfile.js will be omitted from the build sequence

All tasks accept the following arguments

Base options

  • src - the source directory (or an array of directories)
  • dest - the destination directory
  • fileGlob - a glob pattern to search for files within src
  • extensions - an array of file extensions (equivalent to fileGlob: '**/*.{a,b,c}')
  • ignore - a glob pattern of paths to be ignored
  • npm - whether node_modules should be searched as well as src


Uses webpack to compile Javascript code


  • extractSharedJs - create a shared.js file with common code shared between multiple entries
  • entries - a map of built file names, to an array of source files. E.g. { bundle: ['./a.js', './b.js'] } to create a bundle.js from an a.js and b.js
  • globals - a map of local npm packages to their aliases. E.g. jquery: [' , 'jQuery']
  • loaders - config for webpack loaders to be concatted onto the default Pinion loaders. (Pinion will search your package's node_modules for any loader dependencies it can't find in its own)
  • plugins - config for webpack plugins to be concatted onto the default Pinion plugins. (Pinion will search your package's node_modules for any plugin dependencies it can't find in its own)
  • cssModules - a boolean of whether you want to use CSS modules for CSS imports (excluding imports from node_modules)
  • envVars - a list of the environment variables that should be accessible in the built JS files with process.env (NODE_ENV is always exposed)


Uses node-sass to compile SCSS code


  • autoprefixer - options passed to gulp-autoprefixer
  • sass - options passed to gulp-sass


Minifies images in production mode


Uses gulp-svgstore to combine all SVGs into a sprite.svg file


Moves fonts from src to dest


Moves miscellaneous resources from src to dest. It can accept an array of src/dest objects

Task splitting

Tasks can be split into multiple sub tasks, as in the following example

resources: {
  npm: true,
  taskArray: [
      src: 'config',
      dest: 'config'
      src: 'pdfs',
      fileGlob: '**/*.pdf',
      dest: '.'

Where the resources task will be run twice, with equivalent configs of

  npm: true,
  src: 'config',
  dest: 'config'


  npm: true,
  src: 'pdfs',
  fileGlob: '**/*.pdf',
  dest: '.'

Non-configurable tasks


Clean the workspace, and build and watch the workspace


In development mode, builds everything, and also watches for changes in your workspace


Runs through all of the build tasks


pinion rev will revision all of your assets. Also known as "fingerprinting" in Rails.

This adds a hash to the end of your files, unique to their content. This aids in cache-busting (index.html files are not revisioned).

A rev-manifest.json will be created with the mappings from the original file name, to the new file name.

As an example of how to use this rev-manifest.json, this is a sample of some Rails code leveraging the rev-manifest.json

def asset_path(path)
  path = "/assets/#{path}"
  path = REV_MANIFEST[path] || path if defined?(REV_MANIFEST)


If you have an ASSET_HOST environment variable, this will prepend that variable to the mapped values of your rev-manifest.json

For example, a rev-manifest.json of this:

  "someFile.png": "/assets/someFile.png"

with an ASSET_HOST=, would generate the following:

  "someFile.png": ""


Wipes the root.dest directory