boards

    3.2.1 • Public • Published

    Boards

    A minimalistic and extendable code generator/manipulator base.

    This project allows you to generate and manipulate code easily, making it a breeze to build your own cli. This means you can embed it your own cli tool without having to call extra tools (gulp, yo, etc).

    An (very cool, try it) example can be found here: Boards-cli.

    Boards makes use of plugin-discovery to discover plugins in your projects.

    Features

    • Code formatting New!
    • Register boards
    • Generators
    • Register steps
    • Manages stream
    • Finds boards in project dependencies

    As of v3, Boards allows you to automatically format code when using the default generators (Modification and Template). To do this, it uses prettier to do base formatting, and then applies eslint rules (using cwd) to make any code adjust to whatever project it's being used in. To enable this option, set format to true. Read more in the format section of the readme

    Installation

    npm i -D boards

    Usage

    Code speaks a thousand... Codes. Here's an example:

    let boards = new Boards({
      discoveryConfig: {
        prefix               : 'my-prefix',
        dictionaryKeyStrategy: PluginDiscovery.constants.STRATEGY_STRIP_PREFIX,
        configurers          : {
          myconfigurer: (key, plugin, rootImport) => {
            // Custom configuration
          }
        }
      }
    });
     
    boards.generate('generatorNameOrClass', {parameters: 'go here'});

    An overview of options:

    {
      steps          : steps,
      generators     : {},
      sourceType     : 'file', // url or file (treats source value differently)
      discovery      : true, // Enable plugin discovery or not
      discoveryConfig: {}, // options for plugin-discovery
    }

    Note: Options for plugin discovery can be found here.

    Generator

    A generator is responsible for generating or manipulating a file, and supplying the steps to do so.

    Default generators

    This project comes with two default generators that can be extended or utilized.

    TemplateGenerator

    const {ModificationGenerator} = require('boards');

    This is probably the easiest a generator gets. It runs the following steps:

    • read
    • replace
    • write
    • format

    This generator is useful for copying template files into your project. Because the replace step uses Procurator for templating, you can make your templates dynamic.

    CopyGenerator

    const {CopyGenerator} = require('boards');

    This generator performs a quick and easy copy using the following steps:

    • read
    • write

    This generator is useful for copying static files into your project (think assets, images etc).

    ModificationGenerator

    const {TemplateGenerator} = require('boards');

    The modification generator included runs the following steps:

    • read
    • modify
    • replace
    • write
    • move
    • format

    This is useful to quickly edit existing files in your project and also allows using parameters in your replacement strings! Read the docs on steps below to find out how to use them.

    Custom generator

    Here's an example (skeleton) generator to give you an idea of what is involved.

    const {Generator} = require('boards');
    const emoji       = require('node-emoji');
    const path        = require('path');
     
    class SkeletonGenerator extends Generator {
      static defaults() {
        return {
          sourceDirectory: path.join(__dirname, '../templates'),
          targetDirectory: path.join(process.cwd()),
          sourceFile     : `upper.template`,
          extension      : 'html'
        };
      }
     
      prepare(parameters) {
        console.log('\n', emoji.get('coffee') + ` Preparing parameters!\n`);
     
        parameters.targetFile = `${parameters.name}.${parameters.extension}`;
     
        return parameters;
      }
     
      generate(parameters) {
        console.log('\n', emoji.get('hourglass_flowing_sand') + ` Generating sincere greeting (with extra love)!\n`);
     
        return this.runSteps(['read', 'replace', 'upper', 'write']);
      }
     
      complete(stream) {
        console.log('\n', emoji.get('birthday') + ` Pointless file generated!\n`);
     
        return stream;
      }
    }
     
    module.exports = SkeletonGenerator;

    Step

    A step is an action through which the templates stream.

    Boards comes with a couple of default steps.

    Read

    The read step is usually the first step in a generator's flow. It is responsible for creating the read stream.

    Parameters

    There are a couple of parameters you can pass in to change the behavior of this step.

    Key Type Default Description
    sourceDirectory string '' Where to find the source files
    sourceFile string '' The name of the source file
    sourceType string 'file' One of url or file
    source string directory + file Combined parameter based on sourceDirectory and sourceFile
    sourceUrl string '' The url of the template if sourceType is url

    Note: Every generator gets to supply default values for these parameters; these are just the defaults for Boards.

    Replace

    The replace step allows the use of variables in your templates. Replace uses a tiny lib called Procurator, take a look at the docs to know what's possible. To give you an idea:

    <strong>Hello {{name:world}}</strong>

    All parameters passed in are available in your templates.

    Write

    The write step is generally the last step in a generator's flow and us responsible for writing the file to disk.

    Parameters

    There are a couple of parameters you can pass in to change the behavior of this step.

    Key Type Default Description
    targetDirectory string '' Where to store the generated file
    targetFile string '' The name of the target file
    target string directory + file Combined parameter based on targetDirectory and targetFile

    Modify

    The modify step allows you to modify existing files in your project. This is useful when adding routes for example.

    Parameters

    To modify a file, use the modify property in the parameters.

    {modify: {patch: [{pattern, append, prepend, custom}]}

    Key Type Default Description
    patch {}/{}[] '' Patch instructions (object or array of objects)
    patch.pattern RegExp undefined Pattern to apply replacement on
    patch.append string undefined (optional) what to append to match
    patch.prepend string undefined (optional) what to prepend to match
    patch.custom function undefined (optional) callback for replace (uses stream-replace)

    Example

    parameters.modify = {
      patch: {
        pattern: /];\s*module/,
        prepend: `  '${name}',\n`
      }
    };

    Move

    The move step allows you to move a file. This is useful in combination with the modify step.

    Parameters

    To move a file, use the move property in the parameters.

    {move: {sourceFile, targetFile}}

    Key Type Default Description
    sourceFile string '' Full path to the file to move
    targetFile string '' Full path to the new location

    Example

    parameters.move = {
      sourceFile: path.join(parameters.sourceDirectory, parameters.targetFile),
      targetFile: path.join(parameters.sourceDirectory, parameters.sourceFile)
    };

    Format

    The format step allows you to format the file used in a generator.

    Note: Formatting should be applied after the write step.

    Parameters

    To format a file, use the format property in the parameters.

    {format: true}

    Key Type Default Description
    format boolean false Flag indicating if formatting should be applied

    Example

    parameters.format = true;

    Licence

    MIT

    Install

    npm i boards

    DownloadsWeekly Downloads

    91

    Version

    3.2.1

    License

    MIT

    Unpacked Size

    22.4 kB

    Total Files

    19

    Last publish

    Collaborators

    • rwoverdijk