Publish a plugin

A plugin package lets other projects use your plugin with one line of config.

Name the package

Name the package x18n-plugin-<name>, or @<scope>/x18n-plugin-<name>. Then YAML and JSON configs can load it by name, and users can find it on npm.

Export the plugin

The default export of the package is a plugin, a preset, or a function that takes options and returns one:

import { definePlugin } from '@x18n/core'

export default definePlugin((options: { strict?: boolean } = {}) => ({
  name: 'x18n-plugin-acme',
  checks: [
    // ...
  ],
}))

Put x18n in the peerDependencies of the package, so that the plugin uses the x18n version of the project.

Use it

In a TS config, import the package and call the factory:

import { defineConfig } from '@x18n/core'
import acme from 'x18n-plugin-acme'

export default defineConfig({
  plugins: [acme({ strict: true })],
})

In a YAML or JSON config, use the package name. Pass options as the second item of a tuple:

plugins:
  - x18n-plugin-acme
  - [x18n-plugin-other, {strict: true}]

x18n resolves the name from the directory of the config file, imports the package, and calls its default export with the options. If the package is missing, the load stops with X18N1001.

Ship a YAML plugin

A package can also ship a YAML plugin file. Users then list its path:

plugins:
  - ./node_modules/x18n-plugin-acme/acme.x18n-plugin.yml

Checklist

• Give the plugin a unique name, and do not use the x18n: prefix of the built-in plugins.
• Give each check, format and reporter a unique id. Prefix the ids with the name of your plugin to avoid conflicts.
• Add types for your check ids and options through declaration merging. See Typed config keys.
• Set runtime: 'node' if the plugin needs Node APIs.