FAQ / Gotchas

• Why is the bundle/runtime heavy? Because a real Next.js server runs in-process — that's the feature, not a leak. You trade size for full Next.js fidelity.
• Can I use API routes / Server Actions? Yes — they run on the in-process server bound to 127.0.0.1. Add your own auth to anything sensitive.
• Does next/image work? Yes, with images.unoptimized: true (set in the template) because the packaged app is read-only.
• My custom title-bar buttons show on the web build. Gate them behind useWindow().isAvailable.
• useShell does nothing. It's mode: 'none' by default. Set shell.mode to 'allowed' (+ allowedCommands) or 'all' in registerNextOP.
• useSecureStore.setItem throws. OS encryption isn't available (e.g. no Linux keyring). Check isAvailable() first.
• Windows packaging fails on symlink/winCodeSign. Enable Developer Mode or run the terminal as Administrator.
• useDialog's showOpenDialog/showSaveDialog resolve null. The user cancelled — this is not an error, just check for null before using the result.
• useGlobalShortcut's isRegistered stays false. The accelerator is already reserved by the OS or another app; globalShortcut.register returned false. Pick a different accelerator.
• useTray shows no icon / wrong icon. It defaults to electron/assets/favicon.ico relative to the compiled main process — pass options.icon with an absolute path to override.
• useStore vs useSecureStore. useStore never encrypts (plaintext JSON on disk) — use it for settings/preferences, not tokens or secrets.