@witchcraft/nuxt-electron 0.0.1

package/src/runtime/components/WindowControls/MaximizeButton.vue

@@ -0,0 +1,35 @@
+<template>
+<WButton
+	:border="false"
+	aria-label="Toggle Maximize"
+	class="
+			p-0
+			[&:hover_.default-icon]:border-accent-500
+			[&:hover_.default-icon]:shadow-xs
+			[&:hover_.default-icon]:shadow-fg/50
+
+		"
+	@click="emit('action', 'toggleMaximize')"
+>
+	<slot>
+		<div
+			class="
+				default-icon
+				border-fg
+				dark:border-bg
+				hover:border-accent-500
+				border-[length:var(--electron-wc-border)]
+				rounded-(--electron-wc-rounded)
+				w-[var(--electron-wc-size)]
+				h-[var(--electron-wc-size)]
+			"
+		/>
+	</slot>
+</WButton>
+</template>
+
+<script lang="ts" setup>
+const emit = defineEmits<{
+	(e: "action", action: "toggleMaximize"): void
+}>()
+</script>

package/src/runtime/components/WindowControls/MinimizeButton.vue

@@ -0,0 +1,42 @@
+<template>
+<WButton
+	:border="false"
+	aria-label="Minimize"
+	class="
+			p-0
+			[&:hover_.default-icon:after]:bg-accent-500
+			[&:hover_.default-icon:after]:shadow-xs
+			[&:hover_.default-icon:after]:shadow-fg/50
+		"
+	@click="emit('action', 'minimize')"
+>
+	<slot>
+		<div
+			class="
+			default-icon
+			border-fg
+			dark:border-bg
+			w-[var(--electron-wc-size)]
+			h-[var(--electron-wc-size)]
+			relative
+			after:absolute
+			after:content-['']
+			after:bottom-0
+			after:left-0
+			after:w-[var(--electron-wc-size)]
+			after:h-[var(--electron-wc-border)]
+			after:rounded-(--electron-wc-rounded)
+			after:bg-fg
+			dark:after:bg-bg
+
+		"
+		/>
+	</slot>
+</WButton>
+</template>
+
+<script lang="ts" setup>
+const emit = defineEmits<{
+	(e: "action", action: "minimize"): void
+}>()
+</script>

package/src/runtime/components/WindowControls/PinButton.vue

