04-flamingo-carotene-modules.md

How to Flamingo Carotene Module

This is a guide to understand how the modules work and how you can develop and use your own ones.

Modules for Tooling

A module that is used for your tooling process will typically go into the devDependencies of your project and with that will not end up in the code you will serve to the client.

Flamingo Carotene is a collection of modules, which are "self-registered" - and can be combined by personal or project needs.

There are basically 2 kinds of Flamingo Carotene modules:

• Build and Build-Helper Modules

  Which can handle some jobs in your build process.

  Examples:

  • flamingo-carotene-es-lint
  • flamingo-carotene-webpack

• Client Modules

  Which runs in the browser, and should be part of your project (if needed)

  Examples:

  • flamingo-carotene-behavior
  • flamingo-carotene-state-manager

You can easily add a module to your project with:

npm i [-D] [MODULE-NAME]

Example:

npm i -D flamingo-carotene-es-lint  

How to create a new module

If you want to create a new module, the best way to start is to copy one module, which has the same scope.

You need to be sure, that following exists:

• package.json with
  • scripts
    • test
    • lint
    • build (optional, for browser module)
• flamingo-carotene-module.js (this is where the magic happens)

Create the flamingo-carotene-module.js - the M stands for Magic

It's simple and its easy!

Example Simple Module Skeleton

class MyModuleClass {
  constructor (core) {
    this.listeners = [
      {
        command: 'config',
        priority: 100,
        handler: function (core) {
          const config = core.getConfig()
          // add, change or manipulate some config values here
        }
      },
      {
        command: 'addBuildCommandTitleHere',
        handler: function (core) {
          // do some stuff here
        }
      },
      // ...
    ]
  }

  getListeners () {
    return this.listeners
  }
}

module.exports = MyModuleClass 

Example Module with fileWatcher

class MyModuleClass {
  constructor (core) {
    this.listeners = [
      {
        command: 'config',
        priority: 100,
        handler: function (core) {
          const config = core.getConfig()
          // add, change or manipulate some config values here
          
          config.myModule = {
            callback: null
          }
        }
      },
      {
        command: 'watchMyModule',
        handler: function (core) {
          // do some stuff here when a file has changed
        }
      },
      // ...
    ]

    this.watcher = [
      {
        'watchId': 'myModule',
        'path': [
          path.join(config.paths.src, '**', '*.foo')
        ],
        'command': 'watchMyModule',
        'callbackKey': 'myModule'
      }
    ]
  }

  getListeners () {
    return this.listeners
  }

  getWatchers () {
    return this.watcher
  }
}

module.exports = MyModuleClass

How to publish

Lint and Test your Stuff first!

Lint all modules

Inside the root directory (flamingo-carotene, the directory where this MD exists) simply run

npm run lint

Lerna will take care of running the lint script in all modules (if available)

Test all modules

If there are no linting errors you may call

npm t

Lerna will take care of running the test script in all modules (if available)

Publish with lerna

You can only publish versions if:

• Your stuff is lint-error-free!
• You've executed all tests (and there are no issues)
• git-status reports no dirty workspace

To bump the version of flamingo-carotene modules simply execute

npx lerna version

It will show you the current version and gives you the ability to select a new one.

So - as an example - if the current version is v6.0.1 you may want to select Patch Version to bump the version to v6.0.2.

After bumping the version of modules you should publish them to the registry.

To do this, execute

npx lerna publish

This will try to publish all modules.

Keeping packages up-to-date

To keep packages up-to-date and to reduce vulnerability please update all packages on a regular basis.

Run the following command one by one to update all packages and publish the result.

make cleanDep
make upgradeAll
make install
make build
make test
make link

Then link your project's flamingo modules to test the current version.

If everything is well publish the modules.

make publishToNpm

If you see any some errors during install or build you may want to run npm install and npm run build manually in those modules.