using-reacticx

Reacticx の使用方法

概要

Reacticx は、React Native と Expo 向けのコピー＆ペースト式コンポーネントライブラリです。アニメーションとジェスチャーに対応した 163 個のコンポーネントを、ソースコードとしてプロジェクトにコピーして使用します。インストールするランタイムパッケージも、node_modules からインポートするものもありません。コンポーネントを追加したら、通常のプロジェクトコードとして自由に編集できます。

同じレジストリを利用する 2 つの入口があります。

	使用する場面
CLI — npx reacticx <command>	ターミナルを使う人がいる場合、または一度だけ追加する場合
MCP サーバー — @reacticx/mcp	エージェントが作業し、構造化された結果を必要とする場合

どちらも同じレジストリを読み取り、同じ outDir に書き込み、同じ方法でインポートを書き換えます。作業中のセッションで利用できる方を選んでください。作業の途中で両方を混在させる場合は、まず reacticx diff / diff_components で状態を再確認してください。

追加する前に

1. ファイルの配置先を確認してください。 npx reacticx config（または get_config ツール）を実行すると、すべてのデフォルト値が設定された解決済みの構成が表示されます。プロジェクトに component.config.json がない場合はデフォルトが適用されます。つまり、src/shared/components、カテゴリ別の構成、@/shared/components エイリアスが使われますが、既存のプロジェクトでは望ましくないことがほとんどです。まず reacticx init / init_config を実行してください。
2. すでに存在しないか確認してください。 reacticx list でレジストリを確認できます。list_installed_components（MCP）または outDir の内容を確認すれば、プロジェクトにすでにあるコンポーネントがわかります。--overwrite を指定して再追加すると、ローカルでの編集内容は警告なく破棄されます。
3. 接続する前にコンポーネントを読んでください。 形状を確認するには reacticx info <name>、実際のプロパティ型を確認するには get_component_types、動作する呼び出し例を確認するには get_component_example を使います。プロパティを推測することが、無駄なやり取りが発生する主な原因です。

コンポーネントの追加

npx reacticx add accordion                      # into the configured outDir
npx reacticx add accordion --dir src/components/ui   # somewhere else, once
npx reacticx add accordion --types --examples   # bring types and the demo screen
npx reacticx add accordion --dry                # show the plan, write nothing
npx reacticx add accordion --overwrite          # take the registry version

プロジェクトのパッケージマネージャーに合わせて、bunx、npx、または pnpm dlx を使用してください。

ファイルのコピー以外に add が行うこと：

• インポートを書き換えます。 レジストリのソースコードでは @/components/...、@/utils/...、@/helpers/... からインポートしています。これらは component.config.json で指定されたプロジェクト独自のエイリアスに書き換えられます。適切なエイリアスがない場合は、相対パスにフォールバックします。
• 依存関係を追従します。 別のレジストリコンポーネントや共有ヘルパーをインポートするコンポーネントは、それらも一緒に取り込みます。--no-deps を指定するとこの動作は無効になり、その場合は必要なモジュールを自分で用意するまで、コピーされたファイルをコンパイルできません。
• 既存ファイルの上書きを防ぎます。 --overwrite を指定しない限り、既存ファイルは変更されません。
• ダウンロードごとにチェックサムを検証します。
• 不足している npm パッケージを報告し、インストールを提案します。 MCP サーバーは不足パッケージを報告しますが、インストールは行いません。返されたコマンドを実行してください。

追加した後

1. 不足しているパッケージをインストールします。パッケージのバージョンをプロジェクトの Expo SDK に合わせるため、通常の npm install より npx expo install <package> を優先してください。
2. ネイティブコードが追加された場合は、ネイティブターゲットを再ビルドします（npx expo run:ios、npx expo run:android）。Metro を再起動するだけでは不十分です。追加したばかりのコンポーネントが起動時にクラッシュする原因として、これが最もよく見られます。
3. 設定済みのエイリアスからインポートします。例：import { Accordion } from "@/components/ui/molecules/accordion"。
4. 型チェックと lint を実行します。コピーしたソースコードはプロジェクトコードになったため、プロジェクト独自の基準に従います。

知っておくと役立つ依存関係の情報

• ほぼすべてのアニメーションに react-native-reanimated を使用します。40 個のコンポーネントでは react-native-worklets も必要です。Reanimated 4 で worklets が独立したパッケージに移動したため、別途インストールする必要があります。
• Skia は @shopify/react-native-skia で、45 個のコンポーネントが使用します。
• ブラーには @sbaiahmed1/react-native-blur を使用します。これはスコープ付きの npm パッケージです。スコープなしの react-native-blur は別のライブラリなので、インストールしないでください。
• アイコンはコンポーネントに応じて @expo/vector-icons、expo-symbols、または @hugeicons/react-native から取得します。

references/components.md には、コンポーネントごとの正確な依存関係が記載されています。

よくある間違い

• init を実行する前にコンポーネントを追加し、プロジェクトに存在しないエイリアスの下にある src/shared/components に配置してしまう。
• ネイティブ依存関係が追加された後、ネイティブの再ビルドを省略する。
• ローカルで編集したコンポーネントに --overwrite を指定して再追加する。まず reacticx diff <name> を実行してください。失われる内容が正確に表示されます。
• --no-deps を渡しておきながら、インポートが解決されない理由がわからず困惑する。
• スコープのない react-native-blur をインストールする。
• 似た名前のコンポーネントがあるからといって、対象のコンポーネントも存在すると決めつける。インポートを書く前に reacticx list -s <term> を実行してください。CLI は入力ミスに対して、よく似た候補を提示します。

参考資料

ファイル	内容
references/components.md	すべてのコンポーネントの CLI キー、説明、ファイル、正確な依存関係、ドキュメント URL。レジストリ、サイトのコンテンツ、コンポーネントのソースから scripts/skills/generate-catalog.ts によって生成されます
references/cli.md	すべての CLI コマンドとフラグ、およびそれぞれの動作
references/mcp.md	MCP サーバーのセットアップ、12 個すべてのツール、リソース、エージェントのワークフロー
references/configuration.md	component.config.json のすべてのキー、各キーが変更する内容、パスの解決方法