Write a Plugin

Don't reinvent the wheel

Before writing a new plugin, first check the Plugin Registry to see if that plugin exists.

Nomenclature

Use the haraka-plugin-[UNIQUE] naming style.

Reference

• the Plugins section of the manual

package plugin for release on npm.

Clone the haraka-plugin-template and follow the instructions within.

Or set up the plugin directory yourself:

mkdir haraka-plugin-example && cd haraka-plugin-example
touch index.js       // plugin code goes here
mkdir config test
echo '[main]' > config/example.ini
echo "const fixtures = require('haraka-test-fixtures');" > test/main.js
echo '# haraka-plugin-example' > README.md
echo "# 1.0.0 - $(date +%Y-%m-%d)" > Changes.md
npm init
npm install --save <npm modules your plugin requires>
npm install --save-dev haraka-test-fixtures eslint @haraka/eslint-config

config loading

Use this standard method for config loading:

exports.register = function () {
    this.load_example_cfg()
}
exports.load_example_cfg = function () {
    this.cfg = this.config.get('example.ini', () => {
        this.load_example_cfg()
    })
}

• the callback added to config.get() lets your plugins config get updated immediately when the config changes. No Haraka restart required.
• storing the config contents at plugin.cfg lets the active configuration be accessed and manipulated by external processes. This is used heavily when adding test coverage.

booleans

If you have true/false booleans in your config, declare them and optionally, their defaults as well:

exports.load_example_cfg = function () {
    this.cfg = this.config.get('example.ini', {
        booleans: [
            '+enabled',               // this.cfg.main.enabled=true
            '-disabled',              // this.cfg.main.disabled=false
            '+feature_section.yes'    // this.cfg.feature_section.yes=true
        ]
    },
    () => {
        this.load_example_cfg()
    })
}

Lint testing with eslint

We ask that you use the coding style in @haraka/eslint-config. We've made it easy by publishing an eslint plugin that imports our rules automatically.

codeclimate

If you want a codeclimate badge to display in your README, you'll need to specify eslint version 8 in a .codeclimate.yml file.

engines: 
  eslint:
    enabled: true
    channel: "eslint-8"
    config:
      config: ".eslintrc.yaml"

ratings:
   paths:
   - "**.js"