Merge pull request #889 from CREDO23/electon-desktop

[Feat] Desktop app (Win, Mac, Linux)

.vscode/settings.json

@@ -1,3 +1,4 @@
 {
-	"biome.configurationPath": "./surfsense_web/biome.json"
+	"biome.configurationPath": "./surfsense_web/biome.json",
+	"deepscan.ignoreConfirmWarning": true
 }

surfsense_backend/app/app.py

@@ -340,20 +340,17 @@ if config.NEXT_FRONTEND_URL:
         if www_url not in allowed_origins:
             allowed_origins.append(www_url)
 
-# For local development, also allow common localhost origins
+allowed_origins.extend(
-if not config.BACKEND_URL or (
+    [ # For local development and desktop app
-    config.NEXT_FRONTEND_URL and "localhost" in config.NEXT_FRONTEND_URL
-):
-    allowed_origins.extend(
-        [
         "http://localhost:3000",
         "http://127.0.0.1:3000",
     ]
-    )
+)
 
 app.add_middleware(
     CORSMiddleware,
     allow_origins=allowed_origins,
+    allow_origin_regex=r"^https?://(localhost|127\.0\.0\.1)(:\d+)?$",
     allow_credentials=True,
     allow_methods=["*"],  # Allows all methods
     allow_headers=["*"],  # Allows all headers

surfsense_desktop/.env

@@ -0,0 +1,6 @@
+# Electron-specific build-time configuration.
+# Set before running pnpm dist:mac / dist:win / dist:linux.
+
+# The hosted web frontend URL. Used to intercept OAuth redirects and keep them
+# inside the desktop app. Set to your production frontend domain.
+HOSTED_FRONTEND_URL=https://surfsense.net

surfsense_desktop/.gitignore

@@ -0,0 +1,3 @@
+node_modules/
+dist/
+release/

surfsense_desktop/README.md

@@ -0,0 +1,58 @@
+# SurfSense Desktop
+
+Electron wrapper around the SurfSense web app. Packages the Next.js standalone build into a native desktop application with OAuth support, deep linking, and system browser integration.
+
+## Prerequisites
+
+- Node.js 18+
+- pnpm 10+
+- The `surfsense_web` project dependencies installed (`pnpm install` in `surfsense_web/`)
+
+## Development
+
+```bash
+pnpm install
+pnpm dev
+```
+
+This starts the Next.js dev server and Electron concurrently. Hot reload works — edit the web app and changes appear immediately.
+
+## Configuration
+
+Two `.env` files control the build:
+
+**`surfsense_web/.env`** — Next.js environment variables baked into the frontend at build time:
+
+**`surfsense_desktop/.env`** — Electron-specific configuration:
+
+Set these before building.
+
+## Build & Package
+
+**Step 1** — Build the Next.js standalone output:
+
+```bash
+cd ../surfsense_web
+pnpm build
+```
+
+**Step 2** — Compile Electron and prepare the standalone output:
+
+```bash
+cd ../surfsense_desktop
+pnpm build
+```
+
+**Step 3** — Package into a distributable:
+
+```bash
+pnpm dist:mac      # macOS (.dmg + .zip)
+pnpm dist:win      # Windows (.exe)
+pnpm dist:linux    # Linux (.deb + .AppImage)
+```
+
+**Step 4** — Find the output:
+
+```bash
+ls release/
+```

surfsense_desktop/electron-builder.yml

@@ -0,0 +1,67 @@
+appId: com.surfsense.desktop
+productName: SurfSense
+publish:
+  provider: github
+  owner: MODSetter
+  repo: SurfSense
+directories:
+  output: release
+files:
+  - dist/**/*
+  - "!node_modules"
+  - "!src"
+  - "!scripts"
+  - "!release"
+extraResources:
+  - from: ../surfsense_web/.next/standalone/surfsense_web/
+    to: standalone/
+    filter:
+      - "**/*"
+      - "!**/node_modules"
+  - from: ../surfsense_web/.next/standalone/surfsense_web/node_modules/
+    to: standalone/node_modules/
+    filter: ["**/*"]
+  - from: ../surfsense_web/.next/static/
+    to: standalone/.next/static/
+    filter: ["**/*"]
+  - from: ../surfsense_web/public/
+    to: standalone/public/
+    filter: ["**/*"]
+asarUnpack:
+  - "**/*.node"
+mac:
+  icon: assets/icon.icns
+  category: public.app-category.productivity
+  artifactName: "${productName}-${version}-${arch}.${ext}"
+  hardenedRuntime: true
+  gatekeeperAssess: false
+  target:
+    - target: dmg
+      arch: [x64, arm64]
+    - target: zip
+      arch: [x64, arm64]
+win:
+  icon: assets/icon.ico
+  target:
+    - target: nsis
+      arch: [x64, arm64]
+nsis:
+  oneClick: false
+  perMachine: false
+  allowToChangeInstallationDirectory: true
+  createDesktopShortcut: true
+  createStartMenuShortcut: true
+linux:
+  icon: assets/icon.png
+  category: Utility
+  artifactName: "${productName}-${version}-${arch}.${ext}"
+  mimeTypes:
+    - x-scheme-handler/surfsense
+  desktop:
+    entry:
+      Name: SurfSense
+      Comment: AI-powered research assistant
+      Categories: Utility;Office;
+  target:
+    - deb
+    - AppImage

surfsense_desktop/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "surfsense-desktop",
+  "version": "0.1.0",
+  "description": "SurfSense Desktop App",
+  "main": "dist/main.js",
+  "scripts": {
+    "dev": "concurrently -k \"pnpm --dir ../surfsense_web dev\" \"wait-on http://localhost:3000 && electron .\"",
+    "build": "node scripts/build-electron.mjs",
+    "pack:dir": "pnpm build && electron-builder --dir --config electron-builder.yml",
+    "dist": "pnpm build && electron-builder --config electron-builder.yml",
+    "dist:mac": "pnpm build && electron-builder --mac --config electron-builder.yml",
+    "dist:win": "pnpm build && electron-builder --win --config electron-builder.yml",
+    "dist:linux": "pnpm build && electron-builder --linux --config electron-builder.yml",
+    "typecheck": "tsc --noEmit"
+  },
+  "author": "MODSetter",
+  "license": "MIT",
+  "packageManager": "pnpm@10.24.0",
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "concurrently": "^9.2.1",
+    "dotenv": "^17.3.1",
+    "electron": "^41.0.2",
+    "electron-builder": "^26.8.1",
+    "esbuild": "^0.27.4",
+    "typescript": "^5.9.3",
+    "wait-on": "^9.0.4"
+  },
+  "dependencies": {
+    "electron-updater": "^6.8.3",
+    "get-port-please": "^3.2.0"
+  }
+}

surfsense_desktop/pnpm-workspace.yaml

@@ -0,0 +1,4 @@
+onlyBuiltDependencies:
+  - electron
+  - electron-winstaller
+  - esbuild

surfsense_desktop/scripts/build-electron.mjs

@@ -0,0 +1,136 @@
+import { build } from 'esbuild';
+import fs from 'fs';
+import path from 'path';
+import dotenv from 'dotenv';
+
+const desktopEnv = dotenv.config().parsed || {};
+
+const STANDALONE_ROOT = path.join(
+  '..', 'surfsense_web', '.next', 'standalone', 'surfsense_web'
+);
+
+/**
+ * electron-builder cannot follow symlinks when packaging into ASAR.
+ * Recursively walk the standalone output and replace every symlink
+ * with a real copy (or remove it if the target doesn't exist).
+ */
+function resolveAllSymlinks(dir) {
+  if (!fs.existsSync(dir)) return;
+
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isSymbolicLink()) {
+      const target = fs.readlinkSync(full);
+      const resolved = path.resolve(dir, target);
+      if (fs.existsSync(resolved)) {
+        fs.rmSync(full, { recursive: true, force: true });
+        fs.cpSync(resolved, full, { recursive: true });
+        console.log(`Resolved symlink: ${full}`);
+      } else {
+        fs.rmSync(full, { force: true });
+        console.log(`Removed broken symlink: ${full}`);
+      }
+    } else if (entry.isDirectory()) {
+      resolveAllSymlinks(full);
+    }
+  }
+}
+
+/**
+ * pnpm's .pnpm/ virtual store uses symlinks for sibling dependency resolution.
+ * After resolveAllSymlinks converts everything to real copies, packages can no
+ * longer find their dependencies through the pnpm structure.  We flatten the
+ * tree into a standard npm-like layout: every package from .pnpm/*/node_modules/
+ * gets hoisted to the top-level node_modules/.  This lets Node.js standard
+ * module resolution find all dependencies (e.g. next → styled-jsx).
+ */
+function flattenPnpmStore(nodeModulesDir) {
+  const pnpmDir = path.join(nodeModulesDir, '.pnpm');
+  if (!fs.existsSync(pnpmDir)) return;
+
+  console.log('Flattening pnpm store to top-level node_modules...');
+  let hoisted = 0;
+
+  for (const storePkg of fs.readdirSync(pnpmDir, { withFileTypes: true })) {
+    if (!storePkg.isDirectory() || storePkg.name === 'node_modules') continue;
+
+    const innerNM = path.join(pnpmDir, storePkg.name, 'node_modules');
+    if (!fs.existsSync(innerNM)) continue;
+
+    for (const dep of fs.readdirSync(innerNM, { withFileTypes: true })) {
+      const depName = dep.name;
+      // Handle scoped packages (@org/pkg)
+      if (depName.startsWith('@') && dep.isDirectory()) {
+        const scopeDir = path.join(innerNM, depName);
+        for (const scopedPkg of fs.readdirSync(scopeDir, { withFileTypes: true })) {
+          const fullName = `${depName}/${scopedPkg.name}`;
+          const src = path.join(scopeDir, scopedPkg.name);
+          const dest = path.join(nodeModulesDir, depName, scopedPkg.name);
+          if (!fs.existsSync(dest)) {
+            fs.mkdirSync(path.join(nodeModulesDir, depName), { recursive: true });
+            fs.cpSync(src, dest, { recursive: true });
+            hoisted++;
+          }
+        }
+      } else if (dep.isDirectory() || dep.isFile()) {
+        const dest = path.join(nodeModulesDir, depName);
+        if (!fs.existsSync(dest)) {
+          fs.cpSync(path.join(innerNM, depName), dest, { recursive: true });
+          hoisted++;
+        }
+      }
+    }
+  }
+
+  // Remove the .pnpm directory — no longer needed
+  fs.rmSync(pnpmDir, { recursive: true, force: true });
+  console.log(`Hoisted ${hoisted} packages, removed .pnpm/`);
+}
+
+function resolveStandaloneSymlinks() {
+  console.log('Resolving symlinks in standalone output...');
+  resolveAllSymlinks(STANDALONE_ROOT);
+  flattenPnpmStore(path.join(STANDALONE_ROOT, 'node_modules'));
+}
+
+async function buildElectron() {
+  if (fs.existsSync('dist')) {
+    fs.rmSync('dist', { recursive: true });
+    console.log('Cleaned dist/');
+  }
+  fs.mkdirSync('dist', { recursive: true });
+
+  const shared = {
+    bundle: true,
+    platform: 'node',
+    target: 'node18',
+    external: ['electron'],
+    sourcemap: true,
+    minify: false,
+    define: {
+      'process.env.HOSTED_FRONTEND_URL': JSON.stringify(
+        desktopEnv.HOSTED_FRONTEND_URL || 'https://surfsense.net'
+      ),
+    },
+  };
+
+  await build({
+    ...shared,
+    entryPoints: ['src/main.ts'],
+    outfile: 'dist/main.js',
+  });
+
+  await build({
+    ...shared,
+    entryPoints: ['src/preload.ts'],
+    outfile: 'dist/preload.js',
+  });
+
+  console.log('Electron build complete');
+  resolveStandaloneSymlinks();
+}
+
+buildElectron().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

surfsense_desktop/src/main.ts

@@ -0,0 +1,258 @@
+import { app, BrowserWindow, shell, ipcMain, session, dialog, clipboard, Menu } from 'electron';
+import path from 'path';
+import { getPort } from 'get-port-please';
+
+function showErrorDialog(title: string, error: unknown): void {
+  const err = error instanceof Error ? error : new Error(String(error));
+  console.error(`${title}:`, err);
+
+  if (app.isReady()) {
+    const detail = err.stack || err.message;
+    const buttonIndex = dialog.showMessageBoxSync({
+      type: 'error',
+      buttons: ['OK', process.platform === 'darwin' ? 'Copy Error' : 'Copy error'],
+      defaultId: 0,
+      noLink: true,
+      message: title,
+      detail,
+    });
+    if (buttonIndex === 1) {
+      clipboard.writeText(`${title}\n${detail}`);
+    }
+  } else {
+    dialog.showErrorBox(title, err.stack || err.message);
+  }
+}
+
+process.on('uncaughtException', (error) => {
+  showErrorDialog('Unhandled Error', error);
+});
+
+process.on('unhandledRejection', (reason) => {
+  showErrorDialog('Unhandled Promise Rejection', reason);
+});
+
+const isDev = !app.isPackaged;
+let mainWindow: BrowserWindow | null = null;
+let deepLinkUrl: string | null = null;
+let serverPort: number = 3000; // overwritten at startup with a free port
+
+const PROTOCOL = 'surfsense';
+// Injected at compile time from .env via esbuild define
+const HOSTED_FRONTEND_URL = process.env.HOSTED_FRONTEND_URL as string;
+
+function getStandalonePath(): string {
+  if (isDev) {
+    return path.join(__dirname, '..', '..', 'surfsense_web', '.next', 'standalone', 'surfsense_web');
+  }
+  return path.join(process.resourcesPath, 'standalone');
+}
+
+async function waitForServer(url: string, maxRetries = 60): Promise<boolean> {
+  for (let i = 0; i < maxRetries; i++) {
+    try {
+      const res = await fetch(url);
+      if (res.ok || res.status === 404 || res.status === 500) return true;
+    } catch {
+      // not ready yet
+    }
+    await new Promise((r) => setTimeout(r, 500));
+  }
+  return false;
+}
+
+async function startNextServer(): Promise<void> {
+  if (isDev) return;
+
+  serverPort = await getPort({ port: 3000, portRange: [30_011, 50_000] });
+  console.log(`Selected port ${serverPort}`);
+
+  const standalonePath = getStandalonePath();
+  const serverScript = path.join(standalonePath, 'server.js');
+
+  // The standalone server.js reads PORT / HOSTNAME from process.env and
+  // uses process.chdir(__dirname). Running it via require() in the same
+  // process is the proven approach (avoids spawning a second Electron
+  // instance whose ASAR-patched fs breaks Next.js static file serving).
+  process.env.PORT = String(serverPort);
+  process.env.HOSTNAME = 'localhost';
+  process.env.NODE_ENV = 'production';
+  process.chdir(standalonePath);
+
+  require(serverScript);
+
+  const ready = await waitForServer(`http://localhost:${serverPort}`);
+  if (!ready) {
+    throw new Error('Next.js server failed to start within 30 s');
+  }
+  console.log(`Next.js server ready on port ${serverPort}`);
+}
+
+function createWindow() {
+  mainWindow = new BrowserWindow({
+    width: 1280,
+    height: 800,
+    minWidth: 800,
+    minHeight: 600,
+    webPreferences: {
+      preload: path.join(__dirname, 'preload.js'),
+      contextIsolation: true,
+      nodeIntegration: false,
+      sandbox: true,
+      webviewTag: false,
+    },
+    show: false,
+    titleBarStyle: 'hiddenInset',
+  });
+
+  mainWindow.once('ready-to-show', () => {
+    mainWindow?.show();
+  });
+
+  mainWindow.loadURL(`http://localhost:${serverPort}/login`);
+
+  // External links open in system browser, not in the Electron window
+  mainWindow.webContents.setWindowOpenHandler(({ url }) => {
+    if (url.startsWith('http://localhost')) {
+      return { action: 'allow' };
+    }
+    shell.openExternal(url);
+    return { action: 'deny' };
+  });
+
+  // Intercept backend OAuth redirects targeting the hosted web frontend
+  // and rewrite them to localhost so the user stays in the desktop app.
+  const filter = { urls: [`${HOSTED_FRONTEND_URL}/*`] };
+  session.defaultSession.webRequest.onBeforeRequest(filter, (details, callback) => {
+    const rewritten = details.url.replace(HOSTED_FRONTEND_URL, `http://localhost:${serverPort}`);
+    callback({ redirectURL: rewritten });
+  });
+
+  mainWindow.webContents.on('did-fail-load', (_event, errorCode, errorDescription, validatedURL) => {
+    console.error(`Failed to load ${validatedURL}: ${errorDescription} (${errorCode})`);
+    if (errorCode === -3) return; // ERR_ABORTED — normal during redirects
+    showErrorDialog('Page failed to load', new Error(`${errorDescription} (${errorCode})\n${validatedURL}`));
+  });
+
+  if (isDev) {
+    mainWindow.webContents.openDevTools();
+  }
+
+  mainWindow.on('closed', () => {
+    mainWindow = null;
+  });
+}
+
+// IPC handlers
+ipcMain.on('open-external', (_event, url: string) => {
+  try {
+    const parsed = new URL(url);
+    if (parsed.protocol === 'http:' || parsed.protocol === 'https:') {
+      shell.openExternal(url);
+    }
+  } catch {
+    // invalid URL — ignore
+  }
+});
+
+ipcMain.handle('get-app-version', () => {
+  return app.getVersion();
+});
+
+// Deep link handling
+function handleDeepLink(url: string) {
+  if (!url.startsWith(`${PROTOCOL}://`)) return;
+
+  deepLinkUrl = url;
+
+  if (!mainWindow) return;
+
+  // Rewrite surfsense:// deep link to localhost so TokenHandler.tsx processes it
+  const parsed = new URL(url);
+  if (parsed.hostname === 'auth' && parsed.pathname === '/callback') {
+    const params = parsed.searchParams.toString();
+    mainWindow.loadURL(`http://localhost:${serverPort}/auth/callback?${params}`);
+  }
+
+  mainWindow.show();
+  mainWindow.focus();
+}
+
+// Single instance lock — second instance passes deep link to first
+const gotTheLock = app.requestSingleInstanceLock();
+if (!gotTheLock) {
+  app.quit();
+} else {
+  app.on('second-instance', (_event, argv) => {
+    // Windows/Linux: deep link URL is in argv
+    const url = argv.find((arg) => arg.startsWith(`${PROTOCOL}://`));
+    if (url) handleDeepLink(url);
+
+    if (mainWindow) {
+      if (mainWindow.isMinimized()) mainWindow.restore();
+      mainWindow.focus();
+    }
+  });
+}
+
+// macOS: deep link arrives via open-url event
+app.on('open-url', (event, url) => {
+  event.preventDefault();
+  handleDeepLink(url);
+});
+
+// Register surfsense:// protocol
+if (process.defaultApp) {
+  if (process.argv.length >= 2) {
+    app.setAsDefaultProtocolClient(PROTOCOL, process.execPath, [path.resolve(process.argv[1])]);
+  }
+} else {
+  app.setAsDefaultProtocolClient(PROTOCOL);
+}
+
+function setupMenu() {
+  const isMac = process.platform === 'darwin';
+  const template: Electron.MenuItemConstructorOptions[] = [
+    ...(isMac ? [{ role: 'appMenu' as const }] : []),
+    { role: 'fileMenu' as const },
+    { role: 'editMenu' as const },
+    { role: 'viewMenu' as const },
+    { role: 'windowMenu' as const },
+  ];
+  Menu.setApplicationMenu(Menu.buildFromTemplate(template));
+}
+
+// App lifecycle
+app.whenReady().then(async () => {
+  setupMenu();
+  try {
+    await startNextServer();
+  } catch (error) {
+    showErrorDialog('Failed to start SurfSense', error);
+    setTimeout(() => app.quit(), 0);
+    return;
+  }
+  createWindow();
+
+  // If a deep link was received before the window was ready, handle it now
+  if (deepLinkUrl) {
+    handleDeepLink(deepLinkUrl);
+    deepLinkUrl = null;
+  }
+
+  app.on('activate', () => {
+    if (BrowserWindow.getAllWindows().length === 0) {
+      createWindow();
+    }
+  });
+});
+
+app.on('window-all-closed', () => {
+  if (process.platform !== 'darwin') {
+    app.quit();
+  }
+});
+
+app.on('will-quit', () => {
+  // Server runs in-process — no child process to kill
+});

