feat: standalone web app decoupled from electron (#365)

Author: adidahiya

README.md

@@ -52,6 +52,19 @@ can:
 The source code for the app lives in the
 [`raga-app` package](https://github.com/adidahiya/raga/blob/main/packages/raga-app/README.md).
 
+### For Web Developers: `raga-web-app`
+
+The web UI components of _raga_ have been extracted into a separate package called
+[`raga-web-app`](https://github.com/adidahiya/raga/blob/main/packages/raga-web-app/README.md).
+This allows the UI to be:
+
+- Run as a standalone web application for testing and development
+- Deployed to static web servers for preview and demonstration
+- Embedded within the Electron app for the full desktop experience
+
+The web app provides a limited set of features when running outside of Electron due to browser
+security restrictions, but it's useful for UI development and testing.
+
 ### For developers: `raga-lib` and `raga-cli`
 
 Much of _raga_'s data management functionality lives in a separate Node.js library called
@@ -79,6 +92,8 @@ Getting started:
 
 Dev tasks:
 
+- `yarn dev:web` - runs the web app in standalone mode at http://localhost:3000
+- `yarn dev:electron` - runs the full Electron app with all features enabled
 - `yarn build` - builds TypeScript sources and bundles up the Electron app
 - `yarn dist` - creates the Electron app distributable package
 

eslint.config.mjs

@@ -62,7 +62,7 @@ export default tseslint.config(
     },
   },
   {
-    files: ["packages/raga-app/src/client/**/*.{ts,tsx}"],
+    files: ["packages/raga-web-app/src/**/*.{ts,tsx}"],
     plugins: {
       react: reactPlugin,
       "react-hooks": fixupPluginRules(reactHooksPlugin),
@@ -71,10 +71,6 @@ export default tseslint.config(
       ...reactPlugin.configs["recommended"].rules,
       ...reactPlugin.configs["jsx-runtime"].rules,
       ...reactHooksPlugin.configs.recommended.rules,
-      // HACKHACK: until we can get Sass CSS modules type-checked
-      "@typescript-eslint/no-unsafe-assignment": "off",
-      "@typescript-eslint/no-unsafe-member-access": "off",
-      "@typescript-eslint/no-unsafe-argument": "off",
       // unnecessary with TypeScript
       "react/prop-types": "off",
     },

package.json

@@ -11,6 +11,8 @@
     "check-lint": "nx run-many -t check-lint",
     "check-types": "nx run-many -t check-types",
     "clean": "nx run-many -t clean",
+    "dev:web": "yarn workspace @adahiya/raga-web-app dev",
+    "dev:electron": "yarn workspace @adahiya/raga-app dev",
     "dist": "nx run-many -t dist",
     "fix-format": "prettier --write \"./**/*.{js,json,md,scss,ts,tsx,yaml,yml}\"",
     "fix-lint": "nx run-many -t lint-fix"

packages/raga-app/package.json

@@ -19,62 +19,30 @@
   },
   "dependencies": {
     "@adahiya/raga-lib": "workspace:^",
-    "@emotion/react": "^11.14.0",
-    "@mantine/colors-generator": "^7.17.3",
-    "@mantine/core": "^7.17.3",
-    "@mantine/dates": "^7.17.3",
-    "@mantine/dropzone": "^7.17.3",
-    "@mantine/form": "^7.17.3",
-    "@mantine/hooks": "^7.17.3",
-    "@mantine/modals": "^7.17.3",
-    "@mantine/notifications": "^7.17.3",
-    "@mantine/nprogress": "^7.17.3",
-    "@mantine/spotlight": "^7.17.3",
-    "@number-flow/react": "^0.5.8",
-    "@roarr/browser-log-writer": "^1.3.0",
-    "@table-library/react-table-library": "^4.1.12",
+    "@adahiya/raga-web-app": "workspace:^",
     "@tinyhttp/app": "^2.5.2",
     "ansis": "^3.17.0",
     "app-root-dir": "^1.0.2",
-    "chroma-js": "^3.1.2",
-    "classnames": "^2.5.1",
-    "clsx": "^2.1.1",
-    "date-fns": "^4.1.0",
-    "dayjs": "^1.11.13",
     "disconnect": "^1.2.2",
     "effection": "^3.4.0",
-    "immer": "^10.1.1",
-    "mantine-contextmenu": "^7.17.1",
     "milliparsec": "^5.0.2",
-    "motion": "^12.6.3",
     "node-taglib-sharp": "^6.0.1",
-    "pluralize": "^8.0.0",
     "radash": "^12.1.0",
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
-    "react-dropzone": "^14.3.8",
-    "react-icons": "^5.5.0",
-    "react-resizable-panels": "^2.1.7",
     "react-scan": "^0.3.4",
     "roarr": "^7.21.1",
     "serialize-error": "^12.0.0",
     "sirv": "^3.0.1",
-    "use-immer": "^0.11.0",
-    "usehooks-ts": "3.1.1",
-    "vite-plugin-html-config": "^2.0.2",
-    "wavesurfer.js": "^7.9.4",
-    "web-audio-beat-detector": "^8.2.27",
-    "zustand": "^5.0.3"
+    "vite-plugin-html-config": "^2.0.2"
   },
   "devDependencies": {
     "@electron-forge/cli": "^7.8.1",
     "@electron-forge/maker-deb": "^7.8.1",
     "@electron-forge/maker-zip": "^7.8.1",
     "@electron-forge/plugin-vite": "^7.8.1",
     "@types/app-root-dir": "^0.1.4",
-    "@types/chroma-js": "^3.1.1",
     "@types/node": "^22.15.24",
-    "@types/pluralize": "^0.0.33",
     "@types/react": "^19.1.6",
     "@types/react-devtools": "^3.6.2",
     "@types/react-dom": "^19.1.5",

packages/raga-app/src/client/globalWindow.ts

@@ -28,7 +28,7 @@
 
 /* eslint-disable simple-import-sort/imports */
 
-import "./client/index.scss";
+import "../../raga-web-app/src/index.scss";
 
 import { scan } from "react-scan"; // import this BEFORE react
 import "react";
@@ -40,6 +40,6 @@ if (typeof window !== "undefined" && process.env.NODE_ENV === "development") {
   });
 }
 
-import "./client/main";
+import "../../raga-web-app/src/main";
 
 /* eslint-enable simple-import-sort/imports */

packages/raga-app/src/client/main.tsx

@@ -14,9 +14,19 @@ export default defineConfig({
     }),
     react(),
   ],
-  publicDir: "./src/client/assets",
+  // Use the web app's assets directory
+  publicDir: "../raga-web-app/src/assets",
   build: {
     target: "esnext",
+    rollupOptions: {
+      external: ["react-scan"],
+    },
+  },
+  resolve: {
+    alias: {
+      // Ensure proper resolution of the web app package
+      "@adahiya/raga-web-app": "../raga-web-app",
+    },
   },
   cssPreprocessOptions: {
     sass: {

packages/raga-app/src/renderer.js

@@ -0,0 +1,29 @@
+# Dependencies
+node_modules/
+
+# Build outputs
+dist/
+.vite/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Environment
+.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local

packages/raga-app/vite.renderer.config.mjs

@@ -0,0 +1,58 @@
+# Raga Web App
+
+This package contains the portable web UI for Raga music library management. It can be run as a standalone web application or embedded within the Electron app.
+
+## Development
+
+To run the web app in development mode:
+
+```bash
+yarn dev
+```
+
+This will start a Vite dev server at http://localhost:3000
+
+## Building
+
+To build the web app for production:
+
+```bash
+yarn build
+```
+
+The built files will be in the `dist` directory.
+
+## Preview
+
+To preview the production build:
+
+```bash
+yarn preview
+```
+
+## Architecture
+
+This web app is designed to work in two modes:
+
+1. **Standalone mode**: When running as a regular web app, it uses a mock API (`webApi.ts`) that provides the same interface as the Electron API but with limited functionality.
+
+2. **Electron mode**: When embedded in the Electron app, it uses the actual Electron API exposed through the context bridge.
+
+## Key Features
+
+- Built with React 19 and TypeScript
+- Uses Mantine UI components
+- Vite for fast development and optimized builds
+- Sass modules for styling
+- Zustand for state management
+
+## Limitations in Standalone Mode
+
+When running as a standalone web app (not in Electron), certain features are limited:
+
+- File system access is restricted to web standards
+- No direct audio file tag writing
+- No native OS integrations
+- IPC communications are mocked
+
+These limitations do not apply when the app is running within Electron.