diff --git a/pages/docs/tutorial/get_started.mdx b/pages/docs/tutorial/get_started.mdx index 6bace6b..e1da4a6 100644 --- a/pages/docs/tutorial/get_started.mdx +++ b/pages/docs/tutorial/get_started.mdx @@ -35,17 +35,61 @@ pnpm install loro-crdt yarn add loro-crdt ``` -If you're using `Vite`, you should add the following to your vite.config.ts: +### Vite + +#### Vite 8.1 and newer + +[Vite 8.1 introduced built-in WebAssembly ESM integration](https://vite.dev/blog/announcing-vite8-1#wasm-esm-integration-support), +so `vite-plugin-wasm` is no longer needed. The default browser targets also +support top-level `await` (TLA), so `vite-plugin-top-level-await` is not needed. +You can import from `loro-crdt` directly. + +If you customize `build.target`, use browser targets that support TLA. Changing +the target does not add TLA support to older browsers. See +[Vite's WebAssembly guide](https://vite.dev/guide/features#webassembly). + +**Development workaround (Vite 8.1.0 with Loro 1.16.4):** This combination can +fail during WASM initialization with `Cannot read properties of undefined +(reading 'memory')` when Loro is pre-bundled. If you encounter this error, +exclude Loro from dependency pre-bundling: ```ts no-run +import { defineConfig } from "vite"; + +export default defineConfig({ + optimizeDeps: { + exclude: ["loro-crdt"], + }, +}); +``` + +Merge this setting into your existing config. It affects development only; +production builds still bundle Loro normally. + +#### Older Vite versions + +For Vite versions before 8.1, install the plugins: + +```bash +npm install -D vite-plugin-wasm vite-plugin-top-level-await +``` + +Add them alongside your existing framework plugins in `vite.config.ts`: + +```ts no-run +import { defineConfig } from "vite"; import wasm from "vite-plugin-wasm"; import topLevelAwait from "vite-plugin-top-level-await"; export default defineConfig({ - plugins: [...otherConfigures, wasm(), topLevelAwait()], + plugins: [wasm(), topLevelAwait()], }); ``` +For targets with native TLA support, the TLA plugin can be omitted; see the +[plugin's usage guide](https://github.com/Menci/vite-plugin-wasm#usage) for target +configuration and compatibility details. +
⚠️ DOMContentLoaded Timing Issue with Vite @@ -88,6 +132,8 @@ The dynamic import ensures the module and its WASM dependencies are fully loaded
+### Next.js + If you're using `Next.js`, you should add the following to your next.config.js: ```js no-run @@ -102,6 +148,8 @@ module.exports = { }; ``` +### Browser ESM + You can also use Loro directly in the browser via ESM imports. Here's a minimal example: