DOM Components OTA Update Issue Demo

This project demonstrates a critical limitation with Expo's DOM Components feature: DOM components do not support Over-The-Air (OTA) updates and will fail to render after an OTA update is deployed, particularly on iOS devices.

🚨 The Problem

When using Expo's DOM Components (components marked with 'use dom' directive) in your React Native app, you'll encounter the following issues after publishing an OTA update:

• DOM components fail to render after the OTA update is applied
• CSS styles are not loaded properly
• "URL not found" errors appear on iOS devices
• The native parts of your app continue to work, but DOM components become blank or broken

📱 What This Demo Shows

This project contains:

• A Lexical rich text editor implemented as a DOM component (dom-components/hello-dom.tsx)
• CSS styles for the editor (dom-components/styles.css)
• A native React Native screen that embeds the DOM component (app/index.tsx)

Project Structure

dom-components/
├── hello-dom.tsx          # DOM component with 'use dom' directive
├── styles.css             # CSS styles for the DOM component
├── ExampleTheme.ts        # Lexical editor theme
└── plugins/
    └── ToolbarPlugin.tsx   # Editor toolbar

🔍 How to Reproduce the Issue

1. Initial Setup:

   npm install
   npx expo start

2. Test Locally:

   • The DOM component (rich text editor) works perfectly in development
   • All styles load correctly
   • Full functionality is available

3. Build and Deploy:

   # Build the app
   npx expo build:ios  # or build:android
   
   # Publish an OTA update
   npx expo publish

4. Install and Test:

   • Install the built app on a device
   • Verify the DOM component works initially
   • Trigger the OTA update
   • Observe: DOM component stops rendering after the update

📋 Expected vs Actual Behavior

✅ Expected Behavior

• DOM components should continue working after OTA updates
• CSS styles should load properly
• Rich text editor should remain functional

❌ Actual Behavior

• DOM components become blank/broken after OTA updates
• CSS files return "URL not found" errors
• Native components continue working normally
• Users see a degraded experience

🔧 Technical Details

Why This Happens

According to the official Expo documentation:

DOM components can currently only be embedded and do not support OTA updates. This functionality may be added in the future as part of React Server Components.

The Root Cause

1. Separate JavaScript Contexts: DOM components run in isolated WebView contexts
2. Asset Resolution Issues: CSS and JavaScript assets for DOM components aren't properly updated via OTA
3. File Path Mismatches: After OTA updates, the WebView can't locate the updated DOM component assets

Current Limitations

• DOM components are embedded at build time
• OTA updates only affect the main React Native bundle
• WebView assets remain tied to the original build
• No automatic reconciliation between OTA updates and DOM component assets

🛠️ Workarounds and Solutions

Immediate Workarounds

1. Avoid DOM Components for Critical Features:

   // Instead of using DOM components for essential UI
   // Use native React Native components
   import { TextInput } from 'react-native';

2. Hybrid Approach:

   // Use DOM components for non-critical features only
   // Keep essential functionality in native components
   const MyComponent = () => {
     return (
       <View>
         {/* Critical native UI */}
         <Text>Essential content</Text>
         
         {/* Optional DOM component */}
         {Platform.OS === 'web' ? <DOMComponent /> : <NativeFallback />}
       </View>
     );
   };

3. Force Full App Updates:

   • Require users to download new app versions from app stores
   • Disable OTA updates when using DOM components

Long-term Solutions

1. Wait for Official Support: Expo plans to add OTA support for DOM components in future releases

2. Migrate to Native Alternatives:

   // Replace DOM-based rich text editors with native ones
   import { RichEditor } from 'react-native-pell-rich-editor';

3. Use WebView with Remote Content:

   import { WebView } from 'react-native-webview';
   
   // Host DOM content on a web server instead of embedding
   <WebView source={{ uri: 'https://your-server.com/editor' }} />

📊 Impact Assessment

High Risk Scenarios

• Rich text editors (like this demo)
• Complex forms with custom styling
• Data visualization components
• Interactive widgets

Low Risk Scenarios

• Static content display
• Simple informational components
• Development/debugging tools

🎯 Recommendations

1. For New Projects:

   • Avoid DOM components for production apps requiring OTA updates
   • Use native React Native components whenever possible
   • Consider DOM components only for web-specific features

2. For Existing Projects:

   • Audit your DOM component usage
   • Plan migration to native alternatives
   • Implement feature flags to disable DOM components if needed

3. For Critical Applications:

   • Disable OTA updates entirely if DOM components are essential
   • Implement proper error boundaries around DOM components
   • Have native fallbacks ready

📚 References

• Expo DOM Components Documentation
• DOM Components Limitations
• React Native WebView

🤝 Contributing

This demo project serves as documentation of the current limitation. If you discover additional issues or workarounds, please contribute by:

1. Opening an issue with detailed reproduction steps
2. Submitting PRs with additional test cases
3. Sharing workarounds that have worked for your use case

---

⚠️ Important: This limitation is acknowledged by the Expo team and may be resolved in future SDK versions. Always check the latest documentation for updates.