@@ -0,0 +1,56 @@
+<template>
+<WButton
+	aria-label="Toggle Always On Top"
+	auto-title-from-aria
+	:border="false"
+	:class="twMerge(`
+			p-0
+			hover:text-accent-500
+		`,
+		alwaysOnTop && `
+				[&_.default-icon_svg]:drop-shadow-[0_1px_1px_rgba(0,0,0,0.5)]
+			`,
+		!alwaysOnTop && `
+				text-neutral-400
+				dark:text-neutral-600
+			`
+	)"
+
+	@click="emit('action', 'togglePin')"
+>
+	<slot v-bind="{ alwaysOnTop }">
+		<WIcon
+			:class="twMerge(
+				`
+				default-icon
+				w-[var(--electron-wc-size)]
+				h-[var(--electron-wc-size)]
+				flex items-center justify-center
+				scale-105
+			`
+			)
+			"
+		>
+			<i-octicon-pin-16/>
+		</WIcon>
+	</slot>
+</WButton>
+</template>
+
+<script lang="ts" setup>
+import { twMerge } from "#imports"
+
+const emit = defineEmits<{
+	(e: "action", action: "togglePin"): void
+}>()
+/**
+ * If there is a `window.electron.on` api that allows listening to events and main sends an `always-on-top-changed`, it will update the state of the pin.
+ */
+const alwaysOnTop = defineModel<boolean>({ default: false })
+
+if (import.meta.client && (window as any)?.electron?.on) {
+	(window as any).electron.on("always-on-top-changed", (val: boolean) => {
+		alwaysOnTop.value = val
+	})
+}
+</script>

package/src/runtime/electron/apiBuilder.ts

@@ -0,0 +1,27 @@
+import type { DeepPartial } from "@alanscodelog/utils"
+import defu from "defu"
+import type { IpcRenderer } from "electron"
+/**
+ * Helper for building an api object.
+ *
+ * @experimental
+ */
+export function apiBuilder<
+	TPreloadMeta extends Record<string, any>,
+	TRawApi extends Record<string, any> = Record<string, any>,
+	TBuilders extends
+	((meta: DeepPartial<TPreloadMeta>, ipcRenderer: IpcRenderer) => any)[] = ((meta: DeepPartial<TPreloadMeta>, ipcRenderer: IpcRenderer) => any)[],
+	TBuilderOutput extends ReturnType<TBuilders[number]> = ReturnType<TBuilders[number]>
+>(
+	ipcRenderer: IpcRenderer,
+	api: TRawApi,
+	meta: TPreloadMeta,
+	builders: TBuilders
+): TRawApi & TBuilderOutput {
+	const resolutions: object[] = []
+	resolutions.push(api)
+	for (const builder of builders) {
+		resolutions.push(builder(meta, ipcRenderer))
+	}
+	return (defu as any)(...resolutions.reverse()) as any
+}

package/src/runtime/electron/createBroadcastHandlers.ts

@@ -0,0 +1,36 @@
+import { ipcRenderer } from "electron"
+
+export function createBroadcastHandlers<TEvents extends Record<string, (...args: any) => any>>(
+	key: string
+): {
+	on: <T extends keyof TEvents>(event: T, listener: TEvents[T]) => void
+	off: <T extends keyof TEvents>(event: T, listener: TEvents[T]) => void
+} {
+	const listeners = new Map<keyof TEvents, (TEvents[keyof TEvents])[]>()
+	ipcRenderer.on(key, (_e, eventName, ...args: any[]) => {
+		const cbs = listeners.get(eventName)
+		if (cbs) {
+			for (const cb of cbs) {
+				cb(...args)
+			}
+		}
+	})
+	function on<T extends keyof TEvents>(event: T, listener: TEvents[T]): void {
+		const cbs = listeners.get(event)
+		if (cbs) {
+			cbs.push(listener)
+		} else {
+			listeners.set(event, [listener])
+		}
+	}
+
+	function off<T extends keyof TEvents>(event: T, listener: TEvents[T]): void {
+		const cbs = listeners.get(event)
+		if (cbs) {
+			cbs.splice(cbs.indexOf(listener), 1)
+		}
+	}
+	return {
+		on, off
+	}
+}

package/src/runtime/electron/createBroadcaster.ts

@@ -0,0 +1,11 @@
+import type { BrowserWindow } from "electron"
+
+export function createBroadcaster<
+	TEvents extends Record<string, (...args: any) => any>
+>(key: string, getWindows: () => BrowserWindow[]) {
+	return function broadcast<T extends keyof TEvents>(event: T, ...args: Parameters<TEvents[T]>) {
+		for (const win of getWindows()) {
+			win.webContents.send(key, event, ...args)
+		}
+	}
+}

package/src/runtime/electron/createNuxtFileProtocolHandler.ts

@@ -0,0 +1,42 @@
+import { keys } from "@alanscodelog/utils/keys"
+import { net } from "electron"
+import path from "node:path"
+
+export function createNuxtFileProtocolHandler(
+	session: Electron.Session,
+	basePath: string,
+	/**
+	 * If any route starts with one of these keys, it will get rerouted to the given value.
+	 *
+	 * At least `/api` should be added for a basic nuxt app to work correctly.
+	 *
+	 *
+	 * ```ts
+	 * routeProxies: {
+	 * 	"/api": "http://localhost:3000/api",
+	 * }
+	 * ```
+	 */
+	routeProxies: Record<string, string>
+): void {
+	const routeProxyKeys = keys(routeProxies)
+	session.protocol.handle("file", async request => {
+		const url = decodeURIComponent(request.url.slice(7))
+		const newUrl = path.isAbsolute(url)
+			? path.resolve(basePath, url.slice(1))
+			: path.resolve(basePath, url)
+
+		const proxyKey = routeProxyKeys.find(key => url.startsWith(key))
+
+		if (proxyKey) {
+			const proxyUrl = routeProxies[proxyKey]
+			return net.fetch(proxyUrl + url)
+		}
+
+		const res = await net.fetch(`file://${newUrl}`, {
+			// avoid infinite loop
+			bypassCustomProtocolHandlers: true
+		}).catch(err => new Response(err, { status: 404 }))
+		return res
+	})
+}

