use-dom

use-domスキルの概要

use-domスキルでできること

use-domスキルは、Expo DOM components を使って React web のコードを Expo アプリ内で native では webview 経由で動かしつつ、web では通常どおり描画する方法を示すガイドです。実際に解決したいのは、単に「機能を学ぶ」ことではありません。既存の web-first な component、library、layout を、React Native へ全面的に書き直さずに自分のアプリへ載せられるかを判断することです。

use-domスキルが向いている人

この use-dom skill は、次のようなフロントエンド開発者に最適です。

• すでにある React web component を Expo で再利用したい
• charting、editor、syntax highlighting、embed、iframe ベース UI など、ブラウザ専用 library が必要
• web app を段階的に native へ移行したい
• React Native では直接扱いにくい DOM や CSS の機能が必要

UI がシンプルで、なおかつパフォーマンスが重要な場合は、通常これが最適解にはなりません。

generic な Expo prompt と何が違うのか

generic な prompt だと、「WebView を使えばいい」「React Native に移植しよう」といった提案に寄りがちです。use-domガイドはそこをより具体化しています。中心になるのは Expo DOM component のモデル、'use dom'; の file directive、そして install 前に見極めるべき適用境界です。特に重要なのは、performance の tradeoff、対応していない route への配置、どこまで web code をそのまま再利用できるかです。

多くのユーザーが最初に気にすること

use-dom を評価するユーザーがまず知りたいのは、たいてい次の4点です。

1. 既存の web component を、ほぼそのまま維持できるか
2. DOM 依存の target library が実際に動くか
3. native での performance と UX にどんな tradeoff があるか
4. どの時点で use-dom をやめて native component を作るべきか

このスキルが特に強いのは、こうした問いがボトルネックになっているときです。高度な native integration が必要なケース向けではありません。

use-domがハマるケースと避けるべきケース

use-dom for Frontend Development が向いているのは、たとえば次のようなケースです。

• recharts、chart.js、rich text editor、syntax highlighter
• HTML/CSS 依存が強い component
• iframe ベースの embed
• browser API を前提にした canvas や WebGL の code

逆に、次のようなケースには不向きです。

• React Native でそのまま描画できる基本的な app UI
• native performance が重要な screen
• platform API との深い統合が必要な component
• DOM component にしてはいけない _layout route file

use-domスキルの使い方

use-domスキルをインストールする

Expo skills repository から install します。

npx skills add https://github.com/expo/skills --skill use-dom

これにより、単発の prompt に頼るのではなく、agent や workflow で再利用できる use-dom install と実装リファレンスを持てます。

最初に読むべきファイル

まず確認するのは次のファイルです。

• SKILL.md

このスキルでは、有用なガイダンスのほとんどがここにまとまっています。導入判断の前に大きな support tree を探し回る必要はありません。

use-domの基本メカニズムを理解する

use-dom usage の仕組みはシンプルですが重要です。component file の先頭に 'use dom'; directive を置き、その component を DOM ベースとして扱います。web では通常どおり描画され、native では webview context で動作します。

つまり、主要な論点は syntax ではありません。その component が browser API を必要とするほど、本当に webview 境界を受け入れる価値があるかです。

use-domスキルに渡すべき入力

use-dom skill から実用的な出力を得るには、少なくとも次を渡してください。

• 使いたい component または library
• それがすでに React web で動作しているか
• DOM API、canvas、iframes、advanced CSS に依存しているか
• Expo app のどこで使うか
• performance が厳しい要件かどうか
• native modules や深い device integration が必要か

この文脈がないと、提案は汎用的すぎて判断材料として弱くなります。

ざっくりした目的を強いpromptに変える

弱い prompt:

• “Help me use use-dom.”

強い prompt:

• “I have an Expo app and want to reuse a React web chart component built with recharts. It already works on web, uses responsive container sizing, and only needs passed-in data and click callbacks. Show me how to convert it into a DOM component with 'use dom';, explain prop shape expectations, and call out native performance tradeoffs.”

