FreeScout Night Mode

A free, open-source night theme for the FreeScout agent & admin UI, with a Light / Dark / System toggle in the header. The preference is saved per user in the browser — so if one agent prefers light and another prefers dark, they never override each other, even on a shared workstation.

There's also an optional Extended Design Mode ("Aurora") — Beta: a bolder, premium redesign (soft elevated cards, depth, one calm accent). Enable it under Settings → Night Mode. It's still being polished, so a few spots may look rough — feedback welcome.

• Additive & isolated — own module alias (nightmode), own namespace. Every hook is fail-open: if anything goes wrong it silently falls back to the normal light UI and never white-screens FreeScout.
• Scoped CSS — all styles live under a single body.nm-dark class, so with night mode off the module has zero visual effect.
• No flash — a tiny inline head snippet sets the theme before first paint, so reloading a page in night mode doesn't flash white.
• No database bloat — only two global admin options are stored (on/off + default mode). Each user's actual choice lives in their browser's localStorage, keyed by their FreeScout user id.
• Update-capable — updates in place through FreeScout's Modules manager, the same way as any FreeScout module.

Requirements

• FreeScout 1.8.0 or newer.
• PHP 7.3+ (same as FreeScout).

Install

1. Download NightMode.zip from the latest release.
2. Extract it into your FreeScout Modules/ directory. The folder must be named exactly NightMode:

   Modules/NightMode/module.json
   Modules/NightMode/Providers/...
   

   (You can also upload the ZIP via Manage → Modules → Install if your FreeScout build supports ZIP upload.)
3. In FreeScout go to Manage → Modules, find Night Mode, and click Activate.
4. Open Manage → Settings → Night Mode to set the global default (or leave it on System). Each user then picks their own via the header toggle.

Update

When a new version is released, FreeScout's Manage → Modules page shows an Update button for Night Mode (it compares your installed module.json version against the latest release). Click it to update in place.

Manual update: replace the Modules/NightMode/ folder with the new release's contents, then clear the cache (see Recovery).

Usage

A small control appears in the top navbar:

Icon	Mode	Behaviour
☀	Light	Always light.
☾	Dark	Always dark.
⌂	System	Follows your operating system's light/dark setting.

Your choice is remembered per user, per browser.

Recovery / troubleshooting

If a page ever looks broken after install/update:

1. Make sure the folder is named NightMode (not freescout-dark-mode).
2. Clear FreeScout's caches:

   php artisan freescout:clear-cache
   rm -rf storage/framework/cache/data/*

3. Reload with a hard refresh (Ctrl/Cmd+Shift+R) to bust the browser CSS cache.

Because the module is fail-open, disabling it under Manage → Modules (or turning it off under Settings → Night Mode) instantly returns the UI to the stock light theme.

Development

composer install
composer test        # PHPUnit
find . -name '*.php' -not -path './vendor/*' -print0 | xargs -0 -n1 php -l

CI lints every PHP file and runs PHPUnit on each push. Tagging vX.Y.Z (matching module.json's version) builds and attaches NightMode.zip to a GitHub release.

License

MIT © erorplex