v0.4.2 is the only release in the 0.4.x series with breaking changes — and the trade is worth it. Plugins are now fully decoupled from the core: independent npm packages, installed on demand, published separately. Read the upgrade notes carefully before updating.
What this release solves
Previously all nine plugins lived inside the core's lib/plugins/. You carried them whether you used them or not, customizing meant touching core code, and there was no boundary between "kernel" and "plugin" — which meant no third-party ecosystem was possible. v0.4.2 draws that line: the core renders; everything else is a package.
What changed
Breaking: plugins are no longer bundled
lib/plugins/ is gone. The nine plugins (xfm-plugin-sitemap, -rss, -feed-json, -search, -seo, -related, -llms, -minify, -reading-stats) now live in the repository's packages/ directory and are published as independent npm packages. Two concrete behavior changes:
- A site that used to write
plugins: ['rss']must now runnpm i -D xfm-plugin-rss. The upside: a missing plugin no longer silently falls back to a bundled copy — the build fails with the exactnpm icommand to fix it. xfm createwrites apackage.jsonwith nopluginsentry: new sites start with zero plugins and add what they need. Thexfm:<name>prefix and thelib/plugins/<name>.jsfallback were removed along the way.
Added: Hexo-style discovery and site.helpers
- Every
xfm-plugin-*(or@scope/xfm-plugin-*) dependency in your site'spackage.jsonis loaded automatically — no config change required. Short names inplugins: ['rss']resolve toxfm-plugin-rss. - Resolution order is explicit: site-local file (
./plugins/x.js) → sitenode_modules→ the CLI's ownnode_modules, so globally installed plugins work too. - New
site.helpers— a frozen, public helper set (absoluteUrl,withBase,normalizeBase,applyBase,plainText,markdownPlain,escapeHtml). Plugin packages no longer reach intoxfm/lib/...internals, so they work regardless of how the CLI was installed. xfm infolists declared and auto-discovered plugins side by side.- Four new tests (107 → 111) cover auto-discovery, duplicate registration, the missing-plugin error, and the architectural guarantee that the core depends on no plugin package.
Changed / Fixed
The repository is now an npm workspace (packages/*); npm publish --workspaces releases the whole plugin set, each with its own README. README and README_CN gained a complete Plugins chapter: install commands, a table of all nine official plugins (package, output, options), per-page front-matter switches, and a plugin-authoring example built on site.helpers. One docs fix too: the deployment note still mentioned scripts/pages-base.js, which was removed back in 0.4.0.
Should you change anything on upgrade?
Yes — one thing: make sure every plugin your site uses is installed as a devDependency, e.g. npm i -D xfm-plugin-rss. Short-name config entries stay unchanged. Getting it wrong is safe: the build fails and tells you exactly what to install. After upgrading, xfm info (covered in the CLI guide) is the quickest way to verify what loaded.
Comments