この prompt が有効な理由は次のとおりです。

• 実際の library 名が入っている
• web 互換性が確認できている
• data flow が説明されている
• interactivity の要件が見えている
• code だけでなく tradeoff の判断も求めている

use-domの基本実装パターン

典型的な use-dom guide の流れは次のとおりです。

1. すでに React web で動いている web component を特定する
2. 'use dom'; を付けた component file を作る
3. DOM 依存の rendering はその component 内に閉じ込める
4. Expo 側からは serializable で分かりやすい props を渡す
5. web と native の両方で、特に sizing と interaction をテストする

元の例では、DOM component が通常の props に加えて dom: import("expo/dom").DOMProps を受け取っています。component interface を設計する際の良い手がかりになります。

画面全体ではなく、小さなcomponentから始める

導入は、独立した widget を1つ移すところから始めるほうがスムーズです。

• chart
• code viewer
• rich text block
• embed

app 全体の構造や navigation を最初から包むのは避けてください。repository でも layout route の制約が明示されているため、まずは小さな leaf component で成功させるのが安全です。

webviewのオーバーヘッドを早めに許容判断する

ここが install 判断で最も重要なポイントです。use-dom の魅力は rewrite を避けられることですが、その代わり native では webview のオーバーヘッドを受け入れる必要があります。component が performance-critical な導線にある、大量の content を描画する、完全に native らしい体験が求められる――こうした条件に当てはまるなら、先にそこを検証してから採用を決めるべきです。

シンプルな UI なら、長期的には React Native のほうが適していることがほとんどです。

早く判断するためのrepository読み順

このスキルでは、次の順番で読むのが効率的です。

1. SKILL.md の “What are DOM Components?”
2. SKILL.md の “When to Use DOM Components”
3. SKILL.md の “When NOT to Use DOM Components”
4. SKILL.md の “Basic DOM Component” にある example

この順番なら、fit、制約、実装の形を最小限の手間で把握できます。

use-dom活用時の実践的なpromptテンプレート

agent にこのスキルを適用してもらうときは、次のような prompt が有効です。

Use the use-dom skill to evaluate whether this React web component should become an Expo DOM component.

Component purpose:
- [what it does]

Current library dependencies:
- [libraries]

Why React Native alone is not enough:
- [DOM APIs / CSS / iframe / canvas / WebGL]

Performance sensitivity:
- [low / medium / high]

Route placement:
- [where the component will be used]

What I need from you:
- fit assessment
- implementation outline
- example component file with 'use dom';
- risks and when not to use use-dom

抽象的に「migration help がほしい」と頼むより、この構成のほうがはるかに質の高い出力につながります。

実装前に確認したい導入のつまずきポイント

実装前に、次の点を確認してください。

• target library が本当に DOM/browser environment を必要としているか
• component を _layout route に置く想定ではないか
• DOM 側で描画する部分に deep native APIs が不要か
• team が native/web で振る舞いが分かれることを受け入れられるか
• rewrite ではなく再利用する価値が本当にあるか

これらのチェックは、このスキルが明らかにする典型的なミスマッチを先回りで潰せるため、時間の節約になります。

use-domスキル FAQ

use-domは普通のpromptより良い？

多くの場合は yes です。特に課題が「この web component を rewrite せずに Expo で動かせるか？」であるなら有効です。通常の prompt だと、複数の無関係なアプローチが並ぶことがあります。use-dom skill は判断対象を Expo DOM components に絞り、fit の境界を明確にして trial-and-error を減らしてくれます。

use-domは移行用途だけ？

いいえ。migration は主要な use case ですが、それだけではありません。use-dom は、browser 専用 library、iframe ベースの content、advanced CSS、canvas、WebGL など、React Native が直接は提供しない機能が必要な新規 Expo app にも向いています。

どんなときにuse-domスキルを避けるべき？

次のような場合は use-dom を見送るべきです。

• UI が React Native で十分に実現できる
• performance 感度が高い
• 強い native らしさや native integration が必要
• component が _layout に属する
• すでに native または cross-platform library で素直に解決できる

