Skip to main content

Updating the admin

WordPress has built-in core/plugin/theme updates. Flexweg CMS doesn't — you build the new admin yourself (or download a release), upload the new dist/admin/ to Flexweg, and the new code is live.

User state survives the upgrade because it's all in Firestore (or external bundles already on Flexweg) — not bundled with the admin code.

What survives​

  • Posts, pages, terms, media — Firestore docs, untouched
  • Site settings (title, theme, plugins enabled, plugin configs, theme configs, menus) — Firestore, untouched
  • Users + roles — Firestore + Firebase Auth, untouched
  • Flexweg API key — Firestore, untouched
  • Installed external plugins / themes — dist/admin/plugins/<id>/ and dist/admin/themes/<id>/ on Flexweg, untouched
  • External registry — settings/externalRegistry in Firestore, untouched

So a new admin version drops in cleanly: same data, same plugins, same configuration.

What gets replaced​

The admin's bundled code:

  • index.html
  • assets/* (the JS + CSS bundles)
  • runtime/* (the runtime stubs for external bundles)
  • The bundled built-in plugin / theme bundles in dist/admin/plugins/ and dist/admin/themes/
  • external.default.json (the immutable build-time baseline)

When the new admin loads on next visit, it picks up the new code immediately.

Update workflow​

1. Build the new admin​

cd /path/to/flexweg-cms
git pull                    # or download a release tag
npm install --legacy-peer-deps
npm run build

Output: dist/admin/.

2. Upload to Flexweg​

Replace the existing /admin/ (or whatever folder name you used) on Flexweg with the new dist/admin/.

Two safe approaches:

  • Atomic rename — upload to /admin-new/ first, then rename /admin/ to /admin-old/ and /admin-new/ to /admin/. Rollback is one rename.
  • In-place overwrite — upload over the existing folder. Fast but a brief window of "mixed old + new files" if the upload is interrupted.

For most cases the in-place overwrite is fine.

3. Hard-refresh​

Tell admins to hard-refresh (Cmd+Shift+R / Ctrl+F5) the next time they visit. Browser cache might serve the old JS otherwise. After one hard-refresh, normal cache headers handle the rest.

4. Re-deploy theme / plugin assets​

The bundled built-in plugin / theme bundles are now updated, but the external CSS files for built-in themes (e.g. theme-assets/default.css) are still the OLD versions — those live on the public site, not in dist/admin/.

Run Themes → Sync theme assets to push the new CSS up.

5. Regenerate if necessary​

If the new admin version changed templates (e.g. a built-in theme template was tweaked), already-published HTML pages still reflect the old templates. Run Themes → Regenerate site → All HTML pages to push the new templates.

The release notes for each version should call out whether template-level changes happened — most patch releases don't, most major releases do.

What about external plugins / themes​

External plugins and themes installed in your admin:

  • Stay where they are on Flexweg (/admin/plugins/<id>/, /admin/themes/<id>/)
  • Their entries in settings/externalRegistry survive the admin update

If a new admin version bumps FLEXWEG_API_VERSION, externals built against an older apiVersion may need updating. The external loader checks the version at load time and refuses to load incompatible bundles.

Update process for an external you wrote:

  1. Bump your external's apiVersion in manifest.json to match the new admin
  2. Test against the new admin locally
  3. Re-package the ZIP
  4. Re-install via the Install plugin / Install theme UI (overwrite is safe — settings are preserved)

Externals from third-party authors: check their release notes for compatibility with the new admin version.

Reinstall bundled defaults​

The Plugins / Themes install modal exposes a Restore button when there's a delta between external.default.json (the new admin's baseline) and the live Firestore registry. Clicking merges the missing entries back.

Use this when:

  • A built-in plugin you previously uninstalled is back in the new admin and you want it again
  • A new built-in plugin shipped in this version

Rolling back​

If something breaks, roll back by re-uploading the previous dist/admin/. User data is untouched, so the rollback is non-destructive.

If you used the atomic rename approach: rename /admin-old/ back to /admin/. One operation.

If you in-place overwrote: you'll need to re-upload the old dist/admin/ from a backup. Keep the old build around for at least a few days post-upgrade.

Testing in staging first​

For high-traffic or business-critical sites:

  1. Run two Flexweg sites — staging.example.com and example.com (or staging / prod subdirectories on the same Flexweg)
  2. Two Firebase projects (or one project with separate Firestore databases — recently launched feature)
  3. Deploy admin updates to staging first
  4. Test against staging's data
  5. Deploy to prod after validation

The CMS doesn't ship a built-in staging flow, but the architecture supports it cleanly — every site is independent.

Watching for breaking changes​

Each release's CHANGELOG notes:

  • Breaking changes (typically API version bumps)
  • New built-in features
  • Removed features
  • Migration steps when relevant

For the most paranoid: read the diff between your current version's tag and the new tag. Look at:

  • src/services/publisher.ts — publish flow changes
  • src/core/types.ts — schema changes
  • Any new mandatory Firestore rules

Continue​