luci-theme-aurora reskins the OpenWrt router interface with Vite and Tailwind

A theme, not a fork of LuCI itself

luci-theme-aurora is described as a modern OpenWrt LuCI theme built with Vite and Tailwind CSS, and the project description is one line: A modern OpenWrt LuCI theme built with Vite and Tailwind CSS.

That framing matters for anyone who has installed themes on OpenWrt before. A LuCI theme is a package that replaces the presentation layer of the web interface while leaving the underlying LuCI application, its uci configuration and its LuCI JavaScript APIs in place. The Makefile in the repository root confirms the shape of that relationship. It includes the OpenWrt rules, sets LUCI_TITLE to Aurora Theme (A modern browser theme built with Vite and Tailwind CSS), and declares a dependency on luci-base with LUCI_DEPENDS:=+luci-base, then includes the standard LuCI build rules.

So the package is a normal OpenWrt package that depends on luci-base, and it installs into the router's LuCI theme directory. The repository tree matches: htdocs/ holds the static assets, root/ holds the LuCI theme metadata and menu files, ucode/ holds the template code, and there is a .dev/ directory for the development tooling.

The version scheme in the Makefile is the OpenWrt convention. PKG_VERSION is 1.4.0 and PKG_RELEASE is 20260920, and the licence is declared as Apache-2.0. The package version and the release build date are separate fields, so the release you install carries both a semantic version and the date it was packaged.

Installing from the feed, and the apk pinning trap

The one-command install runs on the router itself over SSH.

wget -qO- https://openwrt.eamonxg.fun/install.sh | sh

The documentation says that is the whole installation: the script adds the feed and installs whatever you tick from the list it shows. The feed is hosted at openwrt.eamonxg.fun, which is also the project homepage.

Upgrades then use the usual commands for your package manager, apk update and apk upgrade luci-theme-aurora, or opkg update and opkg upgrade luci-theme-aurora.

Then there is the note, and it is the kind of bug that wastes an afternoon. If the package was previously installed from a downloaded .apk file, that pinned it in /etc/apk/world, and apk upgrade will silently do nothing: success is reported and the version is unchanged. The fix is to run apk add luci-theme-aurora once, by name with no path, to clear the pin. The documentation notes that the install script already does this for you.

That is a real trap rather than a hypothetical one, because the manual install path below is exactly the thing that creates the pin. If you install by hand once and then switch to the feed, your upgrades stop silently.

Installing by hand, and telling apk from opkg apart

The manual route downloads a release artefact and installs it locally, and the package format depends on your OpenWrt version. OpenWrt 25.12 and snapshots use apk, and other versions use opkg. The tip is that you can confirm which you have by running opkg --version or apk --version, and if it returns output rather than not found, that is your package manager.

cd /tmp

# opkg
uclient-fetch -O luci-theme-aurora.ipk https://github.com/eamonxg/luci-theme-aurora/releases/latest/download/luci-theme-aurora_1.4.0-r20260920_all.ipk
opkg install luci-theme-aurora.ipk

# apk
uclient-fetch -O luci-theme-aurora.apk https://github.com/eamonxg/luci-theme-aurora/releases/latest/download/luci-theme-aurora-1.4.0-r20260920.apk
apk add --allow-untrusted luci-theme-aurora.apk

The two artefact names differ: the ipk name carries an r-prefixed release and the apk name is hyphenated, and the apk install needs --allow-untrusted because a locally downloaded package is not signed by the feed. The commands use uclient-fetch rather than wget, matching the documentation.

The version in those URLs matches the Makefile, 1.4.0 with release 20260920, and the release names in the project metadata follow the same shape, luci-theme-aurora-v1.4.0 dated 2026-09-19, with v1.3.0 on 2026-08-30 and v1.2.0 on 2026-08-08.

Browser requirements are high, and the fallback is honest about it

The compatibility section is where a potential user might get stuck, and it is worth reading precisely.

OpenWrt 23.05.0 or later is required, because the theme uses ucode templates and LuCI JavaScript APIs. For browsers, the theme is built with TailwindCSS v4 and the listed targets are Chrome and Edge 111+, Safari 16.4+, and Firefox 128+.

Those are floors, not aspirations. Chrome 111 and Safari 16.4 are from March 2023 and Firefox 128 from July 2024, which means a router admin who opens LuCI in an old browser on a device that never updates will see a broken or unstyled interface.

Then there is the optional enhancement, and the documentation is careful to separate it from the requirement. Same-document navigation, meaning no full page reload between view pages, uses the Navigation API where it is available: Chrome and Edge 105+, Safari 26.2+ and Firefox 147+. Browsers without it keep classic full-page navigation automatically, with no loss of function.

