Skip to content

docs: add warning about DOMContentLoaded timing issue with Vite#12

Merged
zxch3n merged 1 commit intomainfrom
docs/vite-import-timing-issue
Jun 8, 2025
Merged

docs: add warning about DOMContentLoaded timing issue with Vite#12
zxch3n merged 1 commit intomainfrom
docs/vite-import-timing-issue

Conversation

@zxch3n
Copy link
Copy Markdown
Member

@zxch3n zxch3n commented Jun 8, 2025

Summary

  • Added documentation warning about using DOMContentLoaded event with Loro in Vite
  • Explained the timing conflict between DOMContentLoaded and ES module/WASM initialization
  • Provided two solutions to resolve the issue

Context

When developers use DOMContentLoaded event listener with top-level Loro imports in Vite applications, the page fails to load. This is a common pattern developers might use, but it conflicts with how Vite loads ES modules asynchronously along with Loro's WASM initialization.

Problem Details

The issue occurs because:

  1. Vite loads ES modules asynchronously
  2. Loro's WASM module also initializes asynchronously
  3. DOMContentLoaded may fire before these async operations complete
  4. This results in the application failing silently with nothing rendered on screen

Changes

Added a collapsible warning section in the Getting Started guide that:

  • Shows the problematic code pattern
  • Explains why this timing issue occurs
  • Provides two clear solutions:
    1. Remove the DOMContentLoaded listener (recommended)
    2. Use dynamic import inside the event listener

This will help developers avoid this common pitfall when integrating Loro with Vite projects.

🤖 Generated with Claude Code

@zxch3n zxch3n force-pushed the docs/vite-import-timing-issue branch from 8b888e3 to 77a8beb Compare June 8, 2025 08:24
@zxch3n zxch3n changed the title docs: add Vite module loading timing issue and solutions docs: add warning about DOMContentLoaded timing issue with Vite Jun 8, 2025
@zxch3n zxch3n force-pushed the docs/vite-import-timing-issue branch from 77a8beb to 3a087a3 Compare June 8, 2025 08:26
Add a warning section explaining why using DOMContentLoaded event with top-level Loro imports fails in Vite. The issue occurs due to the timing conflict between DOMContentLoaded and asynchronous ES module/WASM initialization. Provides two solutions: removing the event listener or using dynamic imports.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
@zxch3n zxch3n force-pushed the docs/vite-import-timing-issue branch from 3a087a3 to 260d7cf Compare June 8, 2025 08:27
@zxch3n zxch3n merged commit d28503e into main Jun 8, 2025
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant