@smart-cloud/publisher-exporter

@smart-cloud/publisher-exporter is the standalone Node.js CLI package behind WP Suite Static Publisher crawl, deploy, invalidate, and queue-runner workflows.

It is designed to run outside WordPress. The WordPress plugin only manages runtime config, queue state, and logs.

Install

Global install:

npm install -g @smart-cloud/publisher-exporter
publisher-exporter install-browsers

Without a global install:

npx @smart-cloud/publisher-exporter install-browsers

If multiple users may run jobs on the same host, prefer a shared Playwright browsers path:

export PLAYWRIGHT_BROWSERS_PATH=/var/lib/playwright-browsers
publisher-exporter install-browsers

If PLAYWRIGHT_BROWSERS_PATH points to a shared system directory, create that directory first and make it writable by the same OS user that will run publisher-exporter install-browsers. A one-time elevated setup step to create or re-own the directory is fine. The later cron job does not need elevated privileges to use an already installed shared browser cache, but it does need read and execute access to that directory tree.

Commands

PUBLISHER_CONFIG=./publisher.config.json publisher-exporter crawl
PUBLISHER_CONFIG=./publisher.config.json publisher-exporter deploy
PUBLISHER_CONFIG=./publisher.config.json publisher-exporter invalidate
publisher-exporter publish
publisher-exporter queue-runner --runtime-dir /srv/site/runtime --max-jobs 1

Equivalent npx usage:

PUBLISHER_CONFIG=./publisher.config.json npx @smart-cloud/publisher-exporter crawl
PUBLISHER_CONFIG=./publisher.config.json npx @smart-cloud/publisher-exporter deploy
PUBLISHER_CONFIG=./publisher.config.json npx @smart-cloud/publisher-exporter invalidate
npx @smart-cloud/publisher-exporter queue-runner --runtime-dir /srv/site/runtime --max-jobs 1

Queue Runner

The queue runner reads the runtime JSON files generated by the WordPress plugin.

Example:

publisher-exporter queue-runner \
  --runtime-dir /var/www/site/wp-content/uploads/smartcloud-static-publisher/runtime \
  --max-jobs 1

Direct CLI invocation from cron is the recommended setup.

When the runtime config contains enabled scheduler rules and the active queue-runner policy allows scheduler auto-enqueue, queue-runner evaluates those rules once at startup before draining queued jobs.

• Scheduler rules are read from runtime/config.json and their last interval buckets are persisted in runtime/scheduler-state.json.
• Scheduler only auto-enqueues jobs into the runtime queue. It does not replace cron, systemd timers, or Windows Task Scheduler.
• A 1-minute external runner tick is the recommended cadence.
• Supported scheduled commands are publish, crawl, deploy, invalidate, retry-timeouts, and url.
• The scheduler timezone value is currently informational for operations context; interval matching is based on elapsed minute buckets checked at each queue-runner start.
• If an equivalent queued or running job already exists for the same command, crawl mode, deployment profile, and URL, that rule is skipped for the current interval bucket.

Same-host Linux cron example:

SHELL=/bin/bash
HOME=/home/<runner-user>
PATH=/home/<runner-user>/.nvm/versions/node/v24.15.0/bin:/usr/bin:/bin
PLAYWRIGHT_BROWSERS_PATH=/var/lib/playwright-browsers
RUNTIME_PATH=/var/www/site/wp-content/uploads/smartcloud-static-publisher/runtime
LOG_PATH=/var/www/site/wp-content/uploads/smartcloud-static-publisher/logs

* * * * * /usr/bin/flock -n /tmp/static-publisher.cron.lock publisher-exporter queue-runner --runtime-dir "$RUNTIME_PATH" --max-jobs 1 >> "$LOG_PATH/queue-runner-cron.log" 2>&1
17 3 * * * publisher-exporter prune-logs --runtime-dir "$RUNTIME_PATH" --older-than-days 30 >> "$LOG_PATH/prune-logs-cron.log" 2>&1

If WordPress and the runner are on different machines but share the same mounted publisher storage, keep outputDir and logDir storage-relative in WordPress admin and point cron at the crawler host's local mount path:

SHELL=/bin/bash
HOME=/home/<runner-user>
PATH=/home/<runner-user>/.nvm/versions/node/v24.15.0/bin:/usr/bin:/bin
PLAYWRIGHT_BROWSERS_PATH=/var/lib/playwright-browsers
RUNTIME_PATH=/mnt/site/runtime
LOG_PATH=/mnt/site/logs

* * * * * /usr/bin/flock -n /tmp/static-publisher.cron.lock publisher-exporter queue-runner --runtime-dir "$RUNTIME_PATH" --max-jobs 1 >> "$LOG_PATH/queue-runner-cron.log" 2>&1

If you do not want a version-pinned NVM path in crontab, create a stable user launcher in ~/bin and put that directory first in PATH:

mkdir -p "$HOME/bin"
cat > "$HOME/bin/publisher-exporter" <<'EOF'
#!/usr/bin/env bash
set -euo pipefail
export HOME=/home/<runner-user>
export NVM_DIR="$HOME/.nvm"
. "$NVM_DIR/nvm.sh"
nvm use default >/dev/null
exec "$(npm prefix -g)/bin/publisher-exporter" "$@"
EOF
chmod +x "$HOME/bin/publisher-exporter"

If cron already sets the correct HOME, remove the explicit export HOME=... line from the wrapper. A plain symlink to ~/.nvm/versions/node/vX.Y.Z/bin/publisher-exporter will break after upgrades. Prefer this small launcher, or enable an NVM-managed current symlink and link against that stable path.

After each finished, failed, or stopped job, queue-runner copies the exporter-generated working logs into "<logDir>/archive/<timestamp-command-jobId-status>/" and includes a job.json summary plus the latest current-progress.json snapshot when available. The live root log files remain the current working set and may be overwritten by the next job.

Archived files are gzip-compressed per file and listed in job.json. WordPress Audit Log rows can download those archived artifacts through the authenticated REST API.

retry-timeouts uses the newest archived full crawl or publish job log snapshot as its timeout source. It prefers the manifest-backed archived errors.* artifact when available and falls back to older uncompressed archive layouts.

Prune old archive directories with publisher-exporter prune-logs --runtime-dir /srv/site/runtime --older-than-days 30. Add that command to daily cron or another retention scheduler that matches your log policy.

WordPress Integration

The companion WordPress plugin can optionally store an External exporter dir setting. Point it at this package root when you want PHP-side diagnostics to verify the local CLI install.

Typical values:

• /usr/local/lib/node_modules/@smart-cloud/publisher-exporter
• /opt/smartcloud/publisher-exporter/node_modules/@smart-cloud/publisher-exporter

Notes

• Playwright browser binaries are separate from the npm package and may need reinstalling after Playwright version upgrades.
• For internal/self-signed TLS origins, set ignoreHttpsErrors in publisher.config.json or through the WordPress admin UI.
• The package expects Node.js 20 or newer.