Skip to content
Merged
Show file tree
Hide file tree
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
4 changes: 4 additions & 0 deletions docs/build/sdk/typescript-compat/migration-overview.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,10 @@ This guide explains how to migrate your Nitrolite dApp from the v0.5.3 SDK to th

A direct migration from v0.5.3 to v1.0.0 touches **20+ files** per app with deep, scattered rewrites. The compat layer reduces this to **~5 file changes** per app.

:::tip Automate with Codemod
Before migrating manually, try the [yellow-sdk-codemod](https://github.com/layer-3/yellow-sdk-codemod). It rewrites imports, renames auth fields, migrates client constructors, updates `package.json`, and flags RPC patterns with `// TODO [codemod]` comments for the remaining manual steps.
:::

## Installation

```bash
Expand Down
21 changes: 21 additions & 0 deletions docs/build/sdk/typescript-compat/overview.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,27 @@ sidebar_position: 1

Compatibility layer that bridges the Nitrolite SDK **v0.5.3 API** to the **v1.0.0 runtime**, letting existing dApps upgrade to the new protocol with minimal code changes.

<details>
<summary><strong>Already integrated with <code>@erc7824/nitrolite</code> or <code>@layer-3/nitrolite</code>?</strong></summary>

If your app is already built on `@erc7824/nitrolite` (v0.4 through v0.5.3) or `@layer-3/nitrolite`, you can speed up the migration using the [yellow-sdk-codemod](https://github.com/layer-3/yellow-sdk-codemod) tool. It handles the repetitive parts of the upgrade automatically: rewriting imports, migrating client constructors, renaming auth fields, and updating your `package.json`. Where the change requires context (collapsing RPC call chains, removing manual WebSocket setup), the codemod leaves a `// TODO [codemod]` comment with the exact replacement so you know what to do.

```bash
# Clone the codemod and install its dependencies
git clone https://github.com/layer-3/yellow-sdk-codemod.git
cd yellow-sdk-codemod && npm install

# Scan your project to see what needs changing (no files are modified)
npx tsx src/cli.ts scan --path /path/to/your-app/src

# Apply all transforms and update dependencies
npx tsx src/cli.ts run --path /path/to/your-app --update-deps
```

After running, search for `TODO [codemod]` in your codebase and work through the remaining items. See the [codemod README](https://github.com/layer-3/yellow-sdk-codemod#readme) for the full list of transforms and CLI options.

</details>

## Why Use the Compat Layer

The v1.0.0 protocol introduces breaking changes across 14 dimensions — wire format, authentication, WebSocket lifecycle, unit system, asset resolution, and more. A direct migration touches 20+ files per app with deep, scattered rewrites.
Expand Down
33 changes: 1 addition & 32 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading