Front End Prototyper

Extensions

The extend directory is purposed for extending Fepper's functionality. Extensions can be contributed or custom. The extend directory will not be modified when updating Fepper.

Contributed extensions:

Install and update contributed extensions with npm in the extend directory.
Add the tasks to extend/contrib.js (and extend/auxiliary/auxiliary_contrib.js if necessary) in order for Fepper to run them.
Contributed Fepper extensions can be found at https://www.npmjs.com/search?q=fepper%20extension

Custom extensions:

Write custom extensions in the extend/custom directory.
Extensions require a file ending in "~extend.js" in order for Fepper to recognize their tasks.
The "*~extend.js" file can be directly under extend/custom, or nested one directory deep, but no deeper.
Add the tasks to extend/custom.js (and extend/auxiliary/auxiliary_custom.js if necessary) in order for Fepper to run them.
Fepper runs a self-contained instance of gulp to manage tasks. This gulp instance will be independent of any other gulp instance on your system.
For best results, set const gulp = global.gulp, not const gulp = require('gulp').
The fp command is an alias for gulp (among other things). Any fp task can be included in a custom task.
Fepper only supports gulp 3 syntax.

It may be helpful to write help text for a custom extension, especially when a person other than the author uses it. To do this, create a custom task appended by ":help". Declare and log the help text as follows, and it will be output by running fp extend:help.

'use strict';
const gulp = global.gulp;
gulp.task('custom-task:help', function (cb) {
  let helpText = `
Fepper Custom Task Extension
Usage:
    <task> [<additional args>...]
Task and description:
    fp custom-task:help    Print usage and description of custom task.
`;
  console.log(helpText);
  cb();
});

Confs and prefs:

You might need to access the values in the conf.yml and pref.yml files in order to write custom tasks. They are exposed through global.conf and global.pref (on the global Node object).

The values in patternlab-config.json are exposed through global.conf.ui. Please note that all paths in patternlab-config.json will be converted to absolute paths in global.conf.ui. Relative paths can be accessed through global.conf.ui.pathsRelative.

Utilities:

Common utilty functions for custom extensions are available from the Fepper Utils npm.

Object-oriented Fepper:

Beneath the gulp tasking system lies object-oriented Fepper. Running any fp task instantiates the Fepper class. This instance is exposed through the global.fepper object. By directly accessing the Fepper instance, you can run any Fepper operation without gulp. Deeper within Fepper lies the Patternlab class. By directly accessing Patternlab, you can run any Pattern Lab operation without Fepper. The Patternlab instance is attached to Fepper as global.fepper.ui.patternlab. The global.fepper object can, of course, be easily inspected in a console.

If there is something you wish were different about the Fepper class, or any of its member classes, you can inherit from the class, and make whatever changes you wish, without worry that your changes will be overwritten by the next update.

Here is an example of overriding the fp help command:

Create an instance_file. For this example, let's write it at extend/custom/hack-help.js.

'use strict';
const FepperSuper = require('fepper');
const HelperSuper = require('fepper/core/tasks/helper');
const TasksSuper = require('fepper/core/tasks/tasks');
class Helper extends HelperSuper {
  constructor(options) {
    super(options);
  }
  main() {
    console.log('ASYNC ALL THE THINGS!');
  }
}
class Tasks extends TasksSuper {
  constructor(options) {
    super(options);
    this.helper = new Helper(this.options);
  }
}
module.exports = class Fepper extends FepperSuper {
  constructor(cwd) {
    super(cwd);
    this.tasks = new Tasks(this.options);
  }
}

Declare instance_file in pref.yml.

instance_file: extend/custom/hack-help.js

Run fp help on the command line. It should log "ASYNC ALL THE THINGS!"

Hackers wishing to view the code for any of these classes will find that the ES6 syntax and object-orientation makes the code mostly self-documenting. The entry point to the Fepper class is in Fepper NPM at core/fepper.js.