reactlynx-best-practices

---
name: reactlynx-best-practices
description: 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).
license: Apache-2.0
---

# 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:

| 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:

```bash
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.

```bash
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:

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.

```bash
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](./rules/detect-background-only.md) | CRITICAL | `lynx.getJSModule`, `NativeModules`, `'background only'`, custom event/hook boundaries |
| [avoid-use-layout-effect](./rules/avoid-use-layout-effect.md) | MEDIUM | Lifecycle and layout reads |
| [proper-event-handlers](./rules/proper-event-handlers.md) | MEDIUM | `bindtap`, `catchtap`, propagation, dataset, custom prop handlers |
| [main-thread-scripts-guide](./rules/main-thread-scripts-guide.md) | MEDIUM | `main-thread:*`, `useMainThreadRef`, cross-thread calls, shared modules |
| [component-library-packaging](./rules/component-library-packaging.md) | HIGH | ReactLynx component-library exports, type-erased ESM, preserved JSX, Rslib, `tsc` |
| [global-props-mode](./rules/global-props-mode.md) | MEDIUM | `globalPropsMode` config, direct `lynx.__globalProps` reads, `useGlobalPropsChanged` migration |
| [code-splitting](./rules/code-splitting.md) | MEDIUM | `lazy`, `Suspense`, standalone lazy bundles, CSS bundle scope |
| [performance-profiling](./rules/performance-profiling.md) | MEDIUM | ReactLynx trace events, flow IDs, displayName |
| [hoist-static-jsx](./rules/hoist-static-jsx.md) | LOW | Static JSX and render cost |

## API Reference

```typescript
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;
```

```typescript
class ReactLynxWorkflow {
  constructor(mode: WorkflowMode);
  reviewCode(source: string): ScanSummary;
  generateFixPlan(): FixPlan | null;
  applyAutoFixes(source: string): { fixed: string; appliedFixes: Fix[] };
}
```