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
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, neversrc/mainimports.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.