A health check for your Lynx project.
Find threading, API, and build issues. Get fix suggestions and repair prompts for your agent.
Documentation · Quickstart · Examples · Contributing · 中文
Check your code → |
Work with an agent → |
Check pull requests → |
Requires Node.js 22.12 or later. Run a scan from your Lynx project root:
npx lynx-doctor@latestScan only changed files:
npx lynx-doctor@latest --diffGenerate a prompt with source locations, fix suggestions, and verification commands:
npx lynx-doctor@latest --diff --agent-promptIf you have a local coding agent set up, pass the prompt to it directly:
npx lynx-doctor@latest --diff --agent codexWhen a scan finds issues in an interactive terminal, you can also choose an agent from the menu. See the agent guide for details.
Successful handoffs are verified by Doctor; the new report determines the exit status. Staged checks still require reviewed fixes to be staged. Handoffs use text output; run JSON/score modes separately.
Run this once in your project:
npx lynx-doctor@latest installThis adds a doctor script, a GitHub Actions workflow, and .agents/lynx-doctor.md with instructions for coding agents. The default workflow checks changed files on pull requests and fails on errors or warnings. See CI setup to adjust that behavior.
The installer pins the running version in an executable npx script, preserves existing setup, and places monorepo workflows at the Git root. Preview changes with install --dry-run.
| Area | Examples |
|---|---|
reactlynx |
Thread boundaries, lifecycle hooks, main-thread handlers, globalPropsMode, lazy loading, TypeScript setup, native element contracts, and component library entries |
lynx-ui |
Component imports, supported props, and gesture configuration |
rspeedy |
Bundle-size risks such as re-exporting every module with export * and using eval() |
lynx-css |
CSS property/feature support by rendering backend and minimum Lynx engine version |
List rules:
npx lynx-doctor@latest rules listExplain one rule:
npx lynx-doctor@latest rules explain reactlynx/background-only-apiCLI options, configuration, and Node API
lynx-doctor [directory] [options]| Option | Description |
|---|---|
--verbose |
Show every diagnostic with source context, docs, and skill source |
--json |
Output a structured scan report |
--score |
Print only the numeric health score |
--diff [base] |
Scan files changed against a base ref |
--staged |
Read source from the Git index |
--package |
Check existing component library runtime/declaration entry files after building |
--category <category> |
Show one category, repeatable: reactlynx, lynx-ui, rspeedy, or lynx-css |
--no-warnings |
Hide warning-severity diagnostics |
--blocking <level> |
Fail threshold: error, warning, or none |
--agent-prompt |
Print a focused agent repair prompt |
--agent [command] |
Launch an agent and verify its changes; defaults to configured command or Codex |
--no-agent-select |
Disable the interactive agent selection prompt |
See the CLI reference for command details.
Create lynx-doctor.config.ts, lynx-doctor.config.mjs, or lynx-doctor.config.json in the project root.
import { defineConfig } from "lynx-doctor";
export default defineConfig({
targets: { android: "3.5", ios: "3.6" },
ignore: {
files: ["src/generated/**"]
},
rules: {
"reactlynx/lazy-without-suspense": "warning"
},
categories: {
"lynx-ui": "off"
},
agent: {
command: "codex"
}
});targets uses Lynx engine versions, independently of the ReactLynx npm version. CSS checks are opt-in and leave missing data unknown. Reports expose scope, cssCoverage, and notices; a numeric score is not a coverage guarantee. agent.command is used only with explicit bare --agent.
import { buildAgentPrompt, formatReport, scanProject } from "lynx-doctor";
const report = await scanProject({
directory: process.cwd(),
diff: true,
blocking: "warning"
});
console.log(formatReport(report, { verbose: true }));
console.log(buildAgentPrompt(report));The repository includes standalone Lynx projects under examples/.
| Project | Purpose |
|---|---|
| healthy-shop | A passing example with a score of 100/100 |
| threading-regressions | Intentional threading, lifecycle, and event errors |
| event-mode-settings | Configuration and lazy-loading warnings |
See CONTRIBUTING.md for local development, docs, and example validation.



