feat(desktop): add Windows build and runtime support

apps/desktop/electron-builder.ts

@@ -135,8 +135,10 @@ const config: Configuration = {
 		"!**/.DS_Store",
 	],
 
-	// Rebuild native modules for Electron's Node.js version
-	npmRebuild: true,
+	// Rebuild native modules for Electron's Node.js version.
+	// Disabled on Windows — native modules are already handled by install:deps
+	// and copy:native-modules, and node-gyp may fail without Visual Studio.
+	npmRebuild: process.platform !== "win32",
 
 	// macOS
 	mac: {
@@ -204,6 +206,9 @@ const config: Configuration = {
 	nsis: {
 		oneClick: false,
 		allowToChangeInstallationDirectory: true,
+		createDesktopShortcut: true,
+		createStartMenuShortcut: true,
+		shortcutName: productName,
 	},
 };
 

apps/desktop/electron.vite.config.ts

@@ -15,6 +15,7 @@ import {
 	defineEnv,
 	devPath,
 	htmlEnvTransformPlugin,
+	stripCrossOriginPlugin,
 } from "./vite/helpers";
 
 // override: true ensures .env values take precedence over inherited env vars
@@ -104,6 +105,11 @@ export default defineConfig({
 				},
 				output: {
 					dir: resolve(devPath, "main"),
+					// VS Code and other Electron hosts set ELECTRON_RUN_AS_NODE=1 which
+					// prevents Electron from entering browser mode. Clear it before any
+					// require("electron") call — must be the very first statement.
+					banner:
+						'delete process.env.ELECTRON_RUN_AS_NODE;',
 				},
 				external: [
 					"electron",
@@ -235,6 +241,7 @@ export default defineConfig({
 			}),
 			reactPlugin(),
 			htmlEnvTransformPlugin(),
+			stripCrossOriginPlugin(),
 		],
 
 		worker: {

apps/desktop/scripts/copy-native-modules.ts

@@ -99,8 +99,13 @@ function copyModuleIfSymlink(
 		console.log(`  ${moduleName}: symlink -> replacing with real files`);
 		console.log(`    Real path: ${realPath}`);
 
-		// Remove the symlink
-		rmSync(modulePath);
+		// Windows uses junctions (directory-like) instead of symlinks;
+		// rmSync needs { recursive: true } to remove them.
+		if (process.platform === "win32") {
+			rmSync(modulePath, { recursive: true, force: true });
+		} else {
+			rmSync(modulePath);
+		}
 
 		// Copy the actual files
 		cpSync(realPath, modulePath, { recursive: true });

apps/desktop/src/lib/electron-app/factories/app/setup.ts

@@ -56,7 +56,9 @@ export async function makeAppSetup(
 	return window;
 }
 
-PLATFORM.IS_LINUX && app.disableHardwareAcceleration();
+// Disable GPU hardware acceleration on Linux and Windows to prevent black/blank
+// screens caused by GPU driver incompatibilities with Chromium's compositor.
+(PLATFORM.IS_LINUX || PLATFORM.IS_WINDOWS) && app.disableHardwareAcceleration();
 
 // macOS Sequoia+: occluded window throttling can corrupt GPU compositor layers
 if (PLATFORM.IS_MAC) {

apps/desktop/src/lib/window-loader.ts

@@ -24,8 +24,14 @@ export function registerRoute(props: {
 		const url = `http://localhost:${env.DESKTOP_VITE_PORT}/#/`;
 		console.log("[window-loader] Loading development URL:", url);
 		props.browserWindow.loadURL(url);
+	} else if (process.platform === "win32") {
+		// Production (Windows): use custom protocol for proper dynamic import support.
+		// file:// protocol breaks ES module dynamic imports (code-split chunks) on Windows.
+		const url = "superset-app://app/index.html#/";
+		console.log("[window-loader] Loading custom protocol URL:", url);
+		props.browserWindow.loadURL(url);
 	} else {
-		// Production: load from file with hash routing
+		// Production (macOS/Linux): load from file with hash routing
 		// TanStack Router uses hash-based routing, so we always start at #/
 		console.log("[window-loader] Loading file:", props.htmlFile);
 		props.browserWindow.loadFile(props.htmlFile, { hash: "/" });

apps/desktop/src/main/index.ts

@@ -247,6 +247,15 @@ protocol.registerSchemesAsPrivileged([
 			supportFetchAPI: true,
 		},
 	},
+	{
+		scheme: "superset-app",
+		privileges: {
+			standard: true,
+			secure: true,
+			supportFetchAPI: true,
+			corsEnabled: true,
+		},
+	},
 ]);
 
 const gotTheLock = app.requestSingleInstanceLock();
@@ -283,6 +292,48 @@ if (!gotTheLock) {
 			.fromPartition("persist:superset")
 			.protocol.handle("superset-icon", iconProtocolHandler);
 
+		// Register custom protocol for serving renderer files.
+		// Dynamic imports (code-split chunks) fail on file:// protocol in Electron on Windows.
+		// The superset-app:// protocol serves files from the renderer dist directory with
+		// proper CORS and module support, enabling lazy-loaded route components.
+		const rendererDir = path.join(__dirname, "../renderer");
+		const appProtocolHandler = (request: Request) => {
+			let urlPath = new URL(request.url).pathname;
+			// Remove leading slash on Windows
+			if (urlPath.startsWith("/")) urlPath = urlPath.slice(1);
+			const filePath = path.join(rendererDir, urlPath);
+			return net.fetch(pathToFileURL(filePath).toString());
+		};
+		protocol.handle("superset-app", appProtocolHandler);
+		session
+			.fromPartition("persist:superset")
+			.protocol.handle("superset-app", appProtocolHandler);
+
+		// On Windows, the custom superset-app:// protocol origin is not recognized by
+		// the API server's CORS policy. Bypass CORS for API requests by modifying headers.
+		if (PLATFORM.IS_WINDOWS) {
+			const appSession = session.fromPartition("persist:superset");
+			appSession.webRequest.onBeforeSendHeaders(
+				{ urls: ["https://api.superset.sh/*", "https://*.posthog.com/*", "https://*.sentry.io/*", "https://app.outlit.ai/*"] },
+				(details, callback) => {
+					// Replace custom protocol origin with the expected web origin
+					if (details.requestHeaders.Origin === "superset-app://app") {
+						delete details.requestHeaders.Origin;
+					}
+					callback({ requestHeaders: details.requestHeaders });
+				},
+			);
+			appSession.webRequest.onHeadersReceived(
+				{ urls: ["https://api.superset.sh/*"] },
+				(details, callback) => {
+					const headers = details.responseHeaders ?? {};
+					headers["access-control-allow-origin"] = ["superset-app://app"];
+					headers["access-control-allow-credentials"] = ["true"];
+					callback({ responseHeaders: headers });
+				},
+			);
+		}
+
 		ensureProjectIconsDir();
 		setWorkspaceDockIcon();
 		initSentry();

apps/desktop/src/main/windows/main.ts

@@ -220,6 +220,22 @@ export async function MainWindow() {
 		});
 	}
 
+	// Forward renderer warning/error messages to main process stdout for Windows debugging.
+	if (PLATFORM.IS_WINDOWS) {
+		window.webContents.on(
+			"console-message",
+			(_event, level, message, line, sourceId) => {
+				if (level < 2) return;
+				const levelStr =
+					["verbose", "info", "warning", "error"][level] ?? "unknown";
+				const source = sourceId ? ` (${sourceId}:${line})` : "";
+				const formatted = `[renderer:${levelStr}] ${message}${source}`;
+				if (level === 3) console.error(formatted);
+				else console.warn(formatted);
+			},
+		);
+	}
+
 	// Persist window bounds on move/resize so state survives app.exit(0)
 	// (which skips the close handler — e.g. electron-vite SIGTERM during dev).
 	// Gated by `initialized` so the initial maximize() doesn't immediately

apps/desktop/src/renderer/routes/_authenticated/providers/CollectionsProvider/CollectionsProvider.tsx

@@ -64,12 +64,12 @@ export function CollectionsProvider({ children }: { children: ReactNode }) {
 		preloadActiveOrganizationCollections(activeOrganizationId);
 	}, [activeOrganizationId]);
 
-	if (useElectricCloud === undefined) {
-		return null;
-	}
+	// When PostHog is not configured (no key), feature flags stay undefined forever.
+	// Default to false (use proxy) so the app doesn't block rendering.
+	const isElectricCloud = useElectricCloud ?? false;
 
 	setElectricUrl(
-		useElectricCloud
+		isElectricCloud
 			? env.NEXT_PUBLIC_ELECTRIC_URL
 			: env.NEXT_PUBLIC_ELECTRIC_PROXY_URL,
 	);

apps/desktop/vite/helpers.ts

@@ -20,7 +20,7 @@ export function defineEnv(
 	value: string | undefined,
 	fallback?: string,
 ): string {
-	return JSON.stringify(value ?? fallback);
+	return JSON.stringify(value || fallback);
 }
 
 const RESOURCES_TO_COPY = [
@@ -62,6 +62,24 @@ export function copyResourcesPlugin(): Plugin {
 	};
 }
 
+/**
+ * Strips the `crossorigin` attribute that Vite adds to script/link tags.
+ * Electron's ASAR file:// handler doesn't support CORS on Windows,
+ * so crossorigin causes scripts/styles to silently fail to load (black screen).
+ */
+export function stripCrossOriginPlugin(): Plugin {
+	return {
+		name: "strip-crossorigin",
+		transformIndexHtml: {
+			order: "post",
+			handler(html) {
+				if (process.platform !== "win32") return html;
+				return html.replace(/ crossorigin(?:="[^"]*")?/g, "");
+			},
+		},
+	};
+}
+
 /**
  * Injects environment variables into index.html CSP.
  */

package.json

@@ -29,7 +29,7 @@
 		"format:check": "biome format .",
 		"typecheck": "turbo typecheck",
 		"ui-add": "turbo run ui-add",
-		"postinstall": "./scripts/postinstall.sh",
+		"postinstall": "node scripts/postinstall.mjs",
 		"clean": "git clean -xdf node_modules",
 		"clean:workspaces": "turbo clean",
 		"release:desktop": "./apps/desktop/create-release.sh",

scripts/postinstall.mjs

@@ -0,0 +1,48 @@
+/**
+ * Cross-platform postinstall script.
+ *
+ * Replaces the bash-only postinstall.sh so that `bun install` works on
+ * Windows, macOS and Linux without special flags.
+ *
+ * Steps:
+ *  1. Guard against infinite recursion (electron-builder install-app-deps
+ *     can trigger nested bun installs which would re-run this script).
+ *  2. Run sherif for workspace validation.
+ *  3. Install native dependencies for the desktop app.
+ */
+
+import { execSync } from "node:child_process";
+
+// Prevent infinite recursion during postinstall
+if (process.env.SUPERSET_POSTINSTALL_RUNNING) {
+	process.exit(0);
+}
+process.env.SUPERSET_POSTINSTALL_RUNNING = "1";
+
+const env = { ...process.env, SUPERSET_POSTINSTALL_RUNNING: "1" };
+
+/** Run a command, inheriting stdio so output is visible. */
+function run(cmd) {
+	execSync(cmd, { stdio: "inherit", env });
+}
+
+/** Run a command but don't fail if it errors (for optional native deps on Windows). */
+function tryRun(cmd, label) {
+	try {
+		execSync(cmd, { stdio: "inherit", env });
+	} catch {
+		console.warn(`[postinstall] ${label} failed (non-fatal on Windows) — continuing`);
+	}
+}
+
+// Run sherif for workspace validation
+run("sherif");
+
+// Install native dependencies for desktop app.
+// On Windows, native module compilation may fail if Visual Studio Build Tools
+// are not installed. This is non-fatal — prebuilt binaries will be used when available.
+if (process.platform === "win32") {
+	tryRun("bun run --filter=@superset/desktop install:deps", "install:deps");
+} else {
+	run("bun run --filter=@superset/desktop install:deps");
+}