reactlynx-best-practices

ReactLynx のベストプラクティス

このスキルは、ReactLynx のコードを書いたり、レビューしたり、リファクタリングしたりするときに使用します。ReactLynx は React のプログラミングモデルに従いますが、Lynx のデュアルスレッドランタイムは、副作用、ライフサイクルのタイミング、イベントハンドラー、メインスレッドスクリプトの考え方を変えます。

このスキルは、実行時に @ast-grep/napi やネイティブパーサーを必要としません。同梱のスキャナーは、よくある問題に対する軽量なヒューリスティックヘルパーです。エージェントは依然としてコードを読み、rules/*.md のルールドキュメントを適用する必要があります。

適用するとき

• 新しい ReactLynx コンポーネントやアプリケーションコードを書くとき。
• 再利用可能な ReactLynx コンポーネントライブラリを公開またはレビューするとき。
• スレッド境界、ライフサイクル、イベント、lynx.__globalProps、コード分割、パフォーマンスの問題について ReactLynx コードをレビューするとき。
• lynx.getJSModule、NativeModules、runOnMainThread、runOnBackground、lazy、Suspense、useLayoutEffect を呼び出すコードをリファクタリングするとき。
• ReactLynx のレンダー、diff、コミット、パッチ、setState イベントを含むパフォーマンストレースを調査するとき。

公式リファレンス

• Thinking in ReactLynx: https://lynxjs.org/next/react/thinking-in-reactlynx.html
• レンダリングプロセスとライフサイクル: https://lynxjs.org/next/react/lifecycle.html
• メインスレッドスクリプト: https://lynxjs.org/next/react/main-thread-script.html
• コード分割: https://lynxjs.org/next/react/code-splitting.html
• パフォーマンスプロファイリング: 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 と保持された JSX: https://rslib.rs/guide/solution/react
• TypeScript の JSX emit モード: https://www.typescriptlang.org/docs/handbook/jsx
• ReactLynx 0.121.0 の React.createElement サポート: https://github.com/lynx-family/lynx-stack/blob/main/packages/react/CHANGELOG.md#01210

ワークフロー

1. タスクを分類する

次のいずれかのモードを使用します:

モード	使用するとき
writing	ユーザーが新しい ReactLynx コードやベストプラクティスのガイダンスを求めたとき
review	ユーザーが既存のコードを確認、監査、説明、検証してほしいと求めたとき
refactor	ユーザーが既存のコードを修正または書き直してほしいと求めたとき

モードが明示されていない場合は、ユーザーの言い回しから推測します。コードがまだ調査されていない場合は、refactor より review を優先します。

2. コードを調査する

リポジトリでの作業では、編集する前に検索します:

rg "lynx.getJSModule|NativeModules|useLayoutEffect|main-thread:|runOnMainThread|runOnBackground|lazy\\(|Suspense|background only|globalPropsMode|__globalProps|jsx|exports" <target>

変更を加える前に、近くのコンポーネント、カスタムフック、イベントハンドラーを転送するカスタムコンポーネント、Rspeedy の設定、パフォーマンス関連のコードを読みます。

3. ソースが利用可能なときはヘルパースキャナーを実行する

スキャナーは、よくあるバックグラウンド専用の問題やライフサイクルの問題を検出します。これは完全なパーサーではなく、コードレビューの代わりにはなりません。

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. ルールチェックリストを適用する

常にスキャナーの出力と以下の手動チェックを組み合わせてください：

• デュアルスレッドの境界：レンダーコードはメインスレッドで実行される場合があります。副作用とネイティブ API はバックグラウンド専用でなければなりません。
• バックグラウンド専用の伝播：バックグラウンド専用コードからのみ呼び出されるコードはバックグラウンド専用ですが、カスタムプロップやカスタムフックの境界では明示的な 'background only' ディレクティブが必要になることがよくあります。
• ライフサイクル：useLayoutEffect はサポートされていません。バックグラウンドの副作用には useEffect を、レイアウトの読み取りにはメインスレッドのレイアウトイベント/ref を使用してください。
• イベント：通常の bind*/catch* ハンドラーはバックグラウンドスレッドで実行されます。main-thread:* ハンドラーには 'main thread' が必要で、より厳しい制限があります。
• MTS：キャプチャされた値は JSON シリアライズ可能でなければならず、キャプチャされた変数は変更できず、ネストされたメインスレッド関数はサポートされておらず、スレッド間呼び出しには runOnMainThread() または runOnBackground() を使用する必要があります。
• 共有モジュール：ヘルパーのインポートには with { runtime: 'shared' } をコード共有のみに使用し、状態の共有には使用しないでください。
• コンポーネントライブラリ：型消去された dist ESM を公開し、作成された JSX は JSX を含む .jsx ファイルに保持し、対応する宣言を提供してください。ビルドが出力する実際の .js または .jsx エントリをエクスポートしてください。TS/TSX ソースは、明示的なソースフィールドまたはサポートされている条件を通じてのみ公開してください。Rslib、TypeScript、Babel、SWC の出力で、クラシック、自動、カスタムファクトリの JSX 低下を確認してください。意図的な React.createElement は、すべての呼び出しが互換性がないと仮定するのではなく、@lynx-js/react のピア範囲に従って扱ってください。
• lynx.__globalProps：updateGlobalProps を通じて更新される、ホストが注入するクロスページ/グローバルデータ。
• globalPropsMode：'reactive' はルートの forceUpdate をトリガーします。'event' は useGlobalPropsChanged による明示的な更新が必要です。'event' に移行する際は、ルートの forceUpdate が適用されなくなるため、直接の lynx.__globalProps 読み取りをスキャンしてください。
• コード分割：遅延コンポーネントにはデフォルトエクスポート、Suspense、CSS スコープの認識、および重要な境界に対するエラー処理が必要です。
• プロファイリング：最適化の前に、トレースイベントと読み取り可能な displayName 値を使用して、ホットなレンダー/差分/更新パスを特定してください。

5. 安全にリファクタリングする

リファクターモードの場合：

1. まず現在の調査結果を報告します。
2. どの修正が機械的で、どの修正が人間の設計判断を必要とするかを説明します。
3. スコープされた変更のみを適用します。
4. 編集後にヘルパースキャナーまたはパッケージテストを再実行します。

自動修正は提案としてのみ使用してください。現在の自動修正は detect-background-only 診断用に設計されており、適用する前にレビューする必要があります。

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));
}
"

ルール

ルール	影響度	用途
detect-background-only	CRITICAL	lynx.getJSModule、NativeModules、'background only'、カスタムイベント/フックの境界
avoid-use-layout-effect	MEDIUM	ライフサイクルとレイアウトの読み取り
proper-event-handlers	MEDIUM	bindtap、catchtap、伝播、dataset、カスタムプロップハンドラー
main-thread-scripts-guide	MEDIUM	main-thread:*、useMainThreadRef、スレッド間呼び出し、共有モジュール
component-library-packaging	HIGH	ReactLynx コンポーネントライブラリのエクスポート、型消去された ESM、保持された JSX、Rslib、tsc
global-props-mode	MEDIUM	globalPropsMode 設定、直接の lynx.__globalProps 読み取り、useGlobalPropsChanged への移行
code-splitting	MEDIUM	lazy、Suspense、スタンドアロンの遅延バンドル、CSS バンドルスコープ
performance-profiling	MEDIUM	ReactLynx トレースイベント、フロー ID、displayName
hoist-static-jsx	LOW	静的 JSX とレンダーコスト

API リファレンス

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[] };
}