Compatibility

ppd 0.2.0 is verified on macOS with Paseo 0.12.0, desktop app and CLI. It relies on parts of Paseo that are not a public API, and says so when one of them moves instead of blaming your plugin.

What it needs

ToolForWithout it
Node >=22.18everything
Paseo desktop appthe real compiler, evaluator and Lucide list in ppd check, the web UI, agentTimelineppd check runs as a labeled approximation; ppd web needs a web UI build (--web-dist)
Paseo CLIppd daemon, install, dev, paseo, the fake agentno dev daemon
Google Chrome, or Playwright's Chromiumppd web, PaseoWebno screenshots
react-native devDependency, or HERMESC and HERMESthe Hermes compile and VM checksthose two checks skip
adbppd androidno phone

macOS and Linux. On Linux (CI), there is no Paseo app: daemon tests skip and ppd check is an approximation. Windows is not supported.

React Native, React and dependency updates

Paseo supplies React Native, React, the plugin SDK, TanStack Query and Zod at runtime. Their development dependencies give your editor and TypeScript a local API surface. Updating them does not replace the app's runtime or renderer. Match the oldest Paseo app you support, rather than selecting the newest React Native release independently. The manifest's requirements.paseo covers both the daemon and each connected app; it has no separate React Native key. SDK peer ranges constrain package installation, not verified host/API compatibility.

React Native's versioning policy permits breaking changes in 0.x minor releases. Treat a new minor series as a migration. Review React, React Native and SDK versions together; do not bypass conflicting peers to make CI green. Exact package pins do not stop Dependabot from proposing new versions. This optional rule keeps automated version PRs within the current React Native series:

# Under the relevant npm entry in updates:
ignore:
  - dependency-name: react-native
    update-types:
      - version-update:semver-minor
      - version-update:semver-major

This is a version-update policy, not an auto-merge rule. See Dependabot's ignore options. Review series upgrades separately when the supported host and its React/SDK requirements permit them.

For a candidate update, run ordinary npm ci, npm run typecheck, the plugin tests, and ppd check against the supported Paseo host. Then install into an isolated daemon and exercise the actual UI. Check a native client for changes to native components or behavior. ppd check includes compilation and load checks; it does not run TypeScript or prove every render path works. When targeting an older host, set HERMESC and HERMES to that host's engine: discovery otherwise prefers binaries shipped with the plugin's local React Native dependency.

Observed upgrade experiment

On 2026-10-22, an isolated copy of Paseo Plans (8bbe518) was tested against the pinned Paseo 0.12.0 host (cafe4b0), which uses React 19.1.0 and React Native 0.81.5:

ExperimentResult
Minimal dependency example: RN 0.87.1 with React 19.2.3Ordinary lockfile resolution passed
The same example with only RN changed to 0.88.0Resolution failed: RN requires React ^19.3.0
Plans with RN 0.88.0 and its original React 19.1.0Ordinary installation failed with ERESOLVE
Diagnostic copy with peers bypassed and required test-tooling peers restoredTypecheck failed on changed RN View and ScrollView ref types, including focus and scrollTo; 255 tests passed, one approximation test skipped
Same diagnostic copy, pinned host compiler and target-host Hermes13 checks passed; client and server bundle hashes were unchanged by the RN development dependency bump

The bypass was an experiment, not an accepted dependency configuration. An initial bypass also removed automatically installed SDK and Vitest peers; those missing tooling dependencies were restored before attributing the remaining type errors to React Native. The test shows why passing unit tests and host compilation cannot replace ordinary dependency resolution and TypeScript. It does not establish RN 0.88 runtime compatibility: the host renderer remained RN 0.81.5, no native host upgrade was attempted, and no user daemon or production dependency tree was changed. This experiment does not cover other plugins already adapted to RN 0.87.1 or newer host versions, and is not a universal RN compatibility range.

What ppd relies on

Relies onUsed byWhen it changes
compiler.js, bundle-evaluator.js and manifest.js from @getpaseo/server inside the app's app.asar (dist/server/server/plugins)ppd check (real compile and server evaluation)paseo-compile fails with "could not load Paseo's plugin compiler", the expected path, and the verified and found versions. ppd check --approx or PASEO_SOURCE works around it.
The Lucide exports in the app's web bundle (app-dist/_expo/static/js/web/index-*.js)icon checkslucide-icons warns and falls back to the plugin's own lucide-react-native.
@getpaseo/client and ws inside app.asaragentTimelinethe call fails naming the modules it looked for.
paseo daemon run --home, PASEO_HOME, PASEO_LISTEN and the config.json keysppd daemon upa start failure prints the daemon output and how it was started.
Accessible names in the web UI ("New workspace", "Open menu", "Workspace actions", "Search commands")ppd web, PaseoWeba timeout names the label it waited for.
Rules vendored from Paseo (client registration for 0.12 and 0.13 or later, the release that added each newer client method, manifest schema, build options)every ppd check (manifest, client-eval), the client check in ppd install and ppd dev, and the approximation's compiledrift shows up in the weekly CI job against Paseo main.

ppd daemon up prints a note when the installed Paseo is not 0.12.0, and ppd doctor shows the same text as a warning on its paseo CLI line:

note:  ppd was verified on Paseo <verified>; this is <found>

Tracking Paseo main

The devkit's CI runs its test suite every week against a fresh build of Paseo main (PASEO_SOURCE), and examples/ci.yml does the same for your plugin. A second weekly job fails once Paseo's latest release is no longer 0.12.0, until ppd is verified on the new one. When something breaks, an issue with the message helps: nkwib/paseo-plugin-devkit/issues.