Skip to content

Commit 77a8beb

Browse files
zxch3nclaude
andcommitted
docs: add warning about DOMContentLoaded timing issue with Vite
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>
1 parent ed7fbb8 commit 77a8beb

1 file changed

Lines changed: 41 additions & 0 deletions

File tree

pages/docs/tutorial/get_started.md

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,47 @@ export default defineConfig({
4444
});
4545
```
4646

47+
<details>
48+
<summary>⚠️ Important: Module Loading Timing in Vite</summary>
49+
50+
When using Loro with Vite, be aware of module loading timing issues with DOM events:
51+
52+
**Problem:** The following code will cause nothing to load on the screen:
53+
54+
```ts
55+
import { LoroDoc } from 'loro-crdt';
56+
57+
document.addEventListener("DOMContentLoaded", () => {
58+
const doc = new LoroDoc();
59+
// Your code here...
60+
});
61+
```
62+
63+
**Reason:** This occurs because Vite loads ES modules asynchronously, and the WASM module initialization within `loro-crdt` also happens asynchronously. When you import at the top level but execute code inside `DOMContentLoaded`, the WASM module may not be fully initialized when the event fires, causing the application to fail silently.
64+
65+
**Solutions:**
66+
67+
1. **Remove the event listener** (recommended for most cases):
68+
```ts
69+
import { LoroDoc } from 'loro-crdt';
70+
71+
const doc = new LoroDoc();
72+
// Your code here...
73+
```
74+
75+
2. **Use dynamic import inside the event listener**:
76+
```ts
77+
document.addEventListener("DOMContentLoaded", async () => {
78+
const { LoroDoc } = await import('loro-crdt');
79+
const doc = new LoroDoc();
80+
// Your code here...
81+
});
82+
```
83+
84+
The dynamic import ensures the module and its WASM dependencies are fully loaded before use.
85+
86+
</details>
87+
4788
If you're using `Next.js`, you should add the following to your next.config.js:
4889

4990
```js no-run

0 commit comments

Comments
 (0)