You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 

6.0 KiB

Electron Workshop

Intent

This is a reusable Electron + Vue template. Keep startup small, capabilities explicit and module boundaries independent. The original Zephyr application is a structural reference only; do not copy its credentials, identity, assets or update feed.

Commands

Use pnpm. Validate in order: pnpm lint, pnpm typecheck, pnpm test, pnpm build. pnpm test:e2e launches real Electron. pnpm package builds an unpacked application. Format with pnpm format.

Boundaries

  • packages/core: Node-only utilities, no Electron or application imports.
  • packages/contracts: browser-safe shared models and schemas, no routers, method registries, Node/Electron imports.
  • packages/electron-trpc: fixed-channel transport, separate main/preload/renderer entries; mandatory source authorization and lifecycle cleanup.
  • packages/desktop: Electron adapters; dependencies are constructor parameters, never src/main imports.
  • packages/ui: browser-only presentational Vue components.
  • src/main: service construction, feature-owned tRPC routers, common RPC runtime and background lifecycle.
  • src/preload: narrow capability bridge; no raw IPC exposure.
  • src/renderer: browser code; no runtime imports of desktop/core/main. The sole main import allowed is type-only AppRouter from src/main/trpc/app-router.ts.

Rules

  • Shared external dependency versions live in pnpm-workspace.yaml catalogs. Use catalog: for installed versions and catalog:peers for compatibility ranges; keep workspace:* for local packages.
  • Define each API once in src/main/modules/.ts (or its router.ts): procedure roles, input, output, query/mutation/subscription and direct service invocation. No ipc.register, method-name dispatch maps or ctx.invoke.
  • Keep shared models in contracts/src/.ts; index.ts only exports. Add schemas there only when they are genuinely shared; procedure-specific schemas belong beside the procedure.
  • src/main/trpc/runtime.ts owns common role middleware and error sanitization; app-router.ts only composes feature router factories; events.ts composes typed RpcEvent streams.
  • Factories declare their service dependencies with Pick<AppContext, ...>. Background modules use AppModule<...> and lifecycleModules; menu/timer/listener resources register cleanup in their Scope. Feature modules do not import sibling modules.
  • RpcGateway owns trusted window registration, source checks and request capacity, not business schemas or handlers. electron-trpc owns wire messages and cancellation.
  • Each query/mutation declares output validation. Every procedure explicitly allows roles with procedure([...]); missing roles deny access. RpcEvent validates every emitted payload and owner-scopes private events.
  • Use tRPC subscriptions for events; handle errors and unsubscribe on component/scope disposal. No parallel desktop.call/on bridge.
  • Main-process authorization must validate registered window, main frame, exact trusted page, role and request schema.
  • Every listener, timer, watcher and resource needs Scope cleanup. Static routers are disposed with the transport; removing a router from app-router.ts disables its methods.
  • File operations require a user-selected, window-owned opaque grant. Never accept arbitrary paths from renderer code.
  • Credentials stay in main; no plaintext IPC getter, logs, config defaults or committed env files.
  • New windows use WindowService; never override secure webPreferences.
  • Keep app identity and update feed in app.config.json. Default update feed is empty.
  • SQLite migrations are consecutive, transactional and reject downgrades.
  • Application settings use src/main/settings/store.ts, with an independent disk version and consecutive migrations. Preserve valid user values, back up before replacement, and reject newer versions without writing. Keep migration metadata out of RPC models; do not apply these rules implicitly to other JsonStore users.
  • Add focused behavioral tests for security, persistence and lifecycle changes.
  • No implicit startup side effects inside reusable packages.

Renderer and design

  • Read DESIGN.md before changing appearance. Edit design.tokens.json and run pnpm tokens to update both tokens.css and DESIGN.md generated YAML blocks; tokens:check verifies both. Maintain typography, component and interaction rules outside generated blocks manually. Never edit generated tokens.css directly.
  • app owns bootstrap, shared app info, appearance effects and layout; pages compose features; features own state, actions and scope cleanup. Keep feature styles scoped.
  • UI components are presentational and must not import application stores, routing, i18n or RPC.
  • Use the single inferred tRPC client directly in feature composables; do not add another API registry or wrapper layer.
  • Keep busy/error state per feature. Guard domain commits after await; useTask only guards feedback. Subscribe before snapshots, prevent stale response overwrites and release late-acquired file grants.
  • Use UiScrollArea for explicit scroll regions; keep the titlebar outside scrolling. No default per-frame scrollbar update loop.
  • The main process returns immutable window role; renderer route guards improve UX but never replace main authorization.

Capability and async rules

  • Optional services follow app.config.json capabilities and register cleanup at construction. Launch arguments may only disable capabilities. Keep API typing stable and reject disabled operations explicitly; UI visibility is not authorization.
  • Use useSnapshotStream for subscription-plus-snapshot sessions; reconnect explicitly and never retry mutations automatically. Query cancellation uses scope AbortSignal.
  • IPC defaults: query 15s, mutation 120s, subscription startup 15s. Override context.timeoutMs deliberately; native interaction and long downloads use 0. Cancellation is not rollback, and running business requests retain their capacity until completion.
  • Internal errors use diagnoseFailure and an incidentId. Never log arbitrary error.message, complete stacks, paths, input or credentials. Startup diagnostics include a fixed stage.