package/src/runtime/electron/createWindowControlsApi.ts

@@ -0,0 +1,27 @@
+import type { IpcRenderer } from "electron"
+
+import { promisifyApi } from "./promisifyApi.js"
+import type { WindowControlsApi } from "./types.js"
+
+const key = "window-control-action"
+/**
+ * Creates the apis to control the window from the preload script / client.
+ *
+ * ```ts
+ * // the default handler expects it to exist under `electron.api.ui.windowAction`
+ * // but you can configure it to use a different path
+ * constextBridge.exposeInMainWorld("electron", {
+ *		api: {
+ * 		ui: {
+ *				...createWindowControlsApi("windowAction")
+ * 		}
+ *		}
+ * })
+ * ```
+ */
+export function createWindowControlsApi(ipcRenderer: IpcRenderer, name: string): Record<string, WindowControlsApi> {
+	return promisifyApi<typeof name,
+		WindowControlsApi
+	>(ipcRenderer, name, key)
+}
+export const windowControlsMessageKey = key

package/src/runtime/electron/createWindowControlsApiHandler.ts

@@ -0,0 +1,34 @@
+import type { BrowserWindow } from "electron"
+
+import { windowControlsMessageKey } from "./createWindowControlsApi.js"
+import { promisifyReply } from "./promisifyReply.js"
+import type { WindowControlsApi } from "./types.js"
+
+export function createWindowControlsApiHandler(
+	/** Mostly for logging. Does not replace the action. */
+	cb?: (win: BrowserWindow | undefined, action: "close" | "minimize" | "toggleMaximize" | "togglePin")	=> void
+) {
+	promisifyReply<
+		WindowControlsApi
+	>(windowControlsMessageKey, async (win, action) => {
+		switch (action) {
+			case "close":
+				win?.close()
+				break
+			case "minimize":
+				win?.minimize()
+				break
+			case "toggleMaximize":
+				// eslint-disable-next-line no-console
+				console.log(win?.isMaximized())
+				win?.isMaximized() ? win?.unmaximize() : win?.maximize()
+				break
+			case "togglePin":
+				win?.setAlwaysOnTop(!win?.isAlwaysOnTop())
+				break
+			default:
+				throw new Error(`Invalid action: ${action}`)
+		}
+		cb?.(win, action)
+	})
+}

package/src/runtime/electron/getEventWindow.ts

@@ -0,0 +1,19 @@
+import { BrowserWindow } from "electron"
+
+/**
+ * Gets the window that sent the event if it exists, otherwise tries to use the focused window.
+ *
+ * Set `defaultToFocused` to false to only use the sender window.
+ *
+ * Returns undefined if no window is found.
+ */
+export function getEventWindow(
+	e: Electron.IpcMainEvent,
+	{ defaultToFocused = true } = {}
+): BrowserWindow | undefined {
+	const senderWindow = BrowserWindow.fromId(e.sender.id)
+	if (defaultToFocused) {
+		return senderWindow ?? BrowserWindow.getFocusedWindow() ?? undefined
+	}
+	return senderWindow ?? undefined
+}

package/src/runtime/electron/getPaths.ts

