Install and upgrade
Chinese version · English
xfm has zero runtime dependencies: nothing third-party is downloaded, so there is no dependency tree to conflict and no chain of transitive advisories in npm audit. Installation is a single download.
Requirements
| Item | Requirement | Check |
|---|---|---|
| Node.js | 18 or newer (22 LTS recommended) | node -v |
| npm | Ships with Node, 9+ recommended | npm -v |
1 | node -v |
On an older Node, npm fails with EBADENGINE and refuses to install. Switch with nvm or fnm:
1 | nvm install 22 && nvm use 22 |
Three ways to install
Option A: global install
Closest to the Hexo habit — install once, run xfm anywhere:
1 | npm install -g xfmpress |
Option B: run without installing
For a quick look, or a one-off build in CI:
1 | npx xfmpress --help |
npx downloads into a temporary cache and runs from there, leaving no global command behind. The trade-off is a possible network round-trip before each run.
Option C: project dependency
The right choice for teams and CI — pin the version in package.json so everyone gets an identical generator:
1 | mkdir my-blog && cd my-blog |
Then add scripts:
1 | { |
Use npm run dev / npm run build from then on; npx xfmpress info still works for one-offs.
You cannot scaffold a site with option C inside an empty directory — there is no node_modules yet, so xfm create is not available. Scaffold with option A or B first, then npm i -D xfmpress inside the site to switch to a local dependency.
Fixing permission errors
With a system-installed Node on macOS / Linux, npm i -g often fails with EACCES: permission denied. Do not use sudo — it leaves global packages owned by root, which makes later upgrades and removals worse. Two proper fixes:
1 | # Fix 1: move the global prefix into your home directory |
Verifying the install
1 | xfm --version # 0.4.13 |
Run xfm info inside a site to see the resolved configuration — theme, content directory, output directory, loaded plugins, Node version and core count:
1 | xfm info |
Plugins marked “auto” were discovered in the site’s package.json; the others are declared explicitly in the config.
Upgrading
1 | npm i -g xfmpress@latest # global |
Clear the cache afterwards so old output and the new engine do not mix:
1 | xfm clean && xfm build |
The versioning rule is unusual: the patch digit rolls from 0.4.0 to 0.4.99, then bumps to 0.5.0. A minor bump therefore means “one round of work is finished”, not “new features”. Read CHANGELOG.md to decide whether to upgrade.
Uninstalling
1 | npm uninstall -g xfmpress # global |
dist/ and .xfm/ are output and cache and can be deleted with the generator; content/ and xfm.config.mjs are your assets and have nothing to do with it.
Troubleshooting
xfm: command not found
The global npm bin directory is not on PATH. Run npm config get prefix, then add its bin subdirectory (%APPDATA%\npm on Windows) to PATH. With nvm, opening a new terminal usually fixes it.
Windows says the command is not recognized
Open a fresh Git Bash or PowerShell window first; if that fails, check that %APPDATA%\npm is in Path.
node -v is below 18
Upgrade Node, then reinstall: npm i -g xfmpress --force.
A plugin is installed but the build ignores it
Plugins are resolved at startup — restart xfm dev if it is running. Also confirm the plugin is installed in the site directory, not globally.
xfm new created a post that never shows up
Most likely draft: true. Set it to false or delete the line, then run xfm build again.
A build error starting with [xfm]
That is an error the engine raised deliberately, with a fix attached (a declared plugin that is not installed, for example). No stack trace — just follow the hint.
评论