Search by

ernestdefoe / seamless-refresh

ernestdefoe

Stop Flarum telling members to reload: new assets are picked up on the next click, and a session that ends under an open page recovers instead of failing every action.

Package info

github.com/ernestdefoe/seamless-refresh

Forum

Language:TypeScript

Type:flarum-extension

pkg:composer/ernestdefoe/seamless-refresh

Security

Advisories: 0

Aikido package health analysis

Transparency log

Statistics

Installs: 195

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

v0.2.0 2026-10-03 22:36 UTC

Requires

Requires (Dev)

None

Suggests

None

Provides

None

Conflicts

None

Replaces

None

MIT a472e4a34549df2b7f82f29448d853fe47f31627

  • ernestdefoe <ernestdefoe.woop@gmail.com>

assetsrefreshuxflarumflarum-extension

Published on Packagist.org on 2026-10-03 22:37 UTC

This package is auto-updated.

Last update: 2026-10-08 02:59:55 UTC

README

Stop Flarum telling your members to reload. When the forum's assets change, the next page they open quietly picks up the new version, and nothing interrupts them while they read or type. When a session ends under an open page, it recovers instead of throwing errors at every click.

Without Seamless Refresh: Flarum core's yellow "A newer version of this page is available. Reload" alert across the page

Without Seamless Refresh. This is the alert it replaces.

When Flarum's assets are rebuilt (a deploy, an extension switched on or off), every API response carries a new X-Flarum-Assets-Revision header. Core notices it differs from the one the page loaded with and shows that alert straight away, in the middle of whatever you were doing. On a busy forum whose assets change often, it feels like it's always asking you to reload.

Seamless Refresh takes the gentler approach luceos proposed on the Flarum tracker:

  • Never interrupts. When newer assets are detected, nothing appears. It just remembers.
  • Up to date on the next click. The next time you navigate (follow a link, open a discussion, go back or forward), the browser does a normal full page load of where you were going, so the new assets come with it.
  • Leaves drafts alone. Only a real navigation triggers the refresh, and the browser's own "unsaved changes" guard still protects an open composer.

When a session ends under an open page

Leave a tab open long enough and the session behind it expires. Flarum doesn't notice until the member does something: their reply, like or edit fails with an error, and so does every action after it, until they reload by hand. Asked for on discuss.flarum.org in Forcing page reloads/refreshes.

Seamless Refresh handles it:

  • Signed back in without noticing. With "remember me", the server signs the member straight back in, but the page still holds the old security token. Seamless Refresh fetches the new one and sends the failed action again. The reply posts; nothing appears.
  • Actually signed out. One calm notice, "Your session has ended. Sign in again to keep posting; this page stays as it is", with a Sign in button, instead of an error for every click.
  • A real "no". If the member genuinely isn't allowed to do something, Flarum's usual message shows as before.

Coming back to an old tab

A tab left in the background for five minutes or more, or a page a phone restores from memory, checks in once when it's looked at again:

  • Signed out meanwhile: the same notice.
  • Groups or permissions changed (promoted, demoted, granted something), signed in from another tab, or the forum updated: the next click loads its destination fresh, the same quiet way as new assets.
  • Nothing changed: nothing happens.

Settings

There are none. Enable it and you're done.

Good to know

  • How it works. It overrides core's checkAssetsRevision to set a flag instead of showing the alert, and adds a capture-phase click listener. While the flag is set, a click on an internal, same-origin link becomes a full page load (window.location.assign). Back and forward (popstate) reload too.
  • What it leaves alone. Clicks with a modifier key or a middle button ("open in new tab"), target="_blank" and download links, in-page anchors (#…), javascript:, mailto: and tel: links, and external links all behave exactly as normal.
  • Forum only. The admin panel keeps core's behaviour.
  • One tiny endpoint. GET /api/seamless-refresh/session answers who the browser is signed in as, plus a fingerprint of their groups and permissions. It's only called after a failed action or when an old tab comes back, never on a timer.

Installation

composer require ernestdefoe/seamless-refresh
php flarum cache:clear

Then enable Seamless Refresh in the admin panel.

Updating

composer update ernestdefoe/seamless-refresh
php flarum cache:clear

Credit

The behaviour is a direct implementation of the "refresh on the next natural interaction" idea luceos proposed as a middle ground between always interrupting and never warning. It's also being proposed for Flarum core.

Support

Licence

MIT.