tafel-plugin-example

A minimal "hello world" plugin for Tafel — and a step-by-step guide to creating your own.

What it does

| Input | Output | |---|---| | hello world | 👋 | | hello | 👋 | | hi | 👋 | | hey | 👋 | | howdy | 🤠 | | goodbye | 👋 bye! |

Use this as a template

Follow these steps to create, test, and publish your own Tafel plugin.

1. Create the project

mkdir tafel-plugin-my-feature
cd tafel-plugin-my-feature
npm init -y

2. Set up package.json

Open package.json and make sure it has these fields:

{
  "name": "tafel-plugin-my-feature",
  "version": "1.0.0",
  "description": "A short description of what your plugin does.",
  "type": "module",
  "main": "index.js",
  "keywords": [
    "tafel-plugin"
  ],
  "tafel": {
    "id": "community:my-feature",
    "displayName": "My Feature",
    "description": "A short description of what your plugin does.",
    "category": "utility"
  },
  "author": "your-npm-username",
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "https://github.com/your-username/tafel-plugin-my-feature"
  }
}

Key things:

• "type": "module" — required. Tafel loads plugins as ES modules via esm.sh.
• "keywords": ["tafel-plugin"] — required. This is how Tafel's Plugin Store discovers your plugin on npm.
• "tafel" — optional metadata used by the Plugin Store UI (display name, category, etc.).
• "repository" — strongly recommended. Plugins without a public GitHub repo show a warning in the store.

3. Write the plugin

Create index.js (or index.ts — esm.sh handles TypeScript). Your file must default-export a plugin object:

const plugin = {
  // ─── Required fields ───────────────────────────────────
  id: 'community:my-feature',   // MUST start with "community:"
  name: 'My Feature',
  version: '1.0.0',

  // ─── Optional but recommended ──────────────────────────
  description: 'What your plugin does in one sentence.',
  author: 'your-npm-username',
  source: 'community',
  examples: [
    { input: 'example input', output: 'example output' },
  ],

  // ─── The action (this is where the magic happens) ──────
  action: {
    priority: 100,        // must be >= 100 (0–99 is reserved for built-ins)
    resultType: 'string', // 'number' | 'string' | 'date' | 'boolean' | 'comment' | 'error' | 'variable'

    match(ctx) {
      // Return true if your plugin should handle this line.
      // ctx.input is the trimmed line text.
      return ctx.input.toLowerCase() === 'example input'
    },

    evaluate(ctx) {
      // Return the result string, or null to pass to the next plugin.
      return 'example output'
    },
  },
}

export default plugin

The ctx object

Your match and evaluate functions receive an evaluation context:

| Property | Type | Description | |---|---|---| | ctx.input | string | The current line's text (trimmed) | | ctx.prev | string | The previous line's result value | | ctx.lineIndex | number | Zero-indexed line number | | ctx.parser | Parser | The math.js parser (with accumulated variable scope) |

Priority

• Must be >= 100. Values below 100 are reserved for built-in plugins and are automatically clamped.
• Lower numbers run first. If you want your plugin to run before other community plugins, use a lower number (e.g. 100). If you want it to run later, use a higher number (e.g. 200).
• If two plugins share the same priority, built-in plugins always win. Among community plugins, install order is preserved.

4. Test locally

Add a test.js file to verify your plugin works before publishing. See test.js in this repo for a complete example — it tests plugin shape, match(), and evaluate() with no dependencies:

node test.js

Expected output:

Plugin shape:
  ✓ has required id starting with "community:"
  ✓ has required name
  ✓ has required version
  ✓ action.priority is >= 100
  ✓ action.match is a function
  ✓ action.evaluate is a function

match():
  ✓ "hello world" matches
  ...

evaluate():
  ✓ "hello world" → 👋
  ...

15 passed, 0 failed

The test file checks three things you should always verify:

1. Plugin shape — all required fields exist and have the right types
2. match() — returns true for inputs you handle and false for everything else
3. evaluate() — returns the correct output for each matched input

5. Publish to npm

# Log in to npm (one-time)
npm login

# Publish the package
npm publish

That's it! Once published, your plugin will appear in Tafel's Plugin Store → Browse tab when users search for it.

6. Update your plugin

When you make changes:

1. Bump the version in both package.json and your plugin's version field.
2. Run npm publish again.
3. Users will see an update available in the Plugin Store.

Validation rules

Tafel validates every community plugin at load time. If any rule fails, the plugin won't load:

| Field | Rule | |---|---| | id | Non-empty string starting with community:. The built-in: prefix is rejected. | | name | Non-empty string. | | version | Non-empty string (semver recommended). | | action.priority | Number ≥ 100. Values below 100 are clamped with a warning. | | action.match | Function. | | action.evaluate | Function. |

License

MIT