@@ -0,0 +1,68 @@
+import { unreachable } from "@alanscodelog/utils/unreachable"
+import { app } from "electron"
+import path from "node:path"
+
+import { STATIC } from "./static.js"
+
+export function forceRelativePath(filepath: string): string {
+	return path.join(`.${path.sep}`, filepath)
+}
+
+/**
+ * Calculates the correct paths for the app to run in electron.
+ *
+ * Note: For serverUrl to not be overridable in production, you should set `electron.additionalElectronVariables.publicServerUrl` to a quoted string.
+ *
+ * ```ts[nuxt.config.ts]
+ * export default defineNuxtConfig({
+ * 	modules: [
+ * 		"@witchcraft/nuxt-electron",
+ * 	],
+ * 	electron: {
+ * 		additionalElectronVariables: {
+ * 			publicServerUrl: process.env.NODE_ENV === "production"
+ * 			? `"mysite.com"`
+ * 			: `undefined`
+ * 		}
+ * 	}
+ * })
+ * ```
+ */
+export function getPaths(): {
+	windowUrl: string
+	publicServerUrl: string
+	nuxtPublicDir: string
+	preloadPath: string
+} {
+	const rootDir = app.getAppPath()
+	const nuxtPublicDir = path.resolve(rootDir, forceRelativePath(STATIC.ELECTRON_NUXT_PUBLIC_DIR!))
+
+	const preloadPath = path.resolve(rootDir, forceRelativePath(STATIC.ELECTRON_BUILD_DIR!), "./preload.cjs")
+
+	const base = {
+		nuxtPublicDir,
+		preloadPath,
+		publicServerUrl: (process.env.PUBLIC_SERVER_URL
+			// allows us to override it when previewing (VITE_DEV_URL is not available then)
+			?? process.env.PUBLIC_SERVER_URL
+			?? process.env.VITE_DEV_SERVER_URL)!
+	}
+	if (!base.publicServerUrl) {
+		throw new Error("publicServerUrl could not be determined.")
+	}
+
+	if (process.env.VITE_DEV_SERVER_URL) {
+		return {
+			...base,
+			windowUrl: `${process.env.VITE_DEV_SERVER_URL}${STATIC.ELECTRON_ROUTE}`
+		}
+		// this will always be defined in production since they are defined by vite
+	} else if (STATIC.ELECTRON_PROD_URL && STATIC.ELECTRON_BUILD_DIR) {
+		return {
+			...base,
+			// careful, do not use path.join, it will remove extra slashes
+			windowUrl: `file://${STATIC.ELECTRON_PROD_URL}`
+		}
+	}
+	unreachable()
+}

package/src/runtime/electron/getPreloadMeta.ts

@@ -0,0 +1,36 @@
+/**
+ * The preload script can be passed arguments using the `webPreferences.additionalArguments` option.
+ *
+ * ````ts [main.ts]
+ * const meta = { ... }
+ *
+ * const win = new BrowserWindow({
+ * 	webPreferences: {
+ * 		additionalArguments: [
+ * 			// you can change which key is used
+ * 			`--metadata=${JSON.stringify(meta)}`,
+ * 		],
+ * 	},
+ * })
+ * ```
+ *
+ * ````ts [preload.ts]
+ * const meta = getPreloadMeta<Meta>("metadata")
+ * ```
+ *
+ * This function can be used to get the metadata and type it in the preload script.
+ *
+ * Note that if it can't find the argument or there is an error parsing the json, it will throw.
+ */
+export function getPreloadMeta<T>(
+	key: string
+): T {
+	const meta = process.argv
+		.find(arg => arg.startsWith(`--${key}=`))
+		?.split("=")?.[1]
+
+	if (!meta) {
+		throw new Error("No metadata passed to renderer.")
+	}
+	return JSON.parse(meta)
+}

package/src/runtime/electron/index.ts

@@ -0,0 +1,17 @@
+export * from "./types"
+// note adding file endings breaks build types
+export { getPaths } from "./getPaths"
+export { createNuxtFileProtocolHandler } from "./createNuxtFileProtocolHandler"
+export { createWindowControlsApi } from "./createWindowControlsApi"
+export { createWindowControlsApiHandler } from "./createWindowControlsApiHandler"
+export { useNuxtRuntimeConfig } from "./useNuxtRuntimeConfig"
+export { STATIC } from "./static"
+export { apiBuilder } from "./apiBuilder"
+export { useDevDataDir } from "./useDevDataDir"
+export { registerDevtoolsShortcuts } from "./registerDevtoolsShortcuts"
+export { promisifyApi } from "./promisifyApi"
+export { getPreloadMeta } from "./getPreloadMeta"
+export { getEventWindow } from "./getEventWindow"
+export { promisifyReply } from "./promisifyReply"
+export { createBroadcaster } from "./createBroadcaster"
+export { createBroadcastHandlers } from "./createBroadcastHandlers"

package/src/runtime/electron/promisifyApi.ts

