Federated wiki plugins render custom item types in wiki pages. Each plugin corresponds to an item `type` in the page JSON story — for example the `code` item type is rendered by `wiki-plugin-code`. The modern way to create a plugin uses the `create-wiki-plugin` scaffolding package by Paul Rodwell.
## Creating a Plugin
Run from the directory where you want the plugin folder created. The plugin name must be **capitalised** (CamelCase):
npm create wiki-plugin@latest MyThing # creates: wiki-plugin-mything/
Template repo: https://github.com/paul90/create-wiki-plugin — requires Node >= 22.x.
## Generated Structure
wiki-plugin-mything/ ├── src/client/mything.js ← edit this — your plugin logic ├── client/mything.js ← built output (npm run build) ├── scripts/build-client.js ← esbuild bundler ├── test/test.js ← node:test unit tests ├── pages/about-mything-plugin ← fedwiki about page ├── .github/workflows/ ← CI workflows ├── package.json └── eslint.config.js
## The Client Plugin File
The heart of the plugin is `src/client/mything.js`. It exports two functions — `emit` which renders the item into the DOM, and `bind` which attaches interactivity:
const emit = ($item, item) => { $item.append(`<p>${item.text}</p>`) } const bind = ($item, item) => { $item.dblclick(() => wiki.textEditor($item, item)) } if (typeof window !== 'undefined') { window.plugins.mything = { emit, bind } }
The `window.plugins.mything` registration tells the wiki client this plugin handles `type: "mything"` story items. `emit` builds the HTML; `bind` adds double-click-to-edit and other interactions.
## Building and Testing Locally
Build the plugin with esbuild (outputs minified JS to `client/`):
npm run build # bundles src/client/mything.js → client/mything.js npm test # runs node:test unit tests npm run about # starts wiki on port 3010 showing the about page
`npm run about` starts a local wiki server on port 3010 pointed at the plugin directory itself — browse to http://localhost:3010 to see your plugin rendering its own sample item.
## Installing into the Local Farm
Link the plugin into the wiki's node_modules so the farm discovers it automatically:
cd wiki-plugin-mything && npm link cd $(npm root -g)/wiki/node_modules && npm link wiki-plugin-mything
Then restart the wiki server with `wiki-stop` and `wiki-start`.
## Key Differences from Old Plugin System
The old system used Grunt for building. The new system uses: - **esbuild** — fast modern bundler - **ES modules** (`type: "module"` in package.json) - **node:test** — built-in, no external test framework - **prettier** and **eslint** out of the box - **GitHub Actions** CI workflows pre-configured - **Zed and VS Code** editor configs included
# Assets
creating-wiki-plugins