use-domは初心者向け？

中程度です。考え方自体はシンプルですが、判断の質は web と native の tradeoff を理解しているかに左右されます。初心者でも、独立した component を1つ選び、早い段階で device 上のテストを行えば十分使えます。

use-domはReact Native componentの代わりになる？

いいえ。これは標準の UI 戦略ではなく、必要なときのための限定的な escape hatch です。use-dom for Frontend Development の最も良い使い方は、browser 依存 code の選択的な再利用であって、app 全体を DOM components で作り直すことではありません。

どんなlibraryが特に向いている？

最も相性が良いのは、browser environment を前提にしている library です。たとえば次のようなものです。

• charting libraries
• syntax highlighting libraries
• rich text editors
• iframe/embed ベースの widget
• DOM 依存の強い visualization tool

その library に React Native の有力な代替があるなら、まずはそちらと比較してください。

use-domスキルを改善する方法

agentにはcomponent単位のターゲットを渡す

use-dom の結果を最も改善しやすいのは、曖昧な migration 目標ではなく、具体的な1つの component を定義することです。file 名、library、props、配置する screen を明記してください。そうすることで、DOM 境界を受け入れられるかどうかを agent が現実的に判断しやすくなります。

browser依存を明示的に書く

単に「これは web component です」と言うだけでは不十分です。何が web 固有なのかを具体的に書いてください。

• window や document
• canvas rendering
• iframe embeds
• CSS layout の要件
• DOM を前提にした third-party package

この情報は fit assessment を直接良くします。というのも、このスキル自体がそうした制約を軸に設計されているからです。

performance要件を最初から含める

弱い use-dom guide の結果によくあるのは、その component が重要な interaction path にあると後から判明することです。次の点を upfront で伝えてください。

• first view に出るか
• 頻繁に rerender されるか
• scroll 負荷が高いか
• interactive か
• webview 内でも許容できるか

ここが分かるだけで、recommendation は大きく変わります。

codeだけでなく、go / no-go判断を求める

より良い prompt は次のようなものです。

• “Should I use use-dom here, and why?”

単に次のように頼むのではなく:

• “Write the component.”

このほうがスキルの価値を引き出せます。というのも、このスキルの強みのひとつは境界を引くこと、つまり DOM component を使うべき場面と使うべきでない場面を判断することにあるからです。

props設計のレビューを依頼する

元のパターンでは、DOM component に clean に props を渡すことが示されています。agent には次の観点でレビューを依頼してください。

• どの props を境界越しに渡すべきか
• data は先に単純化すべきか
• callback は最小限かつ必要なものに絞れているか
• どの値が不要な複雑さを生みやすいか

凝った実装よりも、入力設計の明快さのほうが重要になることは少なくありません。

最初の出力のあとに絞り込んで改善する

最初の draft のあとには、狙いを絞った follow-up で精度を上げてください。

• “Reduce this to the minimum DOM-dependent surface.”
• “What part should remain native?”
• “What would make this too slow on native?”
• “Can you rewrite this example so the DOM component only handles the chart body?”

大きな code sample を追加で求めるより、こうした質問のほうが導入品質の改善につながります。

よくある失敗パターンに注意する

よくある use-dom usage のミスには、次のようなものがあります。

• native のままでよい基本 UI に使ってしまう
• 非対応の layout route に DOM component を置こうとする
• webview のオーバーヘッドを軽く見積もる
• screen の大部分を DOM layer に移してしまう
• web 版が動くことを理由に device テストを省く

こうした兆候が見えたら、そのまま進めずにまず適用範囲を狭めてください。

最初に検証すべきことを正しく選ぶ

最初のテストで確認すべきなのは、見た目の一致だけではありません。次をチェックしてください。

• native で正しく render されるか
• sizing と container behavior が安定しているか
• input と interaction が期待どおりか
• data update に問題なく追従するか
• target device で体感 performance が許容範囲か

これが、use-dom install を自分の stack に残す価値があるかを最短で見極める方法です。