@@ -0,0 +1,102 @@
+import type { IpcRenderer } from "electron"
+
+const promiseResolveMap = new Map<string, {
+	resolve: (value: any) => void
+	reject: (reason?: any) => void
+}>()
+
+/**
+ * Promisify an electron api and make it type safe so it can be awaited client side. Note that promisifyReply will throw if it can't find a window.
+ *
+ * ```ts[type.st]
+ * export type ElectronApi = {
+ * 	api: {
+ * 		someApi: (apiParam: string, apiParam2: number) => Promise<void>
+ * 	}
+ * }
+ * ```
+ * ```ts [preload.ts]
+ * contextBridge.exposeInMainWorld("electron", {
+ * 	api: {
+ * 		...promisifyApi<"someApi", ElectronApi["api"]["someApi"]>(ipcRenderer, "someApi", MESSAGE.UNIQUE_KEY),
+ * 	},
+ * })
+ * ```
+ *
+ * ```ts [main.ts]
+ * import { promisifyReply } from "@witchcraft/nuxt-electron/runtime/electron"
+ * promisifyReply<
+ * 	ElectronApi["api"]["someApi"]
+ * >(ipcRenderer, MESSAGE.UNIQUE_KEY, (win, apiParam, apiParam2) => {
+ * 	// this doesn't have to be async, though on the client side,
+ * 	// it will always be async
+ * 	return electronSideOfApi(apiParam, apiParam2)
+ * })
+ * ```
+ *
+ * ```ts [renderer.ts]
+ * const result = await electron.api.someApi(apiParam, apiParam2)
+ * ```
+ *
+ * By default, calls will timeout and reject after 10 seconds. This can be changed by changing the timeout option.
+ */
+export function promisifyApi<
+	TKey extends string,
+	TFunction extends (...args: any) => Promise<any>,
+	TArgs extends Parameters<TFunction> = Parameters<TFunction>
+>(
+	ipcRenderer: IpcRenderer,
+	key: TKey,
+	messageKey: string,
+	modifyArgs?: (args: TArgs) => any,
+	{ debug, timeout }: { debug?: boolean, timeout?: number } = { debug: true, timeout: 10000 }
+): Record<TKey, TFunction> {
+	return {
+		[key]: async (...args: TArgs) => new Promise((resolve, reject) => {
+			// preload script should have access to crypto
+			// can't seem to get node crypto to import even renamed
+			const promiseId = crypto.randomUUID()
+			promiseResolveMap.set(promiseId, { resolve, reject })
+			if (modifyArgs) {
+				args = modifyArgs(args)
+			}
+			if (debug) {
+				// eslint-disable-next-line no-console
+				console.log("promisifyApi:sent", messageKey, promiseId, args)
+			}
+
+			const timer: number | NodeJS.Timeout = setTimeout(() => {
+				const resolver = promiseResolveMap.get(promiseId)
+				if (resolver) {
+					promiseResolveMap.delete(promiseId)
+					ipcRenderer.off(messageKey, listener)
+					resolver.reject(new Error(`promisifyApi: Timeout for ${messageKey}`))
+				}
+			}, timeout)
+			function listener(
+				_event: Electron.IpcRendererEvent,
+				resPromiseId: string,
+				res: any,
+				info?: { isError?: boolean }
+			): void {
+				if (debug) {
+					// eslint-disable-next-line no-console
+					console.log("promiseApi:received", resPromiseId, res)
+				}
+				const resolver = promiseResolveMap.get(resPromiseId)
+				if (resolver) {
+					clearTimeout(timer)
+					promiseResolveMap.delete(resPromiseId)
+					ipcRenderer.off(messageKey, listener)
+					if (info?.isError) {
+						resolver.reject(res)
+					} else {
+						resolver.resolve(res)
+					}
+				}
+			}
+			ipcRenderer.on(messageKey, listener)
+			ipcRenderer.send(messageKey, promiseId, ...args)
+		})
+	} as any
+}

package/src/runtime/electron/promisifyReply.ts

@@ -0,0 +1,49 @@
+import { type BrowserWindow, ipcMain } from "electron"
+
+import { getEventWindow } from "./getEventWindow.js"
+
+/** See {@link promisifyApi} for more info. */
+export function promisifyReply<
+	TFunction extends ((...args: any[]) => any),
+	TKey extends string = string,
+	TArgs extends Parameters<TFunction> = Parameters<TFunction>,
+	TReturn extends ReturnType<TFunction> = ReturnType<TFunction>
+>(
+	key: TKey,
+	cb: (win?: BrowserWindow, ...args: TArgs) => Promise<TReturn> | TReturn,
+	/** See {@link getEventWindow}. */
+	{
+		defaultToFocused = true,
+		debug = false
+	}: {
+		defaultToFocused?: boolean
+		debug?: boolean
+	} = {}
+): void {
+	ipcMain.on(key, (
+		e,
+		promiseId: string,
+		...args: any[]
+	) => {
+		const win = getEventWindow(e, { defaultToFocused })
+		if (!win) {
+			throw new Error("No window to send reply to.")
+		}
+		if (debug) {
+			// eslint-disable-next-line no-console
+			console.log({ key, promiseId, args })
+		}
+		const res = cb(win, ...args as TArgs)
+		if (res instanceof Promise) {
+			res.then((innerRes: any) => {
+				win.webContents.send(key, promiseId, innerRes)
+			}).catch(err => {
+				// eslint-disable-next-line no-console
+				console.error(err, { key, promiseId, args })
+				win.webContents.send(key, promiseId, err, { isError: true })
+			})
+		} else {
+			win.webContents.send(key, promiseId, res)
+		}
+	})
+}

package/src/runtime/electron/registerDevtoolsShortcuts.ts

@@ -0,0 +1,12 @@
+/** Registers F12 and Ctrl+Shift+I as shortcuts to open the devtools. */
+export function registerDevtoolsShortcuts(win: Electron.BrowserWindow): void {
+	win.webContents.on("before-input-event", (event, input) => {
+		if (input.type === "keyDown") {
+			if ((input.shift && input.control && input.key.toLowerCase() === "i")
+				|| (input.key === "F12")) {
+				win.webContents.openDevTools()
+				event.preventDefault()
+			}
+		}
+	})
+}

package/src/runtime/electron/static.ts

@@ -0,0 +1,14 @@
+import type { PublicRuntimeConfig } from "nuxt/schema"
+
+// Note that we must write them out like this (with the full path to the env variable) for vite to find them.
+/**
+ * Group of the module's vite's injected variables.
+ */
+export const STATIC = {
+	ELECTRON_ROUTE: process.env.ELECTRON_ROUTE!,
+	ELECTRON_PROD_URL: process.env.ELECTRON_PROD_URL!,
+	ELECTRON_NUXT_DIR: process.env.ELECTRON_NUXT_DIR!,
+	ELECTRON_NUXT_PUBLIC_DIR: process.env.ELECTRON_NUXT_PUBLIC_DIR!,
+	ELECTRON_BUILD_DIR: process.env.ELECTRON_BUILD_DIR!,
+	ELECTRON_RUNTIME_CONFIG: (process.env.ELECTRON_RUNTIME_CONFIG ? JSON.parse(process.env.ELECTRON_RUNTIME_CONFIG) : undefined) as PublicRuntimeConfig
+}

package/src/runtime/electron/types.ts

@@ -0,0 +1 @@
+export type WindowControlsApi = (action: "close" | "minimize" | "toggleMaximize" | "togglePin")	=> Promise<void>

package/src/runtime/electron/useDevDataDir.ts

@@ -0,0 +1,8 @@
+export function useDevDataDir(): string | undefined {
+	if (import.meta.dev) {
+		const index = process.argv.findIndex(arg => arg.startsWith("--user-data-dir")) + 1
+		if (index === -1) return undefined
+		return process.argv[index + 1]
+	}
+	return undefined
+}

package/src/runtime/electron/useNuxtRuntimeConfig.ts

@@ -0,0 +1,7 @@
+import type { PublicRuntimeConfig } from "nuxt/schema"
+
+import { STATIC } from "./static.js"
+
+export function useNuxtRuntimeConfig(): PublicRuntimeConfig {
+	return STATIC.ELECTRON_RUNTIME_CONFIG
+}

package/src/runtime/utils/isElectron.ts

@@ -0,0 +1,11 @@
+/**
+ * This requires electron's preload script set the `electron` property on the window:
+ *
+ * ```ts
+ * // preload.ts
+ * contextBridge.exposeInMainWorld("electron", { })
+ * ```
+ */
+export function isElectron(): boolean {
+	return typeof window !== "undefined" && "electron" in window && typeof window.electron !== "undefined"
+}