nexus-mobile-compat

name

nexus-mobile-compat

description

Keep Nexus loading on mobile and compliant with the Obsidian plugin store — vet a dependency, import without crashing init, confine a vault path, and prove none of it regressed with the reachability checker. Use before adding an npm package or a Node import, when writing to caller-supplied vault paths, when gating a desktop-only feature, when a PDF or worker-backed feature misbehaves, or when the plugin fails to load on a phone.

Nexus mobile & plugin-store safety

Nexus ships isDesktopOnly: false, so main.js runs on phones with no Node.js. The defect this skill exists to prevent has no compiler and no type behind it: a static import executes during module init, before any Platform.isDesktop check, so one import on the startup path takes the plugin down at launch on every phone — from a diff that looks unrelated.

The reachability checker below is now wired into the repo's own gate: npm run lint runs lint:obsidian (ESLint) then lint:mobile (this checker), and npm run build runs npm run lint first. A violation fails the build. Run the checker directly anyway while you work — the gate is the floor, not the loop.

Workflow

Pick the row that matches the job and follow that protocol. Do not improvise from this page; each protocol carries the steps and the checks.

Situation	Protocol
Adding or upgrading an npm package	protocols/vet-a-dependency.md
Need a Node built-in, a heavy module, or a desktop-only feature	protocols/import-without-crashing.md
Writing, reading or deleting at a caller-supplied vault path	protocols/confine-a-vault-path.md
About to ship a change that touched imports or the startup path	protocols/verify-mobile-safety.md
"It won't load on my phone" / a mobile-only failure	protocols/diagnose-mobile-crash.md
Session that used this skill is ending	protocols/self-refine.md

1. Read the protocol the table names, in full, before editing anything.

2. Whatever the protocol, you MUST run the reachability checker before calling the change done — it is the only guard for this defect class:

   node scripts/check-mobile-imports.mjs .
   # identical, the way the build invokes it:
   npm run lint:mobile
   

   scripts/check-mobile-imports.mjs in the repo IS the checker — one implementation, edit it there. It was a Python script behind a launcher until 2026-08-15, when Obsidian's community scorecard failed build verification on a clean container that has Node but no Python. A build gate may only depend on what the build already needs.

   It walks static imports from src/main.ts, follows no await import(), and exits non-zero when a Node built-in is reachable from init. Run --help for --trace <file> (is this module on the startup path, and via what chain) and --packages (which npm packages init loads).

3. npm run lint now runs both halves: ESLint for the store rules that are mechanical, then the reachability checker. A green ESLint says nothing about reachability, and a green checker says nothing about the store rules — which is why the composed script runs both, and why npm run build calls it. ESLint additionally hard-errors on Node built-in and Node-dependent package imports under src/settings/components/** (issue #221): those shared UI primitives are reachable from init today, but the per-file ban holds even if the import graph shifts. The blocklists are the MOBILE_BANNED_* arrays at the top of eslint.config.mjs; widen the guard by adding a glob to that block's files.

4. NEVER treat obsidian dev:mobile on as evidence of mobile safety. It emulates Platform.isMobile, touch and layout inside Electron, where require('fs') still resolves — this crash class cannot reproduce there. See references/init-order.md.

Map

• protocols/ the procedures above, each ending at the next one.
• references/ read on demand: init-order.md (why a platform guard below an import is decoration, and what reachability really guarantees), plugin-store-rules.md (the store rules and which are already lint-enforced), pdfjs-in-electron.md (the worker constraint and the single sanctioned entry).
• The import-graph checker lives in the repo, not here: scripts/check-mobile-imports.mjs. Run it; do not reimplement it as a grep — grep cannot see reachability, and this repo has known-correct hits that a grep reports as violations.

Boundaries

The full store guidance lives in docs/obsidian-plugin-guidelines.md; this skill is the part that bites in practice. Test lanes, the in-app Obsidian CLI loop and mock-versus-real questions belong to nexus-testing. Storage roots, the event store and migrations belong to nexus-storage. Release packaging belongs to nexus-release.