Skip to content
✨ Publier v1 is live — a polished docs platform built for the open web.
On this page

Upgrades and Rollbacks

Upgrade CLI and framework packages separately, qualify the resulting build, and restore a working release.

The installed CLI and your project’s @publier/* packages have independent versions. Updating one does not update the other. Retain working source, dependency inputs, toolchain versions, and a deployable artifact before upgrading.

Record the current release

Run these from your site repository:

Terminal window
publier --version
node --version
bun --version
corepack pnpm --version
corepack pnpm list --depth 0
git rev-parse HEAD
git status --short

Record the deployed artifact or host release ID too. Commit existing work or use a separate branch/worktree; keep an upgrade separate from unrecorded changes. Build credentials stay outside source and deployment artifacts.

Upgrade the CLI

Terminal window
publier upgrade
publier --version
publier doctor

publier upgrade runs the canonical installer and replaces the binary with the latest published CLI. It does not edit dependencies or regenerate an existing project. The installer currently supports Linux x64 and verifies the binary against the release checksum.

Keep curl, tar, and sha256sum available. Supply the same PUBLIER_INSTALL_DIR when upgrading a custom installation prefix. Verify the executable your shell resolves with command -v publier.

Upgrade framework packages

Read the changelog and package release notes, then update the packages you use:

Terminal window
corepack pnpm update --latest @publier/native @publier/shell

For projects also using the optional packages:

Terminal window
corepack pnpm update --latest @publier/primitives @publier/openapi

Review and commit manifests and pnpm-lock.yaml together. Keep supported Astro, MDX, Qwik, Vite, Node, pnpm, and Bun versions aligned. Preserve docsShell() first and expressive-code before MDX in your integrations.

Workspaces with catalogs

Run updates at the workspace root. For members declaring catalog:, use pnpm and review pnpm-workspace.yaml alongside the lockfile:

Terminal window
corepack pnpm update --latest -r @publier/native @publier/shell

Retain catalog: specifiers rather than copying versions into each member. Qualify every affected site when a shared catalog changes. See pnpm update and catalogs.

Qualify before deployment

Restart the dev server after installing packages and hard-reload open tabs; old client modules can reference the previous dependency graph.

  1. In a clean candidate checkout, run corepack pnpm install --frozen-lockfile, then the project’s lint, tests, and type checks.
  2. Run corepack pnpm run build with valid build credentials.
  3. Serve that artifact. Exercise home/deep URLs, navigation, search, code copy, themes, and mobile menu. Include API/custom components you use.
  4. Deploy the same artifact. Check public HTTPS, assets, redirects, headers, and reader controls.

publier doctor diagnoses setup; it does not replace a build or validate the full dependency graph. See troubleshooting.

Roll back a site

Restore the previous qualified host release first. Restore the complete artifact, including HTML, hashed assets, and search index; mixing releases can leave references to missing files.

Make a normal Git revert of the upgrade commit, preserving later unrelated work. Restore manifests, catalog/overrides where present, and lockfile together. Reinstall with a frozen lockfile and rebuild through the same CI path. Redeploy after those checks pass.

To inspect old source without changing your current checkout:

Terminal window
git worktree add --detach ../docs-rollback <known-working-commit>

Replace the placeholder with the recorded revision. An old lockfile alone is insufficient if configuration, content, or toolchain also changed.

Roll back the CLI

Select an existing tag from Publier releases, matching the version you recorded. Pin the installer through PUBLIER_VERSION:

Terminal window
cli_installer=$(mktemp)
curl -fsSL https://publier.net/install.sh -o "$cli_installer" &&
  PUBLIER_VERSION=publier-cli-v0.0.24 sh "$cli_installer"
rm -f "$cli_installer"
publier --version

The tag above is an example released version; substitute your working tag. Supply PUBLIER_INSTALL_DIR for a custom prefix. Leave checksum verification enabled. CLI rollback does not restore packages or your deployed site.