ReactLynx Best Practices
Use this skill when writing, reviewing, or refactoring ReactLynx code. ReactLynx follows the React programming model, but Lynx's dual-thread runtime changes how side effects, lifecycle timing, event handlers, and main-thread scripts should be reasoned about.
This skill intentionally does not require @ast-grep/napi or any native parser at runtime. The bundled scanner is a lightweight heuristic helper for common issues. The agent must still read the code and apply the rule documents in rules/*.md.
When to Apply
- Writing new ReactLynx components or application code.
- Publishing or reviewing reusable ReactLynx component libraries.
- Reviewing ReactLynx code for thread-boundary, lifecycle, event, lynx.__globalProps, code-splitting, or performance issues.
- Refactoring code that calls
lynx.getJSModule, NativeModules, runOnMainThread, runOnBackground, lazy, Suspense, or useLayoutEffect.
- Investigating performance traces that include ReactLynx render, diff, commit, patch, or setState events.
Official References
Workflow
1. Classify the task
Use one of these modes:
| Mode |
Use when |
writing |
The user asks for new ReactLynx code or best-practice guidance |
review |
The user asks to check, audit, explain, or validate existing code |
refactor |
The user asks to fix or rewrite existing code |
If the mode is not explicit, infer it from the user's wording. Prefer review before refactor when code has not been inspected yet.
2. Inspect the code
For repository work, search before editing:
rg "lynx.getJSModule|NativeModules|useLayoutEffect|main-thread:|runOnMainThread|runOnBackground|lazy\\(|Suspense|background only|globalPropsMode|__globalProps|jsx|exports" <target>
Read nearby components, custom hooks, custom components that forward event handlers, Rspeedy config, and performance-related code before making changes.
3. Run the helper scanner when source is available
The scanner catches common background-only and lifecycle issues. It is not a complete parser and must not replace code review.
node -e "
import fs from 'fs';
import { ReactLynxWorkflow, formatScanReport } from '<path_to_skill>/scripts/index.mjs';
const input = '<sourceCodeOrFilePath>';
const sourceCode = fs.existsSync(input) ? fs.readFileSync(input, 'utf-8') : input;
const workflow = new ReactLynxWorkflow('review');
const summary = workflow.reviewCode(sourceCode);
console.log(formatScanReport(summary));
"
4. Apply the rule checklist
Always combine scanner output with these manual checks:
- Dual-thread boundaries: render code may run on the main thread; side effects and native APIs must be background-only.
- Background-only propagation: code called only from background-only code is background-only, but custom prop and custom hook boundaries often need an explicit
'background only' directive.
- Lifecycle:
useLayoutEffect is unsupported; use useEffect for background side effects or main-thread layout events/refs for layout reads.
- Events: normal
bind*/catch* handlers run on the background thread; main-thread:* handlers require 'main thread' and have stricter limitations.
- MTS: captured values must be JSON-serializable, captured variables cannot be modified, nested main-thread functions are unsupported, and cross-thread calls must use
runOnMainThread() or runOnBackground().
- Shared modules: import helpers with
with { runtime: 'shared' } only for code sharing, not state sharing.
- Component libraries: publish type-erased
dist ESM with authored JSX preserved in JSX-bearing .jsx files and matching declarations; export the actual .js or .jsx entry that the build emits. Expose TS/TSX source only through an explicit source field or supported condition. Check Rslib, TypeScript, Babel, and SWC output for classic, automatic, or custom-factory JSX lowering. Treat intentional React.createElement according to the @lynx-js/react peer range instead of assuming every call is incompatible.
lynx.__globalProps: Host-injected cross-page/global data updated through updateGlobalProps.
globalPropsMode: 'reactive' triggers root forceUpdate; 'event' requires explicit updates with useGlobalPropsChanged. When migrating to 'event', scan direct lynx.__globalProps reads because root forceUpdate no longer applies.
- Code splitting: lazy components need default exports,
Suspense, CSS scope awareness, and error handling for important boundaries.
- Profiling: use trace events and readable
displayName values to identify hot render/diff/update paths before optimizing.
5. Refactor safely
For refactor mode:
- Report current findings first.
- Explain which fixes are mechanical and which require human design judgment.
- Apply only scoped changes.
- Re-run the helper scanner or package tests after edits.
Use auto-fixes only as suggestions. The current auto-fixes are designed for detect-background-only diagnostics and should be reviewed before applying.
node -e "
import fs from 'fs';
import { ReactLynxWorkflow, formatFixPlan } from '<path_to_skill>/scripts/index.mjs';
const input = '<sourceCodeOrFilePath>';
const sourceCode = fs.existsSync(input) ? fs.readFileSync(input, 'utf-8') : input;
const workflow = new ReactLynxWorkflow('refactor');
workflow.reviewCode(sourceCode);
const plan = workflow.generateFixPlan();
if (plan) {
console.log(formatFixPlan(plan));
}
"
Rules
| Rule |
Impact |
Use for |
| detect-background-only |
CRITICAL |
lynx.getJSModule, NativeModules, 'background only', custom event/hook boundaries |
| avoid-use-layout-effect |
MEDIUM |
Lifecycle and layout reads |
| proper-event-handlers |
MEDIUM |
bindtap, catchtap, propagation, dataset, custom prop handlers |
| main-thread-scripts-guide |
MEDIUM |
main-thread:*, useMainThreadRef, cross-thread calls, shared modules |
| component-library-packaging |
HIGH |
ReactLynx component-library exports, type-erased ESM, preserved JSX, Rslib, tsc |
| global-props-mode |
MEDIUM |
globalPropsMode config, direct lynx.__globalProps reads, useGlobalPropsChanged migration |
| code-splitting |
MEDIUM |
lazy, Suspense, standalone lazy bundles, CSS bundle scope |
| performance-profiling |
MEDIUM |
ReactLynx trace events, flow IDs, displayName |
| hoist-static-jsx |
LOW |
Static JSX and render cost |
API Reference
function runSkill(source: string): Diagnostic[];
function runSkillWithFixes(source: string): DiagnosticWithFix[];
function analyzeBackgroundOnlyUsage(source: string): Diagnostic[];
function analyzeLifecycleUsage(source: string): Diagnostic[];
function generateFixes(source: string, diagnostic: Diagnostic): Fix[];
function applyFix(source: string, fix: Fix): string;
function applyFixes(source: string, fixes: Fix[]): string;
function formatScanReport(summary: ScanSummary): string;
function formatFixPlan(plan: FixPlan): string;
class ReactLynxWorkflow {
constructor(mode: WorkflowMode);
reviewCode(source: string): ScanSummary;
generateFixPlan(): FixPlan | null;
applyAutoFixes(source: string): { fixed: string; appliedFixes: Fix[] };
}
1---
2name: reactlynx-best-practices
3description: Reviews, writes, and refactors ReactLynx code and component libraries for Lynx dual-thread best practices. Applies when writing ReactLynx components, or handling background-only, useLayoutEffect, bindtap/catchtap, main-thread:*, runOnMainThread/runOnBackground, lazy/Suspense, globalPropsMode/__globalProps, component-library publishing (preserved JSX vs React.createElement), or render/diff/commit performance traces. Excludes vanilla Lynx Element PAPI without ReactLynx JSX (use vanilla-lynx), running-app debugging via DevTool/CDP (use lynx-devtool), or Rspeedy/tsconfig config (use lynx-typescript).
4metadata:
5 source: https://skillmd.com/skills/lynx-community/reactlynx-best-practices
6---
7
8# ReactLynx Best Practices
9
10Use this skill when writing, reviewing, or refactoring ReactLynx code. ReactLynx follows the React programming model, but Lynx's dual-thread runtime changes how side effects, lifecycle timing, event handlers, and main-thread scripts should be reasoned about.
11
12This skill intentionally does not require `@ast-grep/napi` or any native parser at runtime. The bundled scanner is a lightweight heuristic helper for common issues. The agent must still read the code and apply the rule documents in `rules/*.md`.
13
14## When to Apply
15
16- Writing new ReactLynx components or application code.
17- Publishing or reviewing reusable ReactLynx component libraries.
18- Reviewing ReactLynx code for thread-boundary, lifecycle, event, lynx.__globalProps, code-splitting, or performance issues.
19- Refactoring code that calls `lynx.getJSModule`, `NativeModules`, `runOnMainThread`, `runOnBackground`, `lazy`, `Suspense`, or `useLayoutEffect`.
20- Investigating performance traces that include ReactLynx render, diff, commit, patch, or setState events.
21
22## Official References
23
24- Thinking in ReactLynx: https://lynxjs.org/next/react/thinking-in-reactlynx.html
25- Rendering Process and Lifecycle: https://lynxjs.org/next/react/lifecycle.html
26- Main Thread Script: https://lynxjs.org/next/react/main-thread-script.html
27- Code Splitting: https://lynxjs.org/next/react/code-splitting.html
28- Performance Profiling: https://lynxjs.org/next/react/performance/profiling
29- lynx.__globalProps: https://lynxjs.org/next/api/lynx-api/lynx/lynx-global-props.html
30- globalPropsMode: https://lynxjs.org/next/zh/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.globalpropsmode.html
31- Rslib React and preserved JSX: https://rslib.rs/guide/solution/react
32- TypeScript JSX emit modes: https://www.typescriptlang.org/docs/handbook/jsx
33- ReactLynx 0.121.0 `React.createElement` support: https://github.com/lynx-family/lynx-stack/blob/main/packages/react/CHANGELOG.md#01210
34
35## Workflow
36
37### 1. Classify the task
38
39Use one of these modes:
40
41| Mode | Use when |
42|------|----------|
43| `writing` | The user asks for new ReactLynx code or best-practice guidance |
44| `review` | The user asks to check, audit, explain, or validate existing code |
45| `refactor` | The user asks to fix or rewrite existing code |
46
47If the mode is not explicit, infer it from the user's wording. Prefer `review` before `refactor` when code has not been inspected yet.
48
49### 2. Inspect the code
50
51For repository work, search before editing:
52
53```bash
54rg "lynx.getJSModule|NativeModules|useLayoutEffect|main-thread:|runOnMainThread|runOnBackground|lazy\\(|Suspense|background only|globalPropsMode|__globalProps|jsx|exports" <target>
55```
56
57Read nearby components, custom hooks, custom components that forward event handlers, Rspeedy config, and performance-related code before making changes.
58
59### 3. Run the helper scanner when source is available
60
61The scanner catches common background-only and lifecycle issues. It is not a complete parser and must not replace code review.
62
63```bash
64node -e "
65import fs from 'fs';
66import { ReactLynxWorkflow, formatScanReport } from '<path_to_skill>/scripts/index.mjs';
67
68const input = '<sourceCodeOrFilePath>';
69const sourceCode = fs.existsSync(input) ? fs.readFileSync(input, 'utf-8') : input;
70const workflow = new ReactLynxWorkflow('review');
71const summary = workflow.reviewCode(sourceCode);
72console.log(formatScanReport(summary));
73"
74```
75
76### 4. Apply the rule checklist
77
78Always combine scanner output with these manual checks:
79
80- Dual-thread boundaries: render code may run on the main thread; side effects and native APIs must be background-only.
81- Background-only propagation: code called only from background-only code is background-only, but custom prop and custom hook boundaries often need an explicit `'background only'` directive.
82- Lifecycle: `useLayoutEffect` is unsupported; use `useEffect` for background side effects or main-thread layout events/refs for layout reads.
83- Events: normal `bind*`/`catch*` handlers run on the background thread; `main-thread:*` handlers require `'main thread'` and have stricter limitations.
84- MTS: captured values must be JSON-serializable, captured variables cannot be modified, nested main-thread functions are unsupported, and cross-thread calls must use `runOnMainThread()` or `runOnBackground()`.
85- Shared modules: import helpers with `with { runtime: 'shared' }` only for code sharing, not state sharing.
86- Component libraries: publish type-erased `dist` ESM with authored JSX preserved in JSX-bearing `.jsx` files and matching declarations; export the actual `.js` or `.jsx` entry that the build emits. Expose TS/TSX source only through an explicit source field or supported condition. Check Rslib, TypeScript, Babel, and SWC output for classic, automatic, or custom-factory JSX lowering. Treat intentional `React.createElement` according to the `@lynx-js/react` peer range instead of assuming every call is incompatible.
87- `lynx.__globalProps`: Host-injected cross-page/global data updated through `updateGlobalProps`.
88- `globalPropsMode`: `'reactive'` triggers root `forceUpdate`; `'event'` requires explicit updates with `useGlobalPropsChanged`. When migrating to `'event'`, scan direct `lynx.__globalProps` reads because root `forceUpdate` no longer applies.
89- Code splitting: lazy components need default exports, `Suspense`, CSS scope awareness, and error handling for important boundaries.
90- Profiling: use trace events and readable `displayName` values to identify hot render/diff/update paths before optimizing.
91
92### 5. Refactor safely
93
94For refactor mode:
95
961. Report current findings first.
972. Explain which fixes are mechanical and which require human design judgment.
983. Apply only scoped changes.
994. Re-run the helper scanner or package tests after edits.
100
101Use auto-fixes only as suggestions. The current auto-fixes are designed for `detect-background-only` diagnostics and should be reviewed before applying.
102
103```bash
104node -e "
105import fs from 'fs';
106import { ReactLynxWorkflow, formatFixPlan } from '<path_to_skill>/scripts/index.mjs';
107
108const input = '<sourceCodeOrFilePath>';
109const sourceCode = fs.existsSync(input) ? fs.readFileSync(input, 'utf-8') : input;
110const workflow = new ReactLynxWorkflow('refactor');
111workflow.reviewCode(sourceCode);
112const plan = workflow.generateFixPlan();
113
114if (plan) {
115 console.log(formatFixPlan(plan));
116}
117"
118```
119
120## Rules
121
122| Rule | Impact | Use for |
123|------|--------|---------|
124| [detect-background-only](./rules/detect-background-only.md) | CRITICAL | `lynx.getJSModule`, `NativeModules`, `'background only'`, custom event/hook boundaries |
125| [avoid-use-layout-effect](./rules/avoid-use-layout-effect.md) | MEDIUM | Lifecycle and layout reads |
126| [proper-event-handlers](./rules/proper-event-handlers.md) | MEDIUM | `bindtap`, `catchtap`, propagation, dataset, custom prop handlers |
127| [main-thread-scripts-guide](./rules/main-thread-scripts-guide.md) | MEDIUM | `main-thread:*`, `useMainThreadRef`, cross-thread calls, shared modules |
128| [component-library-packaging](./rules/component-library-packaging.md) | HIGH | ReactLynx component-library exports, type-erased ESM, preserved JSX, Rslib, `tsc` |
129| [global-props-mode](./rules/global-props-mode.md) | MEDIUM | `globalPropsMode` config, direct `lynx.__globalProps` reads, `useGlobalPropsChanged` migration |
130| [code-splitting](./rules/code-splitting.md) | MEDIUM | `lazy`, `Suspense`, standalone lazy bundles, CSS bundle scope |
131| [performance-profiling](./rules/performance-profiling.md) | MEDIUM | ReactLynx trace events, flow IDs, displayName |
132| [hoist-static-jsx](./rules/hoist-static-jsx.md) | LOW | Static JSX and render cost |
133
134## API Reference
135
136```typescript
137function runSkill(source: string): Diagnostic[];
138function runSkillWithFixes(source: string): DiagnosticWithFix[];
139function analyzeBackgroundOnlyUsage(source: string): Diagnostic[];
140function analyzeLifecycleUsage(source: string): Diagnostic[];
141function generateFixes(source: string, diagnostic: Diagnostic): Fix[];
142function applyFix(source: string, fix: Fix): string;
143function applyFixes(source: string, fixes: Fix[]): string;
144function formatScanReport(summary: ScanSummary): string;
145function formatFixPlan(plan: FixPlan): string;
146```
147
148```typescript
149class ReactLynxWorkflow {
150 constructor(mode: WorkflowMode);
151 reviewCode(source: string): ScanSummary;
152 generateFixPlan(): FixPlan | null;
153 applyAutoFixes(source: string): { fixed: string; appliedFixes: Fix[] };
154}
155```