Tidal Luna: a plugin platform injected into the Tidal desktop client

It works by replacing the app bundle inside Tidal

Luna is a client mod for the Tidal client and the successor to the project called Neptune. It lets developers create and users run plugins to modify and enhance the Tidal client. The mechanism is the part worth understanding before anything else, because it explains every installation instruction in the README. The Tidal desktop app is a packaged Electron application, and Luna replaces its app.asar with a directory of its own code, keeping the original alongside as original.asar. The manual install says to rename app.asar to original.asar, then unzip the luna.zip release into a folder named app in the resources directory beside original.asar. The result is a folder of Luna files next to the original bundle, and the original is still there if you want to back it out. The client is currently in beta, and the README says developer documentation is planned after the initial beta release.

The normal install is a Windows installer, and the FAQ lists the traps

The ordinary route is two steps. Install Tidal, then download and run the Luna Installer. The FAQ covers the things that go wrong. Luna does not support the Windows Store version of Tidal, and you should install the desktop version if you have the Store version. You should close Tidal before installing or the installation may fail, which makes sense given that the installer is rewriting the running application's files. And you should not need to run as administrator for installing. Once installed, starting Tidal shows the Luna splash screen. The Windows path is the polished one, since the Luna Installer is a separate project with its own releases, and the manual route is explicitly presented as only needed if the installer is not working for you.

Manual install, and the macOS signing step that stops it reverting

The manual procedure starts with downloading the luna.zip release you want from the TidaLuna releases page, then finding your Tidal resources folder. The README lists the three locations, and the fact that there are three says how thin the platform support really is.

- Windows: `%localappdata%\TIDAL\app-x.xx.x\resources` - MacOS: `/Applications/TIDAL.app/Contents/Resources` - Linux: `/opt/tidal-hifi/resources`

On macOS there is an extra step, because the operating system will revert an unsigned modification. You need to sign the new install so that it is not reverted, which the README does with a single command.

codesign --force --deep --sign - /Applications/TIDAL.app

The ad-hoc signature is enough to make the change stick. Skip it and macOS will quietly undo the whole installation the next time it validates the bundle, which is a confusing failure to debug if you do not know it is happening.

Nix users get an overlay or a package replacement

TidaLuna is managed through flakes, so the first step is adding it to your flake inputs.

inputs.tidaLuna = {
  url = "github:Inrixia/TidaLuna";
  inputs.nixpkgs.follows = "nixpkgs";
};

After that there are two ways to install the injected tidal-hifi client. The overlay approach adds the TidaLuna overlay to your nixpkgs overlay list, after which you install the tidal-hifi package as you used to.

nixpkgs.overlay = [
  inputs.tidaLuna.overlays.default
];

The package approach instead replaces your current tidal-hifi package with the new input.

environment.systemPackages = with pkgs; [
-  tidal-hifi
+  inputs.tidaLuna.packages.${stdenv.hostPlatform.system}.default
];

The overlay route is the smaller change and keeps the rest of your configuration untouched, while the package route is the more explicit one. The repository carries flake.nix and flake.lock, plus a nix directory and an .envrc for direnv, so the Nix support is a first-class part of the project rather than an afterthought.

The developer loop is a symlink into the Tidal app folder

Developer documentation is described as planned, but the client dev steps are in the README. You fork and clone the repository, install the packages with pnpm i, run the watch command with pnpm run watch, and then symlink your dist folder to the Tidal app folder. On Windows that is a directory link.

   mklink /D "%LOCALAPPDATA%\TIDAL\app-x.xx.x\resources\app" "./dist"

If you do not care about live reloading of the injector source, the alternative is to set the TIDALUNA_DIST_PATH environment variable to the path of your dist folder instead of making the link. The distinction between what reloads live and what does not is stated explicitly, and it matters for the inner loop. Core plugins under the plugins directory can be reloaded through the Luna settings, but changes to the render or native code require a client restart. The build is esbuild driven through a config file, with rimraf clearing the dist directory first, and the package is an ES module whose main entry is the injector script.

A small dependency list, mostly for the build

The package manifest shows that most of the weight is in the build rather than the runtime. The runtime dependencies are the inrixia helpers package, esbuild itself, clean-css and html-minifier-terser for producing the injected assets, and a set of type packages. The dev dependencies are React and React DOM types, prettier, rimraf, tsx for running the TypeScript build script, and TypeScript itself at version 7. The repository layout mirrors the architecture, with separate native, render and plugins directories, a build directory, an esbuild.config.ts, a luna.d.ts for the public types, and a pnpm workspace file with a lockfile. There is also a renovate configuration for dependency updates and a prettier config. The licence is MS-PL, the Microsoft Public License, which is a permissive choice similar in spirit to MIT but with the Microsoft patent grant. The release history is a run of beta tags, 1.17.1-beta on 2026-09-30, 1.17.0-beta on 2026-09-28 and 1.16.6-beta on 2026-09-01, and the last push was on 2026-10-12.

Editorial conclusion

Tidal Luna fits a developer who wants to write plugins for the Tidal desktop client and needs a live reload loop, and who is comfortable maintaining a patched copy of an Electron app. It does not fit a Windows Store install of Tidal, which the README says is unsupported, or anyone who wants a supported client. Verify first that you have the desktop version of Tidal rather than the Store version, expect to re-apply the install after a Tidal update since the app folder is replaced wholesale, and read the MacOS code signing step, because without it the installation is reverted.

Frequently asked questions

Official sources

1. Inrixia/TidaLuna on GitHub
2. Issues
3. License: MS-PL
4. README
5. Releases