use-dom

use-dom skill 概覽

use-dom skill 能幫你做到什麼

use-dom skill 會示範如何使用 Expo DOM components，讓 React web 程式碼能透過 webview 在 Expo app 的原生環境中執行，同時在 web 端仍維持正常渲染。真正要解決的，不是單純「學會某個功能」，而是判斷一個以 web 為優先的元件、函式庫或版面，是否能不經完整 React Native 重寫，就直接交付到你的 app 裡。

哪些人適合使用 use-dom skill

這個 use-dom skill 特別適合以下前端開發者：

• 已經有 React web 元件，想在 Expo 裡重用
• 需要瀏覽器限定的函式庫，例如圖表、編輯器、語法高亮、嵌入內容或 iframe 型 UI
• 正在把 web app 逐步遷移到原生
• 需要 React Native 沒有直接提供的 DOM 與 CSS 能力

如果你的 UI 很單純，而且對效能非常敏感，通常就不是最適合的選擇。

use-dom 與一般 Expo 提示有什麼不同

一般提示可能只會建議你「直接用 WebView」或「改寫成 React Native」。use-dom 指南更聚焦：它以 Expo DOM component 模型、'use dom'; 檔案指示詞，以及安裝前最該先釐清的適配邊界為核心——尤其是效能取捨、不支援的 route 放置位置，以及哪些 web 程式碼可以原封不動重用。

使用者通常最先在意什麼

多數在評估 use-dom 的人，最想先得到這四個問題的答案：

1. 我現有的 web 元件能不能大致不改就沿用？
2. 如果目標函式庫依賴 DOM，它真的能運作嗎？
3. 在原生端的效能與 UX 取捨是什麼？
4. 什麼情況下應該停止使用 use-dom，改做原生元件？

當這些問題正是你的決策瓶頸時，這個 skill 特別有價值；如果你需要的是進階原生整合，它就不是最強項。

最適合與不適合的 use-dom 情境

適合 use-dom for Frontend Development 的情境包括：

• recharts、chart.js、富文本編輯器、語法高亮工具
• 高度依賴 HTML/CSS 的元件
• 以 iframe 為基礎的嵌入內容
• 預期瀏覽器 API 的 canvas 或 WebGL 程式碼

不適合的情境包括：

• React Native 本身就能直接渲染的基本 app UI
• 對原生效能要求很高的畫面
• 需要深入平台 API 整合的元件
• _layout route 檔案，這類不應做成 DOM components

如何使用 use-dom skill

安裝 use-dom skill

從 Expo skills repository 安裝：

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

這樣你的 agent 或工作流程就能拿到可重用的 use-dom install 與實作參考，而不是只依賴一次性的 prompt。

先讀這個檔案

先從這裡開始：

• SKILL.md

這個 skill 幾乎所有真正有用的指引都集中在這裡。你不需要在一大堆輔助檔案之間來回翻找，才能先判斷自己是否適合採用。

先理解 use-dom 的核心機制

use-dom usage 的模型很簡單，但非常關鍵：建立一個元件檔案，並在最上方加上 'use dom'; 指示詞。這會把該元件標記為 DOM-based。到了 web 端，它會正常渲染；到了原生端，它會在 webview 環境中執行。

也就是說，真正的重點不是語法，而是你的元件是否真的需要瀏覽器 API，需要到值得跨過 webview 這條邊界。

你需要提供哪些資訊給 use-dom skill

想讓 use-dom skill 給出真正有用的結果，請提供：

• 你想使用的元件或函式庫
• 它目前是否已經能在 React web 正常運作
• 它是否依賴 DOM APIs、canvas、iframes 或進階 CSS
• 它會放在 Expo app 的哪個位置
• 效能是否是硬性要求
• 你是否需要 native modules 或深度裝置整合

少了這些背景，建議通常都會過於籠統，可信度不高。

把模糊目標改寫成有效的 use-dom prompt

弱 prompt：

• 「Help me use use-dom.」

強 prompt：

• 「我有一個 Expo app，想重用一個用 recharts 做的 React web 圖表元件。它在 web 上已經可用，會用 responsive container sizing，而且只需要傳入資料與 click callbacks。請示範如何把它改成帶有 'use dom'; 的 DOM component，說明 prop shape 的預期，並指出在原生端的效能取捨。」

為什麼這樣更有效：

• 點出實際使用的函式庫
• 先確認 web 相容性
• 說清楚資料流
• 讓互動需求浮出來
• 要求的不只是程式碼，也包含取捨分析

基本的 use-dom 實作模式

典型的 use-dom guide 流程大致如下：

1. 找出一個已經能在 React web 正常運作的 web 元件。
2. 建立元件檔案，加入 'use dom';。
3. 把依賴 DOM 的渲染邏輯留在該元件內。
4. 從 Expo 端傳入可序列化、定義清楚的 props。
5. 同時在 web 與原生端測試行為，尤其是尺寸與互動表現。

來源範例展示了 DOM component 接收一般 props，再加上 dom: import("expo/dom").DOMProps；這是設計元件介面時很值得參考的訊號。

先從小型元件開始，不要一開始就包整個畫面

如果先搬一個獨立小元件，通常導入會順很多，例如：

• 圖表
• 程式碼檢視器
• 富文本區塊
• 嵌入內容

不要一開始就把大範圍的 app 結構或導覽包進去。repository 已經明確提醒 layout route 的限制，所以先從小型 leaf component 下手，會是比較安全的第一步。

盡早判斷 use-dom 的 webview 成本是否可接受

這是安裝決策中最重要的因素。use-dom 吸引人的地方，在於它能避免重寫；但代價就是原生端的 webview 開銷。如果元件位於效能關鍵路徑、需要渲染大量內容，或必須具備非常原生的手感，請先測試再決定是否要投入。

如果只是簡單 UI，長期來看通常還是 React Native 更合適。

透過 repository 閱讀順序加快 use-dom 判斷

對這個 skill，建議照以下順序閱讀：

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」底下的範例

照這個順序讀，能用最少成本先掌握適配性、限制條件與實作輪廓。

use-dom usage 的實用 prompt 範本

當你要請 agent 套用這個 skill，可以用下面這個 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」更容易得到高品質結果。

開始寫程式前，先檢查常見的 use-dom 導入阻礙

實作前請先確認：

• 目標函式庫是否真的需要 DOM／瀏覽器環境
• 元件是否不是要放在 _layout route
• DOM-rendered 那一段是否不需要深度原生 API
• 你的團隊是否能接受原生與 web 行為分流
• 這個元件是否真的值得重用，而不是直接重寫更划算

這些檢查很省時間，因為它們剛好對應到這個 skill 所揭示的常見不適配情況。

use-dom skill 常見問題

use-dom 會比一般 prompt 更好嗎？

通常會，前提是你的問題真的是「這個 web 元件能不能在 Expo 裡不重寫就跑起來？」一般 prompt 常會丟出多種彼此無關的方案。use-dom skill 則會把決策收斂到 Expo DOM components，並提供清楚的適配邊界，降低你試錯的成本。

use-dom 只適合拿來做 migration 嗎？

不是。遷移確實是主要使用情境之一，但不是唯一情境。當你在新的 Expo app 裡需要瀏覽器限定函式庫、iframe 型內容、進階 CSS 行為、canvas 或 WebGL，而 React Native 無法直接提供時，use-dom 一樣很適合。

什麼情況下應該避免使用 use-dom skill？

以下情況建議略過 use-dom：

• 你的 UI 用 React Native 就足夠完成
• 效能非常敏感
• 你需要更強的原生手感與整合
• 元件屬於 _layout
• 已經有原生或跨平台函式庫能把問題乾淨地解掉

use-dom 對初學者友善嗎？

算中等。概念本身不難，但決策品質很仰賴你是否理解 web 與原生之間的取捨。初學者仍然可以用得不錯，前提是先從單一、獨立的小元件開始，並且盡早在實機上測試。

use-dom 會取代 React Native components 嗎？

不會。它是有明確用途的 escape hatch，不是預設 UI 策略。use-dom for Frontend Development 最好的用法，是選擇性重用依賴瀏覽器的程式碼，而不是把整個 app 都重建在 DOM components 裡。

哪些函式庫最適合 use-dom？

最強的候選通常是那些預設就假設執行環境是瀏覽器的函式庫，例如：

• 圖表函式庫
• 語法高亮函式庫
• 富文本編輯器
• iframe／embed 類 widget
• 高度依賴 DOM 的視覺化工具

如果某個函式庫已經有成熟的 React Native 替代品，請先比較那條路。

如何改進 use-dom skill 的使用效果

給 agent 明確到元件層級的 use-dom 目標

想改善 use-dom 的輸出品質，最快的方法就是指定一個具體元件，而不是丟一個模糊的 migration 目標。請直接說出檔名、函式庫、props 與畫面位置。這樣 agent 才能判斷 DOM 邊界是否合理。

明確描述瀏覽器依賴

不要只說「這是一個 web component」。要說清楚它為什麼是 web 專屬，例如：

• window 或 document
• canvas rendering
• iframe embeds
• CSS layout requirements
• 預設依賴 DOM 的 third-party packages

這會直接提升適配判斷品質，因為這個 skill 的核心就是圍繞這些限制建立的。

一開始就交代清楚效能預期

很多不理想的 use-dom guide 結果，都是因為太晚才發現元件其實位於關鍵互動路徑。請明確說明這個元件是否：

• 位於首屏可見區域
• 會頻繁 rerender
• 捲動負載很高
• 互動性強
• 可以接受放在 webview 裡

這些條件會實質改變建議方向。

不要只要程式碼，直接要求 go / no-go 判斷

更好的問法是：

• 「這裡應不應該用 use-dom？原因是什麼？」

而不只是：

• 「幫我把元件寫出來。」

這樣能更發揮 skill 的價值，因為它的主要強項之一，就是幫你劃清邊界：什麼時候該用 DOM components，什麼時候不該用。

請 agent 一併檢查 props 設計

來源模式顯示，傳 props 進 DOM component 應該盡量保持乾淨。你可以請 agent 一起檢查：

• 哪些 props 應該跨邊界傳遞
• 資料是否應先簡化
• callbacks 是否夠少且確實必要
• 哪些值可能帶來不必要的複雜度

很多時候，清楚的輸入比花俏的實作更重要。

拿到第一版後，針對性迭代 use-dom 方案

第一版出來後，請用更聚焦的追問來修正：

• 「把 DOM 依賴面縮到最小。」
• 「哪些部分應該保留為 native？」
• 「什麼因素會讓這個在原生端太慢？」
• 「能不能改寫這個範例，讓 DOM component 只處理圖表本體？」

這類問題，通常比單純要求更大份的程式碼範例，更能提高實際導入品質。

留意 use-dom 常見失敗模式

常見的 use-dom usage 錯誤包括：

• 把它用在本來就應該維持 native 的基本 UI
• 嘗試把 DOM components 放進不支援的 layout routes
• 低估 webview 開銷
• 把整個畫面太多內容搬進 DOM layer
• 因為 web 版已經能跑，就跳過實機測試

如果你發現自己踩到這些模式，先縮小範圍，再繼續往下做。

先測對的東西，才能提升對 use-dom 的信心

第一輪測試不應該只看畫面是否長得一樣。請優先檢查：

• 原生端渲染是否正確
• 尺寸與容器行為是否正常
• 輸入與互動行為是否正常
• 資料更新是否穩定
• 在目標裝置上的體感效能

這是最快驗證 use-dom install 是否值得留在你技術棧裡的方法。