@witchcraft/nuxt-electron 0.2.0 → 0.2.1

package/README.md

@@ -15,6 +15,7 @@
 - :scissors: Trims server and non-electron routes from the electron bundle.
 - :open_file_folder: Modifies directory structure for easier multi-platform builds.
 - :snowflake: Nix Support - Playground contains an example flake for reproducible development and builds.
+- :closed_lock_with_key: Supports Auth - Integrates with my auth library [@witchcraft/nuxt-auth](https://github.com/witchcraftjs/nuxt-auth) for local-first auth.
 - :hammer_and_wrench: Helpful Tools/Composables
 	- `isElectron` 
 	- Electron Only 
@@ -47,11 +48,15 @@ pnpm build
 pnpm build:electron:pack
 # in one tab
 pnpm preview
-# in another tab
+# in another tab - replace `linux-unpacked` with your platform
 OVERRIDE_PUBLIC_SERVER_URL=http://localhost:3000 ./.dist/electron/release/linux-unpacked/your-app-name
 ```
 
-If you're using nix the above should work in the dev shell. You can also do `nix run` but warning, this is like just building and doing `pnpm launch:electron` (see below).
+#### Nix
+
+If you're using nix the first example should work in the dev shell. The second won't. You can do `nix run`, but warning, this is like building and doing `pnpm launch:electron` so it api will be pointed at production server (see below).
+
+See [#Usage on Nix](#Usage-on-Nix) for more details.
 
 ## Install
 ```bash
@@ -83,7 +88,10 @@ A directory structure like the following is suggested:
 │       │   └── ${productName}_${version}.${ext}
 │       └── build/ (for any intermediate builds like electron's)
 ├── app/ - nuxt code
-└── app-electron/ - contains all the main/renderer code
+├── app-electron/ - contains all the main/renderer code
+│   └── package.json - to control packaged dependencies
+└── electron-builder-config.js
+
 ```
 The module sets it up like this when building electron, but not for the regular build. You should set that to go elsewhere if you're using it (though it's not required).
 
@@ -103,36 +111,12 @@ Usage of nuxt 4's new directory structure is recommended.
 
 For whatever electron builder you want to use, you must point it at the correct directories.
 
-For `electron-builder` with the default directories the module uses and to have all the artifacts in one folder, add:
+For `electron-builder` with the default directories the module uses and to be able to control which dependencies are packaged with `app-electron/package.json` copy the following:
 
+[electron-builder-config.js](https://github.com/witchcraftjs/nuxt-electron/blob/master/playground/electron-builder-config.js)
+[app-electron/package.json](https://github.com/witchcraftjs/nuxt-electron/blob/master/playground/app-electron/package.json)
 
-<details>
-<summary>Electron Builder Config Example</summary>
-
-```json
-{
-	"directories": {
-		"output": ".dist/electron/release"
-	},
-	"files": [
-		".dist/electron/build/**/*",
-		".dist/electron/.output/public/**/*"
-	],
-	"linux": {
-		"artifactName": "${productName}_${version}.${ext}",
-		// ...
-	},
-	"mac": {
-		"artifactName": "${productName}_${version}.${ext}",
-		// ...
-	},
-	"win": {
-		"artifactName": "${productName}_${version}.${ext}"
-		// ...
-	},
-}
-```
-</details>
+They should work out of the box, with the package name as configured in your package.json. 
 
 Add the following to the package.json:
 
@@ -142,6 +126,12 @@ Add the following to the package.json:
 ```json
 // package.json
 {
+	// these first properties are required to package the app
+	"name": "your-app-name",
+	"version": "0.0.0",
+	"description": "Your app description",
+	"author": "Your Name",
+	"repository" :"...",
 	"main": ".dist/electron/build/main.cjs",
 	"scripts": {
 		"dev": "nuxi dev",
@@ -152,7 +142,7 @@ Add the following to the package.json:
 		"launch:electron": "electron .",
 		"launch:electron:dev": "LOG_LEVEL=trace OVERRIDE_PUBLIC_SERVER_URL=http://localhost:3000 electron .",
 		"build:electron": "BUILD_ELECTRON=true pnpm build",
-		"build:electron:pack": "APP_VERSION=0.0.0 electron-builder",
+		"build:electron:pack": "APP_VERSION=0.0.0 electron-builder --config electron-builder-config.js",
 		"build:electron:no-pack": "APP_VERSION=0.0.0 SKIP_ELECTRON_PACK=true BUILD_ELECTRON=true nuxi build",
 		// write a dev desktop file for linux, see below
 		"preview:electron:dev": "concurrently --kill-others \"pnpm preview\" \"sleep 2 && pnpm launch:electron:dev\"",
@@ -162,7 +152,7 @@ Add the following to the package.json:
 ```
 </details>
 
-#### To Develop
+### To Develop
 
 Run `pnpm dev:electron`. This will both launch nuxt and open electron.
 
@@ -172,12 +162,12 @@ Run `pnpm dev` to start the nuxt dev server. The dev version of the app will be
 
 In a seperate terminal run `pnpm launch:electron` to start the electron app (this will do `electron .` which will run the configured `main` property, aka `.dist/electron/build/main.cjs`).
 
-##### Notes
+#### Notes
 By default the module will not open electron. You must set `process.env.AUTO_OPEN` to include the string `electron` or set `autoOpen `in the options to true, hence the seperate `dev:electron` script.
 
 The idea is if you use other platform modules as well, you'd do `AUTO_OPEN=electron,android`, etc. for each module you wanted to actually have auto open.
 
-#### To Build
+### To Build
 
 Build the regular nuxt app with `pnpm build` then build the electron app with `pnpm build:electron` or `pnpm build:electron:no-pack` (if you just want to test, you can skip the packing).
 
@@ -191,7 +181,7 @@ You can run `pnpm launch:electron` to launch the production build in nearly exac
 
 CAREFUL though, **this will proxy api requests to the real server**.
 
-If you want to test against the local server build, run it with `pnpm preview` then run the app with `pnpm launch:electron:dev`.
+ef you want to test against the local server build, run it with `pnpm preview` then run the app with `pnpm launch:electron:dev`.
 
 If you use the example code, it allows `OVERRIDE_PUBLIC_SERVER_URL` which allows the app to override which server the app proxies to and that's what the script is setting to allow this.
 
@@ -208,7 +198,6 @@ We also need to create the nuxt `app://` protocol handler for every window and c
 
 See full example in [main.ts](https://github.com/witchcraftjs/nuxt-electron/blob/master/playground/app-electron/main.ts).
 
-
 For the nuxt config, here's the minimum you need, the one in the playground contains additional options for testing and debugging:
 
 <details>
@@ -238,7 +227,8 @@ export default defineNuxtConfig({
 				? `"https://yoursite.com"`
 				: `undefined`
 		},
-		// the module will set this to pre-render
+		// the module will set this to prerender: true
+		// you can override it in routeRules and create a spa without prerender if you need
 		// additionalRoutes: ["/other-page-prerendered"]
 	}
 })
@@ -292,20 +282,51 @@ And a third parameter pointing to your config if it's not in one of the searched
 - `electron-builder.json5`
 - `electron-builder.json`
 
+### Usage on Nix
+
+As mentioned, the second example script won't work out of the box with nix. You need something like [nix-alien](https://github.com/thiagokokada/nix-alien) if you want to test the electron-builder packaged version (**which you should**, it is packaged completely different than on nix where electron builder is not used).
+
+```
+DEBUG=true LOG_LEVEL=trace nix run "github:thiagokokada/nix-alien#nix-alien" -- .dist/electron/release/linux-unpacked/your-app-name
+```
+
+Apart from that nix has some additional goodies.
+
+First there flake with a devenv based shell and direnv support. If you have direnv run `direnv allow .` in the project root. Otherwise run `nix develop`.
+
+Nearly everything should work, except the build electron-builder builds. You can do `nix run` instead.
+
+The derivation for reference is [here](https://github.com/witchcraftjs/nuxt-electron/blob/master/playground/nix/derivation.nix).
+
+There is also a debugging script `debugNixBuild` which drops you in a shell to run the derivation. See it for details. The shell should give you info about all scripts.
+
+It uses a set of devenv flake utils I've created (see [here](https://github.com/alanscodelog/nix-devenv-utils)). They contain some good stuff like working support for electron (obviously), android, playwright, etc if you're interested.
+
 ## Misc Notes
 
-Note that while nuxt's path aliases are passed to the electron vite config, you cannot use other nuxt paths (such as those added by modules, e.g. `#somemodule`) in electron. This is why a seperate `@witchcraft/nuxt-electron/electron` export is provided.
+- Note that while nuxt's path aliases are passed to the electron vite config, you cannot use other nuxt paths (such as those added by modules, e.g. `#somemodule`) in electron. This is why a seperate `@witchcraft/nuxt-electron/electron` export is provided.
+- In any electron main code, import.meta.url is always the built main.mjs file regardless of whether you're in dev or prod or what file you're in.
+
+## Auth
+
+While you might not want to use it (it is very beta) my auth library [@witchcraft/nuxt-auth](https://github.com/witchcraftjs/nuxt-auth) contains a whole section on auth flow on electron. It also contains electron specific code for doing local-first auth which you might find helpful (more code will be added as I figure more things out). It includes support for "semi-authed" local only users and handling "synced" users who can remain "logged in" past authentication expiration so long as they don't perform actions that require auth (e.g. sync). 
+
+I do not use an existing lib because I have not found any that support complex scenarios like these. 
+
+This takes a lot of careful consideration and planning to implement like this. I'm still working on some pain points. 
+
+I mention it because you will need to render your login page as a SPA to get it working. This makes middleware "soft" on that page, just so you're aware. You will also need to proxy auth requests.
 
 
 ## How it Works
 
-#### Development
+### Development
 
 Electron is pointed to the localhost server and sees a similar view to the web app except we must client side detect we're on electron and redirect to the `electronRoute`.
 
-#### Production
+### Production
 
-Normally nuxt has to be configured to output a SPA by setting `ssr: false` and you have to modify baseURL and buildAssetsDir for everything to work (among other changes, see nuxt-electron module for the typical changes).
+Normally nuxt would have had to be configured to output a SPA by setting `ssr: false` and you have to modify baseURL and buildAssetsDir for everything to work (among other changes, see nuxt-electron module for the typical changes).
 
 But this module has gone a different route.
 
@@ -313,7 +334,7 @@ First for production only changes, we run the nuxt config with a different env v
 
 Then we use a custom protocol to proxy requests and api calls.
 
-##### Custom `app://` Handler 
+#### Custom `app://` Handler 
 
 Electron uses the `file://` protocol by default to load all scripts/assets/etc. 
 
@@ -343,13 +364,13 @@ We then need to remove unwanted routes from the bundle which are included regard
 
 Note we would ideally also remove "/" from the prerender, but this requires manually splitting chunks by pages and I was having issues with this.
 
-###### Why not use a redirect? 
+##### Why not use a redirect? 
 
 A `routeRules` redirect won't work, because it will trigger a request to electron's file protocol handler which we don't know what to do with.
 
 A redirect from a page (e.i. `if (process.client && isElectron) { await navigateTo("/app") }`) works, but it takes a little big of time to navigate. This is still needed for development redirecting, but not in production.
 
-#### Build
+### Build
 
 Building for electron requires lots of changes to the config. We can't just build for web then copy. So this module reroutes the output when building the web app (and reroutes it differently when building for electron (see directory sturcture above).
 
@@ -357,7 +378,7 @@ The reason for the nested `.output` is so it doesn't overwrite the default one.
 
 To build for electron you must set `process.env.BUILD_ELECTRON` to true, to do the configuration required to make the final output actually work with electron.
 
-##### Electron Build
+#### Electron Build
 
 The electron app itself is "built" in two parts, the "build" and the "packing".
 
@@ -371,6 +392,13 @@ Note that nuxt builds the server anyways, it's just not packed into the final ap
 
 Your packer should then create the final executables (into `.dist/electron/release`).
 
+### Debugging Tips
+
+-  To inspect the asar, run `npx @electron/asar list .dist/electron/release/linux-unpacked/resources/app.asar`.
+- If routes aren't rendering:
+	- Check the final config in the ready hook. Other modules might be causing issues.
+	- Check your structure is correct (`pages/page.vue` with NuxtPage, `pages/page/index.vue`).
+
 
 <!-- Badges -->
 [npm-version-src]: https://img.shields.io/npm/v/@witchcraft/nuxt-electron/latest.svg?style=flat&colorA=020420&colorB=00DC82

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "name": "electron",
   "configKey": "electron",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

package/dist/module.mjs

@@ -331,13 +331,17 @@ const module$1 = defineNuxtModule({
       nuxtRemoveUneededPages(nuxt, ["/", electronRoute, ...options.additionalRoutes]);
       nuxt.options.router.options ??= {};
       nuxt.options.router.options.hashMode = false;
+      extendRouteRules(electronRoute + "/", {
+        prerender: true
+      }, { override: true });
       extendRouteRules(electronRoute + "/**", {
         prerender: true
       }, { override: true });
       for (const route of options.additionalRoutes) {
         extendRouteRules(route, {
           prerender: true
-        }, { override: true });
+          // allow user to set something else and use a spa
+        }, { override: false });
       }
       nuxt.hook("prerender:routes", ({ routes }) => {
         for (const route of ["/404.html"]) {

package/dist/runtime/electron/createProxiedProtocolHandler.js

@@ -22,7 +22,7 @@ async function getPathToServe(originalPath, pathWithIndexHtml, key, logger) {
     logger.trace({
       ns: "main:createProxiedProtocolHandler:stats",
       key,
-      stats,
+      exists: !!stats,
       isFile: stats?.isFile(),
       isDirectory: stats?.isDirectory()
     });

package/dist/runtime/electron/getPaths.js

@@ -32,7 +32,7 @@ export function getPaths(protocolName = "app", overridingEnvs = {
     return {
       ...base,
       // careful, do not use path.join, it will remove extra slashes
-      windowUrl: `${protocolName}://bundle/${STATIC.ELECTRON_PROD_URL}`
+      windowUrl: `${protocolName}://bundle${STATIC.ELECTRON_PROD_URL}`
     };
   }
   unreachable();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@witchcraft/nuxt-electron",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Nuxt module for working with electron.",
   "repository": "https://github.com/witchcraftjs/nuxt-electron",
   "license": "MIT",

package/src/module.ts

@@ -521,6 +521,11 @@ export default defineNuxtModule<ModuleOptions>({
 			nuxt.options.router.options ??= {}
 			nuxt.options.router.options.hashMode = false
 
+			// its not a smart merge or anything, so we need to override both possibilities
+			extendRouteRules(electronRoute + "/", {
+				prerender: true
+			}, { override: true })
+
 			extendRouteRules(electronRoute + "/**", {
 				prerender: true
 			}, { override: true })
@@ -528,7 +533,8 @@ export default defineNuxtModule<ModuleOptions>({
 			for (const route of options.additionalRoutes) {
 				extendRouteRules(route, {
 					prerender: true
-				}, { override: true })
+				// allow user to set something else and use a spa
+				}, { override: false })
 			}
 
 

package/src/runtime/electron/createProxiedProtocolHandler.ts

@@ -36,7 +36,7 @@ async function getPathToServe(
 		logger.trace({
 			ns: "main:createProxiedProtocolHandler:stats",
 			key,
-			stats,
+			exists: !!stats,
 			isFile: stats?.isFile(),
 			isDirectory: stats?.isDirectory()
 		})

package/src/runtime/electron/getPaths.ts

@@ -66,7 +66,7 @@ export function getPaths(
 		return {
 			...base,
 			// careful, do not use path.join, it will remove extra slashes
-			windowUrl: `${protocolName}://bundle/${STATIC.ELECTRON_PROD_URL}`
+			windowUrl: `${protocolName}://bundle${STATIC.ELECTRON_PROD_URL}`
 		}
 	}
 	unreachable()