So the no-reload page switching is a progressive enhancement on top of a theme that works everywhere else. The feature list describes the payoff, switching pages only updates the content instead of reloading the whole page, with a claim of about 67 percent quicker per page switch at the median in the project's own measurements, and points to a router document explaining why it pays off. The credits go to luci-theme-footstrap, which took the cue for the no-reload behaviour.

What the theme adds on top of the LuCI shell

The feature list is where the theme's value is, and several items go beyond recolouring.

There is a theme switcher with switching between Auto, which follows the system, Light and Dark modes. There is a command palette on the Command key with K, for searching and jumping to any page from the header. There is a floating toolbar of clickable button icons for quick access to frequently used pages, and a custom background option for the login page and the admin interface.

The theme ships as an installable PWA, with a web app manifest and app icons, so LuCI can be installed to a home screen and launched like a native app. That is a meaningful feature for a router interface, because it turns an admin panel into something you can put on a phone's home screen.

Mobile-friendliness is stated as a goal rather than a checkbox, optimised for mobile interactions and display and supporting both smartphones and tablets.

Customisation is delegated to a separate plugin, luci-app-aurora-config, which ships five built-in theme presets and lets you customise the Light and Dark colour tokens, the navigation layout with Mega Menu, Dropdown and Sidebar options, layout density, typography, branding, page backgrounds and the floating toolbar, plus a theme store for browsing and sharing complete themes. That split is a sensible one: the theme stays a theme, and the configuration surface lives in a companion package that can be updated on its own.

Building it yourself with the OpenWrt build system

The build instructions assume the standard OpenWrt developer setup, with the toolchain documentation linked as the host prerequisite, and the output landing in bin/packages/<arch>/base/, for example bin/packages/x86_64/base/luci-theme-aurora_*_all.ipk, which you then copy to the router and install as described above.

There are two routes. The first is the full source tree.

# Full source tree — the openwrt-24.10 branch builds an .ipk, the main branch builds an .apk
git clone https://github.com/openwrt/openwrt.git
cd openwrt
git checkout openwrt-24.10

The comment records the same package format split as the install section, in the branch names this time: the openwrt-24.10 branch builds an .ipk and the main branch builds an .apk.

The alternative is the prebuilt SDK, which the documentation links as a shorter path.

The Makefile itself is four lines of real content. LUCI_MINIFY_CSS is empty and CONFIG_LUCI_CSSTIDY is empty, which means the theme does not use the LuCI CSS tidy step, a normal choice for a theme that brings its own Tailwind build rather than the stock LuCI stylesheet pipeline.

The repository also carries a CLAUDE.md and a .claude/ directory, a .dev/ directory with the router design document the feature list links to, a .github/ directory for the release workflow, and a README_zh.md for a Simplified Chinese version of the documentation.

Licence, cadence and the one thing to check before installing

The licence is Apache-2.0, and the Makefile header credits the copyright to eamonxg with the Apache License version 2.0, so the package metadata and the repository agree.

The release history shows a steady rhythm through the summer of 2026: v1.4.0 on 2026-09-19, v1.3.0 on 2026-08-30 and v1.2.0 on 2026-08-08, with the last push on 2026-09-19. The repository is not archived.

Before you install, the one thing to check is which package manager your OpenWrt release uses, because the two install paths are genuinely different and the artefact names differ. OpenWrt 25.12 and snapshots use apk, and everything older uses opkg, and a router that has been upgraded in place may not be on the version you assume.

The second thing to check is whether you have previously installed the theme from a downloaded file, because the apk pinning behaviour will make future upgrades report success while doing nothing. The install script handles that case, so using the feed avoids the trap entirely.

And the third is the browser, because a router admin interface accessed from a locked down or outdated browser is where a Tailwind v4 theme is most likely to look wrong.

Editorial conclusion

luci-theme-aurora fits an OpenWrt owner who spends real time in the router interface and wants it to look and behave like a modern web application, and who is comfortable adding a package feed or installing an ipk by hand. It does not fit a router running OpenWrt older than 23.05, because the theme depends on ucode templates and the LuCI JavaScript APIs, and it does not fit a browser older than Chrome 111, Safari 16.4 or Firefox 128. Before installing, check whether your OpenWrt release uses apk or opkg, because the two installers differ, and read the apk pinning note if you previously installed from a downloaded file, since a pinned package will report a successful upgrade while the version stays unchanged.

Frequently asked questions

Official sources

1. eamonxg/luci-theme-aurora on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases