5et-desktop/README.md

5ET-D Desktop App

Current stage:

• Build 0 complete: Electron boots directly into local 5etools wiki.
• Stage 1 in progress: React shell navigation + light visual reskin pass, while preserving wiki behavior.
• Character Creator milestone 1 added:
  • Create new character
  • Load character from JSON
  • View/edit saved characters

Prerequisites

• Node.js 20+
• Git (only required if setup mode uses source/image repository URLs)

On first launch, if no local source is found, the app opens a setup window. Setup supports either:

• Source repository URL clone
• Local source ZIP import

Images can be cloned from an image repository URL, and/or loaded from an external image base URL fallback.

Optional override:

• Set FIVEETOOLS_SRC_DIR to point at a different 5etools-src path.
• Set FIVEETOOLS_DESKTOP_RESKIN=0 to disable injected wiki styling for strict baseline comparisons.
• Set FIVEETOOLS_DESKTOP_FORCE_NIGHT=0 to keep 5etools day theme while using desktop reskin.

Install

npm install

Run (dev)

npm run dev

npm run dev uses a portless workflow (vite build --watch) for environments where local TCP binding is restricted.

Optional HMR mode (requires local port binding):

npm run dev:web

Run (build once + launch)

npm run start

Package installers

npm run dist

This command installs electron-builder on demand via npx for packaging, rather than during every local dependency install.

macOS arm64 (source release workflow)

If macOS runners are unavailable in CI, publish the 5ET-D-macos-arm64-source-* artifact and have Apple Silicon users build locally:

./build-macos-arm64.command

Equivalent CLI command:

./scripts/build-macos-arm64.sh

This builds a macOS arm64 package and writes output to release/.

Notes

• The app starts an internal local HTTP server for wiki content.
• This avoids file:// loading limitations while keeping content fully local.
• Electron launch scripts clear ELECTRON_RUN_AS_NODE automatically, so app boot is stable even if that variable is set in your shell environment.
• Character files are stored as JSON under the app user-data directory:
  • <userData>/characters/<character-id>.json
  • one file per character
• SQLite is intentionally deferred until a later character-system migration phase.
• Build identity is set to:
  • Product name: 5ET-D
  • App ID: com.notBoris.5et-desktop

Troubleshooting

• app.whenReady undefined or Electron behaving like Node:
  • check echo $ELECTRON_RUN_AS_NODE
  • launcher scripts already clear this variable before app start
• listen EPERM ...5173:
  • use npm run dev (portless mode)
  • only use npm run dev:web when local TCP binding is available