reactlynx-best-practices

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

• Thinking in ReactLynx: https://lynxjs.org/next/react/thinking-in-reactlynx.html
• Rendering Process and Lifecycle: https://lynxjs.org/next/react/lifecycle.html
• Main Thread Script: https://lynxjs.org/next/react/main-thread-script.html
• Code Splitting: https://lynxjs.org/next/react/code-splitting.html
• Performance Profiling: https://lynxjs.org/next/react/performance/profiling
• lynx.__globalProps: https://lynxjs.org/next/api/lynx-api/lynx/lynx-global-props.html
• globalPropsMode: https://lynxjs.org/next/zh/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.globalpropsmode.html
• Rslib React and preserved JSX: https://rslib.rs/guide/solution/react
• TypeScript JSX emit modes: https://www.typescriptlang.org/docs/handbook/jsx
• ReactLynx 0.121.0 React.createElement support: https://github.com/lynx-family/lynx-stack/blob/main/packages/react/CHANGELOG.md#01210

Workflow

1. Classify the task

Use one of these modes:

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

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:

1. Report current findings first.
2. Explain which fixes are mechanical and which require human design judgment.
3. Apply only scoped changes.
4. 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.

Rules

API Reference