Skip to content
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 50 additions & 2 deletions pages/docs/tutorial/get_started.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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.

<details>
<summary>⚠️ DOMContentLoaded Timing Issue with Vite</summary>

Expand Down Expand Up @@ -88,6 +132,8 @@ The dynamic import ensures the module and its WASM dependencies are fully loaded

</details>

### Next.js

If you're using `Next.js`, you should add the following to your next.config.js:

```js no-run
Expand All @@ -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:

Expand Down