use-dom

Overview of use-dom skill

What the use-dom skill helps you do

The use-dom skill shows how to use Expo DOM components so React web code can run inside an Expo app on native via a webview, while still rendering normally on web. The real job-to-be-done is not “learn a feature” in isolation—it is deciding whether a web-first component, library, or layout can be shipped in your app without a full React Native rewrite.

Who should use the use-dom skill

This use-dom skill is best for frontend developers who:

• already have React web components they want to reuse in Expo
• need browser-only libraries such as charting, editors, syntax highlighting, embeds, or iframe-based UI
• are migrating a web app to native incrementally
• need DOM and CSS capabilities that React Native does not expose directly

If your UI is simple and performance-sensitive, this is usually not the best fit.

What makes use-dom different from a generic Expo prompt

A generic prompt may suggest “just use a WebView” or “port it to React Native.” The use-dom guide is more specific: it centers the Expo DOM component model, the 'use dom'; file directive, and the fit boundaries that matter most before installation—especially performance tradeoffs, unsupported route placement, and when web code can be reused verbatim.

What users usually care about first

Most users evaluating use-dom want answers to four questions:

1. Can I keep my existing web component mostly unchanged?
2. Will my target library work if it depends on the DOM?
3. What are the performance and UX tradeoffs on native?
4. When should I stop and build a native component instead?

The skill is strongest when those questions are your bottleneck, not when you need advanced native integration.

Best-fit and poor-fit scenarios

Good fits for use-dom for Frontend Development include:

• recharts, chart.js, rich text editors, syntax highlighters
• HTML/CSS-heavy components
• iframe-based embeds
• canvas or WebGL code that expects browser APIs

Poor fits include:

• basic app UI that React Native can render directly
• screens where native performance is critical
• components that need deep platform API integration
• _layout route files, which should not be DOM components

How to Use use-dom skill

Install the use-dom skill

Install from the Expo skills repository:

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

This gives your agent or workflow a reusable use-dom install and implementation reference instead of relying on a one-off prompt.

Read this file first

Start with:

• SKILL.md

For this skill, nearly all of the useful guidance is concentrated there. You do not need to hunt through a large support tree before deciding whether to adopt it.

Understand the core mechanism

The use-dom usage model is simple but important: create a component file with the 'use dom'; directive at the top. That marks the component as DOM-based. On web, it renders normally. On native, it runs in a webview context.

That means the main question is not syntax—it is whether your component truly needs browser APIs enough to justify the webview boundary.

Know what input the skill needs from you

To get useful output from the use-dom skill, provide:

• the component or library you want to use
• whether it already works on React web
• whether it depends on DOM APIs, canvas, iframes, or advanced CSS
• where it will live in your Expo app
• whether performance is a hard requirement
• whether you need native modules or deep device integration

Without that context, recommendations will be too generic to trust.

Turn a rough goal into a strong prompt

Weak prompt:

• “Help me use use-dom.”

Strong 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.”

Why this works:

• names the actual library
• confirms web compatibility
• describes data flow
• surfaces interactivity needs
• asks for tradeoff guidance, not just code

Basic use-dom implementation pattern

A typical use-dom guide flow looks like this:

1. Identify a web component that already works in React web.
2. Create a component file with 'use dom';.
3. Keep the DOM-dependent rendering inside that component.
4. Pass serializable, well-defined props from the Expo side.
5. Test behavior on both web and native, especially sizing and interaction.

The source example shows the DOM component accepting regular props plus dom: import("expo/dom").DOMProps, which is a useful signpost when shaping your component interface.

Start with a narrow component, not a whole screen

Adoption is usually smoother if you move one isolated widget first:

• a chart
• a code viewer
• a rich text block
• an embed

Do not begin by wrapping broad app structure or navigation. The repository explicitly calls out layout route constraints, so a small leaf component is the safer first win.

Decide early if webview overhead is acceptable

This is the biggest install-decision factor. use-dom is attractive because it avoids a rewrite, but the tradeoff is native webview overhead. If the component appears in a performance-critical path, renders large volumes of content, or must feel fully native, test that before committing.

For simple UI, React Native is usually the better long-term choice.

Repository-reading path for faster decisions

For this skill, use this reading order:

1. SKILL.md section “What are DOM Components?”
2. SKILL.md section “When to Use DOM Components”
3. SKILL.md section “When NOT to Use DOM Components”
4. SKILL.md example under “Basic DOM Component”

That sequence gets you fit, constraints, and implementation shape with minimal overhead.

Practical prompt template for use-dom usage

Use a prompt like this when asking an agent to apply the skill:

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

This structure leads to much better output than asking for “migration help” in the abstract.

Common adoption blockers to check before coding

Before you implement, confirm:

• the target library truly requires a DOM/browser environment
• the component is not intended for a _layout route
• you do not need deep native APIs inside the DOM-rendered part
• your team accepts the native/web behavior split
• the component is worth reusing instead of rewriting

These checks save time because they target the specific misfit cases surfaced by the skill.

use-dom skill FAQ

Is use-dom better than a normal prompt?

Usually yes, if your problem is specifically “can this web component run in Expo without a rewrite?” A normal prompt may suggest multiple unrelated approaches. The use-dom skill narrows the decision to Expo DOM components and gives fit boundaries that reduce trial-and-error.

Is use-dom only for migrations?

No. Migration is a major use case, but not the only one. use-dom also fits net-new Expo apps when you need browser-only libraries, iframe-based content, advanced CSS behavior, canvas, or WebGL that React Native does not provide directly.

When should I avoid the use-dom skill?

Skip use-dom when:

• your UI is simple enough for React Native
• performance is highly sensitive
• you need strong native feel and integration
• the component belongs in _layout
• a native or cross-platform library already solves the problem cleanly

Is use-dom beginner-friendly?

Moderately. The idea is straightforward, but the decision quality depends on understanding web-vs-native tradeoffs. Beginners can use it successfully if they start with one isolated component and test on device early.

Does use-dom replace React Native components?

No. It is a targeted escape hatch, not a default UI strategy. The best use of use-dom for Frontend Development is selective reuse of browser-dependent code, not rebuilding an entire app inside DOM components.

What kinds of libraries are the best fit?

The strongest candidates are libraries that assume a browser environment, such as:

• charting libraries
• syntax highlighting libraries
• rich text editors
• iframe/embed-based widgets
• DOM-heavy visualization tools

If the library already has a solid React Native equivalent, compare that first.

How to Improve use-dom skill

Give the agent a component-level target

The fastest way to improve use-dom results is to define one concrete component, not a vague migration goal. Name the file, library, props, and screen location. That lets the agent reason about whether the DOM boundary is acceptable.

Describe browser dependencies explicitly

Do not just say “this is a web component.” Say what makes it web-specific:

• window or document
• canvas rendering
• iframe embeds
• CSS layout requirements
• third-party packages that assume the DOM

This directly improves fit assessment because the skill is built around those constraints.

Include performance expectations up front

Many weak use-dom guide outcomes come from discovering too late that the component sits in a critical interaction path. State whether the component is:

• above the fold
• frequently rerendered
• scroll-heavy
• interactive
• acceptable inside a webview

That changes the recommendation materially.

Ask for a go or no-go decision, not just code

A better prompt is:

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

Not just:

• “Write the component.”

This improves the skill’s value because one of its main strengths is boundary-setting: when to use DOM components and when not to.

Request a prop design review

The source pattern suggests passing props into a DOM component cleanly. Ask the agent to review:

• which props should cross the boundary
• whether data should be simplified first
• whether callbacks are minimal and necessary
• which values may cause avoidable complexity

Clear inputs usually matter more than clever implementation.

Iterate after the first output

After the first draft, refine with targeted follow-ups:

• “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?”

These questions improve adoption quality more than asking for a larger code sample.

Watch for common failure modes

Common use-dom usage mistakes include:

• using it for basic UI that should stay native
• trying to place DOM components in unsupported layout routes
• underestimating webview overhead
• moving too much of a screen into the DOM layer
• skipping device testing because the web version already works

If you see one of those patterns, narrow the scope before continuing.

Improve trust by testing the right thing first

Your first test should not be visual parity alone. Check:

• render correctness on native
• sizing and container behavior
• input and interaction behavior
• data updates
• perceived performance on target devices

That is the quickest way to validate whether use-dom install is worth keeping in your stack.