From 121dfc5129626d7495794262abfbb62572cbeb4e Mon Sep 17 00:00:00 2001 From: Maharshi Mishra Date: Fri, 13 Mar 2026 15:28:08 +0530 Subject: [PATCH 1/3] docs: add yellow-sdk-codemod reference to compat SDK pages Add callout boxes linking to the codemod tool on the compat overview and migration overview pages so developers migrating from v0.5.3 can discover and use the automated migration tooling. --- .../typescript-compat/migration-overview.mdx | 4 ++++ docs/build/sdk/typescript-compat/overview.mdx | 18 ++++++++++++++++++ 2 files changed, 22 insertions(+) diff --git a/docs/build/sdk/typescript-compat/migration-overview.mdx b/docs/build/sdk/typescript-compat/migration-overview.mdx index 9ac4ecc..7820496 100644 --- a/docs/build/sdk/typescript-compat/migration-overview.mdx +++ b/docs/build/sdk/typescript-compat/migration-overview.mdx @@ -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 diff --git a/docs/build/sdk/typescript-compat/overview.mdx b/docs/build/sdk/typescript-compat/overview.mdx index 718aa23..27fa581 100644 --- a/docs/build/sdk/typescript-compat/overview.mdx +++ b/docs/build/sdk/typescript-compat/overview.mdx @@ -228,6 +228,24 @@ const nextConfig = { }; ``` +## Automated Migration with Codemod + +If you are migrating an existing codebase from `@erc7824/nitrolite` (v0.4–v0.5.3) or `@layer-3/nitrolite`, the [yellow-sdk-codemod](https://github.com/layer-3/yellow-sdk-codemod) tool can automate much of the upgrade for you. + +:::tip Codemod available +Run the codemod to handle import rewrites, client constructor migration, auth field renames, and package.json updates automatically. Patterns that require manual judgment (RPC call collapse, WebSocket removal) are flagged with `// TODO [codemod]` comments pointing to the exact replacement. + +```bash +# Scan your codebase for old patterns (no changes made) +npx tsx src/cli.ts scan --path ./src + +# Apply all transforms + update dependencies +npx tsx src/cli.ts run --path ./src --update-deps +``` + +See the [codemod README](https://github.com/layer-3/yellow-sdk-codemod#readme) for the full list of transforms and options. +::: + ## Migration Guides - [Migration Overview](./migration-overview) — Pattern changes, import swaps From 92afaf5d69243a86288fdba04051c8d88360b8e0 Mon Sep 17 00:00:00 2001 From: Maharshi Mishra Date: Fri, 13 Mar 2026 16:12:16 +0530 Subject: [PATCH 2/3] docs: move codemod callout to top with collapsible details, add setup context Move the codemod reference to a collapsible section right below the page intro so returning developers see it first. Add clone and install steps so the CLI invocation makes sense without prior context. --- docs/build/sdk/typescript-compat/overview.mdx | 35 +++++++++---------- package-lock.json | 33 +---------------- 2 files changed, 18 insertions(+), 50 deletions(-) diff --git a/docs/build/sdk/typescript-compat/overview.mdx b/docs/build/sdk/typescript-compat/overview.mdx index 27fa581..955f4b4 100644 --- a/docs/build/sdk/typescript-compat/overview.mdx +++ b/docs/build/sdk/typescript-compat/overview.mdx @@ -8,6 +8,23 @@ 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. +
+Already integrated with @erc7824/nitrolite or @layer-3/nitrolite? + +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 +# First, scan to see what needs changing (no files are modified) +npx tsx src/cli.ts scan --path ./src + +# Then apply all transforms and update dependencies +npx tsx src/cli.ts run --path ./src --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. + +
+ ## 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. @@ -228,24 +245,6 @@ const nextConfig = { }; ``` -## Automated Migration with Codemod - -If you are migrating an existing codebase from `@erc7824/nitrolite` (v0.4–v0.5.3) or `@layer-3/nitrolite`, the [yellow-sdk-codemod](https://github.com/layer-3/yellow-sdk-codemod) tool can automate much of the upgrade for you. - -:::tip Codemod available -Run the codemod to handle import rewrites, client constructor migration, auth field renames, and package.json updates automatically. Patterns that require manual judgment (RPC call collapse, WebSocket removal) are flagged with `// TODO [codemod]` comments pointing to the exact replacement. - -```bash -# Scan your codebase for old patterns (no changes made) -npx tsx src/cli.ts scan --path ./src - -# Apply all transforms + update dependencies -npx tsx src/cli.ts run --path ./src --update-deps -``` - -See the [codemod README](https://github.com/layer-3/yellow-sdk-codemod#readme) for the full list of transforms and options. -::: - ## Migration Guides - [Migration Overview](./migration-overview) — Pattern changes, import swaps diff --git a/package-lock.json b/package-lock.json index d1f45a3..af5cc08 100644 --- a/package-lock.json +++ b/package-lock.json @@ -172,7 +172,6 @@ "resolved": "https://registry.npmjs.org/@algolia/client-search/-/client-search-5.49.1.tgz", "integrity": "sha512-Nt9hri7nbOo0RipAsGjIssHkpLMHHN/P7QqENywAq5TLsoYDzUyJGny8FEiD/9KJUxtGH8blGpMedilI6kK3rA==", "license": "MIT", - "peer": true, "dependencies": { "@algolia/client-common": "5.49.1", "@algolia/requester-browser-xhr": "5.49.1", @@ -324,7 +323,6 @@ "resolved": "https://registry.npmjs.org/@babel/core/-/core-7.29.0.tgz", "integrity": "sha512-CGOfOJqWjg2qW/Mb6zNsDm+u5vFQ8DxXfbM09z69p5Z6+mE1ikP2jUXw+j42Pf1XTYED2Rni5f95npYeuwMDQA==", "license": "MIT", - "peer": true, "dependencies": { "@babel/code-frame": "^7.29.0", "@babel/generator": "^7.29.0", @@ -2172,7 +2170,6 @@ } ], "license": "MIT", - "peer": true, "engines": { "node": ">=18" }, @@ -2195,7 +2192,6 @@ } ], "license": "MIT", - "peer": true, "engines": { "node": ">=18" } @@ -2305,7 +2301,6 @@ "resolved": "https://registry.npmjs.org/postcss-selector-parser/-/postcss-selector-parser-7.1.1.tgz", "integrity": "sha512-orRsuYpJVw8LdAwqqLykBj9ecS5/cRHlI5+nvTo8LcCKmzDmqVORXtOIYEEQuL9D4BxtA1lm5isAqzQZCoQ6Eg==", "license": "MIT", - "peer": true, "dependencies": { "cssesc": "^3.0.0", "util-deprecate": "^1.0.2" @@ -2727,7 +2722,6 @@ "resolved": "https://registry.npmjs.org/postcss-selector-parser/-/postcss-selector-parser-7.1.1.tgz", "integrity": "sha512-orRsuYpJVw8LdAwqqLykBj9ecS5/cRHlI5+nvTo8LcCKmzDmqVORXtOIYEEQuL9D4BxtA1lm5isAqzQZCoQ6Eg==", "license": "MIT", - "peer": true, "dependencies": { "cssesc": "^3.0.0", "util-deprecate": "^1.0.2" @@ -3527,7 +3521,6 @@ "resolved": "https://registry.npmjs.org/@docusaurus/core/-/core-3.9.2.tgz", "integrity": "sha512-HbjwKeC+pHUFBfLMNzuSjqFE/58+rLVKmOU3lxQrpsxLBOGosYco/Q0GduBb0/jEMRiyEqjNT/01rRdOMWq5pw==", "license": "MIT", - "peer": true, "dependencies": { "@docusaurus/babel": "3.9.2", "@docusaurus/bundler": "3.9.2", @@ -3709,7 +3702,6 @@ "resolved": "https://registry.npmjs.org/@docusaurus/plugin-content-docs/-/plugin-content-docs-3.9.2.tgz", "integrity": "sha512-C5wZsGuKTY8jEYsqdxhhFOe1ZDjH0uIYJ9T/jebHwkyxqnr4wW0jTkB72OMqNjsoQRcb0JN3PcSeTwFlVgzCZg==", "license": "MIT", - "peer": true, "dependencies": { "@docusaurus/core": "3.9.2", "@docusaurus/logger": "3.9.2", @@ -4753,7 +4745,6 @@ "resolved": "https://registry.npmjs.org/@mdx-js/react/-/react-3.1.1.tgz", "integrity": "sha512-f++rKLQgUVYDAtECQ6fn/is15GkEH9+nZPM3MS0RcxVqoTfawHvDlSCH7JbMhAM6uJ32v3eXLvLmLvjGu7PTQw==", "license": "MIT", - "peer": true, "dependencies": { "@types/mdx": "^2.0.0" }, @@ -5236,7 +5227,6 @@ "resolved": "https://registry.npmjs.org/@svgr/core/-/core-8.1.0.tgz", "integrity": "sha512-8QqtOQT5ACVlmsvKOJNEaWmRPmcojMOzCz4Hs2BGG/toAp/K38LcsMRyLp349glq5AzJbCEeimEoxaX6v/fLrA==", "license": "MIT", - "peer": true, "dependencies": { "@babel/core": "^7.21.3", "@svgr/babel-preset": "8.1.0", @@ -6149,7 +6139,6 @@ "resolved": "https://registry.npmjs.org/@types/react/-/react-19.2.14.tgz", "integrity": "sha512-ilcTH/UniCkMdtexkoCN0bI7pMcJDvmQFPvuPvmEaYA/NSfFTAgdUSLAoVjaRJm7+6PvcM+q1zYOwS4wTYMF9w==", "license": "MIT", - "peer": true, "dependencies": { "csstype": "^3.2.2" } @@ -6511,7 +6500,6 @@ "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.16.0.tgz", "integrity": "sha512-UVJyE9MttOsBQIDKw1skb9nAwQuR5wuGD3+82K6JgJlm/Y+KI92oNsMNGZCYdDsVtRHSak0pcV5Dno5+4jh9sw==", "license": "MIT", - "peer": true, "bin": { "acorn": "bin/acorn" }, @@ -6579,7 +6567,6 @@ "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.18.0.tgz", "integrity": "sha512-PlXPeEWMXMZ7sPYOHqmDyCJzcfNrUr3fGNKtezX14ykXOEIvyK81d+qydx89KY5O71FKMPaQ2vBfBFI5NHR63A==", "license": "MIT", - "peer": true, "dependencies": { "fast-deep-equal": "^3.1.3", "fast-uri": "^3.0.1", @@ -6625,7 +6612,6 @@ "resolved": "https://registry.npmjs.org/algoliasearch/-/algoliasearch-5.49.1.tgz", "integrity": "sha512-X3Pp2aRQhg4xUC6PQtkubn5NpRKuUPQ9FPDQlx36SmpFwwH2N0/tw4c+NXV3nw3PsgeUs+BuWGP0gjz3TvENLQ==", "license": "MIT", - "peer": true, "dependencies": { "@algolia/abtesting": "1.15.1", "@algolia/client-abtesting": "5.49.1", @@ -7142,7 +7128,6 @@ } ], "license": "MIT", - "peer": true, "dependencies": { "baseline-browser-mapping": "^2.9.0", "caniuse-lite": "^1.0.30001759", @@ -7451,7 +7436,6 @@ "resolved": "https://registry.npmjs.org/chevrotain/-/chevrotain-11.1.2.tgz", "integrity": "sha512-opLQzEVriiH1uUQ4Kctsd49bRoFDXGGSC4GUqj7pGyxM3RehRhvTlZJc1FL/Flew2p5uwxa1tUDWKzI4wNM8pg==", "license": "Apache-2.0", - "peer": true, "dependencies": { "@chevrotain/cst-dts-gen": "11.1.2", "@chevrotain/gast": "11.1.2", @@ -8165,7 +8149,6 @@ "resolved": "https://registry.npmjs.org/postcss-selector-parser/-/postcss-selector-parser-7.1.1.tgz", "integrity": "sha512-orRsuYpJVw8LdAwqqLykBj9ecS5/cRHlI5+nvTo8LcCKmzDmqVORXtOIYEEQuL9D4BxtA1lm5isAqzQZCoQ6Eg==", "license": "MIT", - "peer": true, "dependencies": { "cssesc": "^3.0.0", "util-deprecate": "^1.0.2" @@ -8491,7 +8474,6 @@ "resolved": "https://registry.npmjs.org/cytoscape/-/cytoscape-3.33.1.tgz", "integrity": "sha512-iJc4TwyANnOGR1OmWhsS9ayRS3s+XQ185FmuHObThD+5AeJCakAAbWv8KimMTt08xCCLNgneQwFp+JRJOr9qGQ==", "license": "MIT", - "peer": true, "engines": { "node": ">=0.10" } @@ -8901,7 +8883,6 @@ "resolved": "https://registry.npmjs.org/d3-selection/-/d3-selection-3.0.0.tgz", "integrity": "sha512-fmTRWbNMmsmWq6xJV8D19U/gw/bwrHfNXxrIN+HfZgnzqTHp9jOmKMhsTUjXOJnZOdZY9Q28y4yebKzqDKlxlQ==", "license": "ISC", - "peer": true, "engines": { "node": ">=12" } @@ -10222,7 +10203,6 @@ "resolved": "https://registry.npmjs.org/ajv/-/ajv-6.14.0.tgz", "integrity": "sha512-IWrosm/yrn43eiKqkfkHis7QioDleaXQHdDVPKg0FSwwd/DuvyX79TZnFOnYpB7dcsFAMmtFztZuXPDvSePkFw==", "license": "MIT", - "peer": true, "dependencies": { "fast-deep-equal": "^3.1.1", "fast-json-stable-stringify": "^2.0.0", @@ -15644,7 +15624,6 @@ "resolved": "https://registry.npmjs.org/ajv/-/ajv-6.14.0.tgz", "integrity": "sha512-IWrosm/yrn43eiKqkfkHis7QioDleaXQHdDVPKg0FSwwd/DuvyX79TZnFOnYpB7dcsFAMmtFztZuXPDvSePkFw==", "license": "MIT", - "peer": true, "dependencies": { "fast-deep-equal": "^3.1.1", "fast-json-stable-stringify": "^2.0.0", @@ -16222,7 +16201,6 @@ } ], "license": "MIT", - "peer": true, "dependencies": { "nanoid": "^3.3.11", "picocolors": "^1.1.1", @@ -17126,7 +17104,6 @@ "resolved": "https://registry.npmjs.org/postcss-selector-parser/-/postcss-selector-parser-7.1.1.tgz", "integrity": "sha512-orRsuYpJVw8LdAwqqLykBj9ecS5/cRHlI5+nvTo8LcCKmzDmqVORXtOIYEEQuL9D4BxtA1lm5isAqzQZCoQ6Eg==", "license": "MIT", - "peer": true, "dependencies": { "cssesc": "^3.0.0", "util-deprecate": "^1.0.2" @@ -17949,7 +17926,6 @@ "resolved": "https://registry.npmjs.org/react/-/react-19.2.4.tgz", "integrity": "sha512-9nfp2hYpCwOjAN+8TZFGhtWEwgvWHXqESH8qT89AT/lWklpLON22Lc8pEtnpsZz7VmawabSU0gCjnj8aC0euHQ==", "license": "MIT", - "peer": true, "engines": { "node": ">=0.10.0" } @@ -17959,7 +17935,6 @@ "resolved": "https://registry.npmjs.org/react-dom/-/react-dom-19.2.4.tgz", "integrity": "sha512-AXJdLo8kgMbimY95O2aKQqsz2iWi9jMgKJhRBAxECE4IFxfcazB2LmzloIoibJI3C12IlY20+KFaLv+71bUJeQ==", "license": "MIT", - "peer": true, "dependencies": { "scheduler": "^0.27.0" }, @@ -18015,7 +17990,6 @@ "resolved": "https://registry.npmjs.org/@docusaurus/react-loadable/-/react-loadable-6.0.0.tgz", "integrity": "sha512-YMMxTUQV/QFSnbgrP3tjDzLHRg7vsbMn8e9HAa8o/1iXoiomo48b7sk/kkmWEuWNDPJVlKSJRB6Y2fHqdJk+SQ==", "license": "MIT", - "peer": true, "dependencies": { "@types/react": "*" }, @@ -18044,7 +18018,6 @@ "resolved": "https://registry.npmjs.org/react-router/-/react-router-5.3.4.tgz", "integrity": "sha512-Ys9K+ppnJah3QuaRiLxk+jDWOR1MekYQrlytiXxC1RyfbdsZkS5pvKAzCCr031xHixZwpnsYNT5xysdFHQaYsA==", "license": "MIT", - "peer": true, "dependencies": { "@babel/runtime": "^7.12.13", "history": "^4.9.0", @@ -19961,8 +19934,7 @@ "version": "2.8.1", "resolved": "https://registry.npmjs.org/tslib/-/tslib-2.8.1.tgz", "integrity": "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==", - "license": "0BSD", - "peer": true + "license": "0BSD" }, "node_modules/tsyringe": { "version": "4.10.0", @@ -20043,7 +20015,6 @@ "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==", "devOptional": true, "license": "Apache-2.0", - "peer": true, "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" @@ -20427,7 +20398,6 @@ "resolved": "https://registry.npmjs.org/ajv/-/ajv-6.14.0.tgz", "integrity": "sha512-IWrosm/yrn43eiKqkfkHis7QioDleaXQHdDVPKg0FSwwd/DuvyX79TZnFOnYpB7dcsFAMmtFztZuXPDvSePkFw==", "license": "MIT", - "peer": true, "dependencies": { "fast-deep-equal": "^3.1.1", "fast-json-stable-stringify": "^2.0.0", @@ -20675,7 +20645,6 @@ "resolved": "https://registry.npmjs.org/webpack/-/webpack-5.105.4.tgz", "integrity": "sha512-jTywjboN9aHxFlToqb0K0Zs9SbBoW4zRUlGzI2tYNxVYcEi/IPpn+Xi4ye5jTLvX2YeLuic/IvxNot+Q1jMoOw==", "license": "MIT", - "peer": true, "dependencies": { "@types/eslint-scope": "^3.7.7", "@types/estree": "^1.0.8", From 0b601c4becf852a926140fe567754bb4f9ab00af Mon Sep 17 00:00:00 2001 From: Maharshi Mishra Date: Fri, 13 Mar 2026 16:15:52 +0530 Subject: [PATCH 3/3] docs: update yellow-sdk-codemod instructions for migration Enhance the codemod section by adding detailed steps for cloning and installing the tool, and clarify the scanning and transformation commands for better usability during the migration from v0.5.3 to v1.0.0. --- docs/build/sdk/typescript-compat/overview.mdx | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/docs/build/sdk/typescript-compat/overview.mdx b/docs/build/sdk/typescript-compat/overview.mdx index 955f4b4..340a014 100644 --- a/docs/build/sdk/typescript-compat/overview.mdx +++ b/docs/build/sdk/typescript-compat/overview.mdx @@ -14,11 +14,15 @@ Compatibility layer that bridges the Nitrolite SDK **v0.5.3 API** to the **v1.0. 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 -# First, scan to see what needs changing (no files are modified) -npx tsx src/cli.ts scan --path ./src +# Clone the codemod and install its dependencies +git clone https://github.com/layer-3/yellow-sdk-codemod.git +cd yellow-sdk-codemod && npm install -# Then apply all transforms and update dependencies -npx tsx src/cli.ts run --path ./src --update-deps +# 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.