Crius

A flexible and modular gulp front-end workflow

With crius you can:

• Write CSS with Stylus
  • Build your website's grid with the RolleiFLEX declarative flex helper framework. (stylus)
  • Use simplified media queries with rupture (stylus)
  • Responsive font-size and other useful mixins
• Write modern Javascript
• See live changes (CSS/JS/HTML) on your project with browserSync
• Need to manage a new type of resource, like, let's say... sounds? Just define it in the crius.json and let the magic happen!

Requirements

• Node.js >= 8.6.0
• Gulp >= 4.x.x

Installation

1. git clone git@github.com:kaisermann/crius.git
2. npm install or yarn

Usage samples

• Selene - Wordpress theme based on Sage and Crius.
• Hyperion - A static web-app workflow based on Crius.

Theme Development

Build commands

Pretty much every task needed is covered by the package.json scripts:

• npm run watch|start - Run browsersync and watch file changes;
• npm run build - Build minified assets;
• npm run build:dev - Build unminified assets;
• npm run build:production - Build the assets, append a hash to the name;
• npm run clean - Remove the dist folder;
• npm run lint - Lint all styl and js files;
• npm run lint:styles - Lint all styl files;
• npm run lint:scripts - Lint all js files.

Gulp

• gulp / gulp build - Erases distribution directory and builds all assets
• gulp compile - Same as gulp build - without deleting distribution directory
• gulp clean - Deletes the distribution directory
• gulp watch - Starts watching the asset files
• gulp sizereport - Displays the size and gzipped size of your project
• gulp scripts|styles|fonts|images - Build the specified resource assets;
• gulp lint - Lint all styl and js files;
• gulp lint:styles - Lint all styl files;
• gulp lint:scripts - Lint all js files.

Creating new tasks

To create new generic gulp tasks, just create a file inside gulpfile.js/tasks, import gulp and create a task as if it was inside the gulpfile itself.

Gulp Parameters

You can also pass the following parameters to gulp:

• --sync Starts browserSync. Use only with gulp watch
• --report or -r Report mode
  • If used with watch, it will display the assets sizes of the current resource being edited
• --maps Allows sourcemaps to be created
• -d Asset debug mode. It won't minify the files
• -p Production mode. File names will be appended with a hash of its content for cache-busting

The available parameters can be extended at gulpfile.js/Flags.js.

Supported browsers

The supported browsers for CSS autoprefixing, eslint-compat plugin, etc can be configured by editing the browserslist array inside the package.json.

Manifest (crius.json) Documentation

The paths object

{
  "paths": {
    "source": "app/",
    "dist": "dist/",
    "manifest": "assets.json"
  }
}

The paths object MAY have a manifest string attribute that defines the revision manifest's file name on production distributions.

Defaults to "assets.json"

---

The crius.jon object MAY have a browserSync object if it's planned to use browserSync.

{
  "browserSync": {
    "mode": "proxy",
    "baseDir": "./",
    "index": "index.html",
    "devUrl": "localhost/crius",
    "watch": ["{lib,templates}/**/*.{php,html}", "*.{php,html}"],
    "whitelist": [],
    "blacklist": []
  }
}

watch is an optional array or a string of files to be watched by browserSync. Do not watch your asset files via browserSync as they are already being watched by gulp.watch. Defaults to [].

whitelist and blacklist are each one an optional array or a string of supposed watched files allowed/not allowed to be watched. Defaults to [].

mode is a optional string that defines in which mode should browserSync be initialized.

• In server mode, it creates a temporary server for your project.

• In proxy mode (default), it just proxies the devUrl to an already existing server.

With mode: "proxy"

• devUrl is a mandatory string that specifies your projects development proxy url.

With mode: "server"

• baseDir is a optional string that defines the root directory for the browserSync server (defaults to the gulpfile directory).

• index is a optional stringthat defines the entry file for the browserSync server (defaults to index.html)

---

The resources object

{
  "resources": {
    "scripts": {
      "pattern": "*.js",
      "directory": "scripts",
      "assets": {
        "main.js": {
          "files": "index.js"
        }
      }
    }
  }
}

---

Each resource type MAY have a directory string attribute, defining where the assets are inside paths.src and where the built ones will be inside paths.dist. If not specified, the resource type name will be used.

Each resource type MUST have a assets object, defining which assets are to be generated. The generated file output name is represented by the key:

...
  "assets": {
    "main.js": {
      "files": "index.js",
      "autoload": "path/relative/to/**/gulpfile.js"
    }
  }
...

The value can be either a string, an array of strings or an object with a MUST-HAVE files and an OPTIONAL autoload properties.

If a path begins with ~, crius references the node_modules directory. If not, the path is relative to the resource directory.

---

crius automatically creates a gulp task for each resource. All of a resource assets will be moved from the paths.source to paths.dist without you doing anything besides defining the resource in the crius.json.

If a resource assets need any type of processing, a drop-in module can be created at gulpfile.js/tasks/resources/${resourceName}.js to modify the stream with a lazypipe. The file name must match the resource name.

Resource module format:

const lazypipe = require('lazypipe')

module.exports = {
  // Names of tasks to be ran before/after the resource task
  tasks: {
    before: ['nameOftaskToRunBEFOREThisOne'],
    after: ['nameOftaskToRunAFTERThisOne'],
  },
  pipelines: {
    // Pipeline attached to each asset stream
    each: asset => {
      return lazypipe()
    },
    // Pipeline attached to all assets streams merged
    // Useful for manifests, etc
    merged: resourceInfo => {
      return lazypipe()
    },
  },
}

You can see other real examples by looking at the gulpfile.js/tasks/resources directory.

External links

• RolleiFLEX grid documentation
• Ruputure: Media Queries with Stylus documentation
• Sage documentation (Sage 9 uses webpack, please refer to the 8.. documentation.)

Credits and Inspirations

• Asset builder
• Sage Starter Theme