surfsense_desktop/src/preload.ts

@@ -0,0 +1,19 @@
+const { contextBridge, ipcRenderer } = require('electron');
+
+contextBridge.exposeInMainWorld('electronAPI', {
+  versions: {
+    electron: process.versions.electron,
+    node: process.versions.node,
+    chrome: process.versions.chrome,
+    platform: process.platform,
+  },
+  openExternal: (url: string) => ipcRenderer.send('open-external', url),
+  getAppVersion: () => ipcRenderer.invoke('get-app-version'),
+  onDeepLink: (callback: (url: string) => void) => {
+    const listener = (_event: unknown, url: string) => callback(url);
+    ipcRenderer.on('deep-link', listener);
+    return () => {
+      ipcRenderer.removeListener('deep-link', listener);
+    };
+  },
+});

surfsense_desktop/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "commonjs",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "noEmit": true
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "dist", "scripts"]
+}

surfsense_web/Dockerfile

@@ -71,7 +71,7 @@ COPY --from=builder /app/public ./public
 
 # Automatically leverage output traces to reduce image size
 # https://nextjs.org/docs/advanced-features/output-file-tracing
-COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
+COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone/app/ ./
 COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
 
 # Entrypoint scripts for runtime env var substitution

surfsense_web/next.config.ts

@@ -1,3 +1,4 @@
+import path from "path";
 import { createMDX } from "fumadocs-mdx/next";
 import type { NextConfig } from "next";
 import createNextIntlPlugin from "next-intl/plugin";
@@ -5,8 +6,12 @@ import createNextIntlPlugin from "next-intl/plugin";
 // Create the next-intl plugin
 const withNextIntl = createNextIntlPlugin("./i18n/request.ts");
 
+// TODO: Separate app routes (/login, /dashboard) from marketing routes
+// (landing page, /contact, /pricing, /docs) so the desktop build only
+// ships what desktop users actually need.
 const nextConfig: NextConfig = {
 	output: "standalone",
+	outputFileTracingRoot: path.join(__dirname, ".."),
 	reactStrictMode: false,
 	typescript: {
 		ignoreBuildErrors: true,