ChiefWoods · Jul 21, 2026 · Jul 21, 2026 · Jul 21, 2026 · Jul 31, 2026 · Jul 31, 2026
diff --git a/.github/workflows/node-build.yml b/.github/workflows/node-build.yml
@@ -22,75 +22,40 @@ on:
       - crates/node-litesvm/docs/**
 
 jobs:
-  lint:
-    name: Lint
-    runs-on: ubuntu-latest
-    defaults:
-      run:
-        working-directory: crates/node-litesvm
-    steps:
-      - uses: actions/checkout@v6
-
-      - name: Setup node
-        uses: actions/setup-node@v6
-        with:
-          node-version: 22
-          cache: 'yarn'
-          cache-dependency-path: crates/node-litesvm/yarn.lock
-
-      - name: Install
-        uses: dtolnay/rust-toolchain@nightly
-        with:
-          components: clippy, rustfmt
-
-      - name: Install dependencies
-        run: yarn install
-
-      - name: Oxlint
-        run: yarn lint
-
-      - name: Cargo fmt
-        run: cargo fmt -- --check
-
-      - name: Clippy
-        run: cargo clippy
   build:
     strategy:
       fail-fast: false
       matrix:
         settings:
           - host: macos-latest
             target: x86_64-apple-darwin
-            build: yarn build --target x86_64-apple-darwin
+            build: yarn workspace litesvm-core build --target x86_64-apple-darwin
           - host: macos-latest
             target: aarch64-apple-darwin
-            build: yarn build --target aarch64-apple-darwin
+            build: yarn workspace litesvm-core build --target aarch64-apple-darwin
           - host: ubuntu-22.04
             target: x86_64-unknown-linux-gnu
-            build: yarn build --target x86_64-unknown-linux-gnu --use-napi-cross
+            build: yarn workspace litesvm-core build --target x86_64-unknown-linux-gnu --use-napi-cross
           - host: ubuntu-22.04
             target: aarch64-unknown-linux-gnu
-            build: yarn build --target aarch64-unknown-linux-gnu --use-napi-cross
+            build: yarn workspace litesvm-core build --target aarch64-unknown-linux-gnu --use-napi-cross
           - host: ubuntu-latest
             target: x86_64-unknown-linux-musl
-            build: yarn build --target x86_64-unknown-linux-musl -x
+            build: yarn workspace litesvm-core build --target x86_64-unknown-linux-musl -x
           - host: ubuntu-latest
             target: aarch64-unknown-linux-musl
-            build: yarn build --target aarch64-unknown-linux-musl -x
+            build: yarn workspace litesvm-core build --target aarch64-unknown-linux-musl -x
     name: stable - ${{ matrix.settings.target }} - node@22
     runs-on: ${{ matrix.settings.host }}
-    defaults:
-      run:
-        working-directory: crates/node-litesvm
     steps:
       - uses: actions/checkout@v6
       - name: Setup node
         uses: actions/setup-node@v6
         with:
           node-version: 22
           cache: yarn
-          cache-dependency-path: crates/node-litesvm/yarn.lock
-      - name: Install
+          cache-dependency-path: yarn.lock
+      - name: Install Rust
         uses: dtolnay/rust-toolchain@nightly
         with:
           toolchain: stable
@@ -122,16 +87,17 @@ jobs:
         if: ${{ matrix.settings.setup }}
         shell: bash
       - name: Install dependencies
-        run: yarn install
+        run: corepack enable && yarn install --immutable
       - name: Build
         run: ${{ matrix.settings.build }}
         shell: bash
       - name: Upload artifact
         uses: actions/upload-artifact@v6
         with:
           name: bindings-${{ matrix.settings.target }}
-          path: crates/node-litesvm/litesvm/litesvm.*.node
+          path: crates/node-litesvm-core/litesvm/litesvm.*.node
           if-no-files-found: error
+
   test-macOS-binding:
     name: Test bindings on ${{ matrix.settings.target }} - node@${{ matrix.node }}
     needs:
@@ -150,9 +116,6 @@ jobs:
           - '20'
           - '22'
     runs-on: ${{ matrix.settings.host }}
-    defaults:
-      run:
-        working-directory: crates/node-litesvm
     steps:
       - uses: actions/checkout@v6
       - name: Setup node
@@ -161,19 +124,25 @@ jobs:
           node-version: ${{ matrix.node }}
           cache: yarn
           architecture: ${{ matrix.settings.architecture }}
-          cache-dependency-path: crates/node-litesvm/yarn.lock
+          cache-dependency-path: yarn.lock
       - name: Install dependencies
-        run: yarn install
+        run: corepack enable && yarn install --immutable
       - name: Download artifacts
         uses: actions/download-artifact@v4
         with:
           name: bindings-${{ matrix.settings.target }}
-          path: crates/node-litesvm/litesvm
-      - name: List packages
-        run: ls -R .
+          path: crates/node-litesvm-core/litesvm
+      - name: List bindings
+        run: ls -R crates/node-litesvm-core/litesvm
         shell: bash
-      - name: Test bindings
-        run: yarn test
+      - name: Test core and wrappers
+        run: |
+          yarn workspace litesvm-core test
+          yarn workspace litesvm build
+          yarn workspace litesvm test
+          yarn workspace litesvm-web3js build
+          yarn workspace litesvm-web3js test
+
   test-linux-binding:
     name: Test ${{ matrix.target }} - node@${{ matrix.node }}
     needs:
@@ -186,30 +155,24 @@ jobs:
           - x86_64-unknown-linux-musl
           - aarch64-unknown-linux-gnu
           - aarch64-unknown-linux-musl
-          # - armv7-unknown-linux-gnueabihf
         node:
           - '20'
           - '22'
     runs-on: ${{ contains(matrix.target, 'aarch64') && 'ubuntu-24.04-arm' || 'ubuntu-latest' }}
-    defaults:
-        run:
-          working-directory: crates/node-litesvm
     steps:
       - uses: actions/checkout@v6
       - name: Setup node
         uses: actions/setup-node@v6
         with:
           node-version: ${{ matrix.node }}
           cache: yarn
-          cache-dependency-path: crates/node-litesvm/yarn.lock
+          cache-dependency-path: yarn.lock
       - name: Output docker params
         id: docker
         run: |
           node -e "
             if ('${{ matrix.target }}'.startsWith('aarch64')) {
               console.log('PLATFORM=linux/arm64')
-            } else if ('${{ matrix.target }}'.startsWith('armv7')) {
-              console.log('PLATFORM=linux/arm/v7')
             } else {
               console.log('PLATFORM=linux/amd64')
             }
@@ -223,27 +186,21 @@ jobs:
           " >> $GITHUB_OUTPUT
       - name: Install dependencies
         run: |
-          yarn config set --json supportedArchitectures.cpu '["current", "arm64", "x64", "arm"]'
+          corepack enable
+          yarn config set --json supportedArchitectures.cpu '["current", "arm64", "x64"]'
           yarn config set --json supportedArchitectures.libc '["current", "musl", "gnu"]'
-          yarn install
+          yarn install --immutable
       - name: Download artifacts
         uses: actions/download-artifact@v6
         with:
           name: bindings-${{ matrix.target }}
-          path: crates/node-litesvm/litesvm
-      - name: List packages
-        run: ls -R .
+          path: crates/node-litesvm-core/litesvm
+      - name: List bindings
+        run: ls -R crates/node-litesvm-core/litesvm
         shell: bash
-      # - name: Set up QEMU
-      #   uses: docker/setup-qemu-action@v3
-      #   if: ${{ contains(matrix.target, 'armv7') }}
-      #   with:
-      #     platforms: all
-      # - run: docker run --rm --privileged multiarch/qemu-user-static --reset -p yes
-      #   if: ${{ contains(matrix.target, 'armv7') }}
-      - name: Test bindings
+      - name: Test core and wrappers
         uses: addnab/docker-run-action@v3
         with:
           image: ${{ steps.docker.outputs.IMAGE }}
-          options: -v ${{ github.workspace }}:${{ github.workspace }} -w ${{ github.workspace }}/crates/node-litesvm --platform ${{ steps.docker.outputs.PLATFORM }} -e RUST_MIN_STACK=8388608
-          run: yarn test
+          options: -v ${{ github.workspace }}:${{ github.workspace }} -w ${{ github.workspace }} --platform ${{ steps.docker.outputs.PLATFORM }} -e RUST_MIN_STACK=8388608
+          run: corepack enable && yarn workspace litesvm-core test && yarn workspace litesvm build && yarn workspace litesvm test && yarn workspace litesvm-web3js build && yarn workspace litesvm-web3js test
diff --git a/.github/workflows/node-docs-check.yml b/.github/workflows/node-docs-check.yml
@@ -25,10 +25,8 @@ jobs:
         with:
           node-version: 22
           cache: yarn
-          cache-dependency-path: crates/node-litesvm/yarn.lock
+          cache-dependency-path: yarn.lock
       - name: Install dependencies
-        working-directory: crates/node-litesvm
-        run: yarn install
+        run: corepack enable && yarn install --immutable
       - name: Build with VitePress
-        working-directory: crates/node-litesvm
-        run: yarn predocs && yarn docs:build
+        run: yarn workspace litesvm predocs && yarn workspace litesvm docs:build
diff --git a/.github/workflows/node-docs.yml b/.github/workflows/node-docs.yml
@@ -25,15 +25,13 @@ jobs:
         with:
           node-version: 22
           cache: yarn
-          cache-dependency-path: crates/node-litesvm/yarn.lock
+          cache-dependency-path: yarn.lock
       - name: Setup Pages
         uses: actions/configure-pages@v5
       - name: Install dependencies
-        working-directory: crates/node-litesvm
-        run: yarn install
+        run: corepack enable && yarn install --immutable
       - name: Build with VitePress
-        working-directory: crates/node-litesvm
-        run: yarn predocs && yarn docs:build
+        run: yarn workspace litesvm predocs && yarn workspace litesvm docs:build
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v4
         with:
@@ -49,4 +47,4 @@ jobs:
     steps:
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@v4
diff --git a/.github/workflows/node-lint.yml b/.github/workflows/node-lint.yml
@@ -9,7 +9,7 @@ on:
       - LICENSE
       - '**/*.gitignore'
       - .editorconfig
-      - node-litesvm/docs/**
+      - crates/node-litesvm/docs/**
 jobs:
   lint:
     runs-on: ubuntu-latest
@@ -20,13 +20,19 @@ jobs:
         with:
           node-version: 22
           check-latest: true
-      - name: Rustup install
+          cache: yarn
+          cache-dependency-path: yarn.lock
+      - name: Install Rust
         uses: dtolnay/rust-toolchain@stable
         with:
-          components: clippy
+          components: clippy, rustfmt
       - name: Install dependencies
-        run: cd crates/node-litesvm && corepack enable && yarn install
-      - name: Lint rust
-        run: cd crates/node-litesvm && yarn lint:rust
-      - name: Lint JS
-        run: cd crates/node-litesvm && yarn lint:js
+        run: corepack enable && yarn install --immutable
+      - name: Check Rust formatting
+        run: cargo fmt --all -- --check
+      - name: Lint Rust core
+        run: yarn workspace litesvm-core lint
+      - name: Lint Kit wrapper
+        run: yarn workspace litesvm lint:js
+      - name: Lint Web3.js wrapper
+        run: yarn workspace litesvm-web3js lint
diff --git a/.github/workflows/release-node.yml b/.github/workflows/release-node.yml
@@ -3,8 +3,9 @@ name: release NodeJS
 on:
   push:
     tags:
-    - "node-v[0-9]+.[0-9]+.[0-9]+"
-    - "node-v[0-9]+.[0-9]+.[0-9]+-*"
+      - "node-v[0-9]+.[0-9]+.[0-9]+"
+      - "node-v[0-9]+.[0-9]+.[0-9]+-*"
+
 permissions:
   contents: read
   id-token: write
@@ -20,28 +21,49 @@ jobs:
         with:
           node-version: 22
           check-latest: true
+          registry-url: https://registry.npmjs.org
           cache: yarn
-          cache-dependency-path: crates/node-litesvm/yarn.lock
+          cache-dependency-path: yarn.lock
+      - name: Check package versions match the release tag
+        run: |
+          node <<'NODE'
+          const assert = require('node:assert/strict');
+          const version = process.env.GITHUB_REF_NAME.replace(/^node-v/, '');
+          for (const workspace of require('./package.json').workspaces) {
+            const pkg = require(`./${workspace}/package.json`);
+            assert.equal(pkg.version, version, `${pkg.name} must match release version ${version}`);
+          }
+          NODE
       - name: Upgrade npm for trusted publishing
         run: npm install -g npm@latest
       - name: Install dependencies
-        run: cd crates/node-litesvm/ && corepack enable && yarn install
-      - name: Create npm dirs
-        run: cd crates/node-litesvm/ && yarn napi create-npm-dirs
-      - name: Download all artifacts
+        run: corepack enable && yarn install --immutable
+      - name: Create native package directories
+        run: yarn workspace litesvm-core napi create-npm-dirs
+      - name: Download all native artifacts
         uses: dawidd6/action-download-artifact@v11
         with:
           workflow: node-build.yml
-          path: crates/node-litesvm/artifacts
-      - name: Move artifacts
-        run: cd crates/node-litesvm/ && yarn artifacts
-      - name: Compile Typescript
-        run: cd crates/node-litesvm/ && yarn build:js
-      - name: List packages
-        run: cd crates/node-litesvm/ && ls -R ./npm
-      - name: Publish
+          path: crates/node-litesvm-core/artifacts
+      - name: Move native artifacts
+        run: yarn workspace litesvm-core artifacts
+      - name: Build wrappers
+        run: |
+          yarn workspace litesvm build
+          yarn workspace litesvm-web3js build
+      - name: List native packages
+        run: ls -R crates/node-litesvm-core/npm
+      - name: Publish core and wrappers
+        env:
+          # Bootstrap the eight new packages with a granular write token that can
+          # create packages and bypass 2FA. After configuring trusted publishing
+          # for litesvm-core, litesvm-web3js and all six platform packages, remove it.
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
         run: |
-          cd crates/node-litesvm/
           TAG=latest
           [[ "$GITHUB_REF_NAME" == *-rc.* ]] && TAG=next
-          npm publish --access public --tag "$TAG"
+          (cd crates/node-litesvm-core && npm publish --access public --tag "$TAG")
+          yarn workspace litesvm pack --out "$RUNNER_TEMP/litesvm.tgz"
+          yarn workspace litesvm-web3js pack --out "$RUNNER_TEMP/litesvm-web3js.tgz"
+          npm publish "$RUNNER_TEMP/litesvm.tgz" --access public --tag "$TAG"
+          npm publish "$RUNNER_TEMP/litesvm-web3js.tgz" --access public --tag "$TAG"
diff --git a/.gitignore b/.gitignore
@@ -1,3 +1,7 @@
 target/
 tarpaulin-out/
-tarpaulin-out-up/
+tarpaulin-out-up/
+node_modules/
+.yarn/*
+!.yarn/releases
+!.yarn/releases/yarn-4.10.3.cjs
diff --git a/...de-litesvm/.yarn/releases/yarn-4.10.3.cjs → .yarn/releases/yarn-4.10.3.cjs b/...de-litesvm/.yarn/releases/yarn-4.10.3.cjs → .yarn/releases/yarn-4.10.3.cjs
diff --git a/crates/node-litesvm/.yarnrc.yml → .yarnrc.yml b/crates/node-litesvm/.yarnrc.yml → .yarnrc.yml
diff --git a/Cargo.toml b/Cargo.toml
@@ -1,6 +1,7 @@
 [workspace]
 resolver = "2"
 members = ["crates/*"]
+exclude = ["crates/node-litesvm", "crates/node-litesvm-web3js"]
 
 [workspace.package]
 version = "0.18.0"

diff --git a/README.md b/README.md
@@ -126,7 +126,10 @@ See the [anchor-litesvm testing guide](https://www.litesvm.com/docs/additional-c
 
 - Full documentation: [litesvm.com](https://litesvm.com)
 - Full API reference: [docs.rs/litesvm](https://docs.rs/litesvm/latest/litesvm/)
-- Node.js wrapper: [`litesvm` on npm](https://www.npmjs.com/package/litesvm) — see [`crates/node-litesvm`](crates/node-litesvm) for its README and tutorial
+- Node.js packages:
+  - [`litesvm`](https://www.npmjs.com/package/litesvm) provides the `@solana/kit` wrapper.
+  - [`litesvm-web3js`](https://www.npmjs.com/package/litesvm-web3js) provides the `@solana/web3.js` v3 wrapper.
+  - [`litesvm-core`](https://www.npmjs.com/package/litesvm-core) exposes the raw NAPI bindings used by both wrappers.
 
 ### 🛠️ Developing litesvm
 

diff --git a/crates/node-litesvm/.cargo/config.toml → crates/node-litesvm-core/.cargo/config.toml b/crates/node-litesvm/.cargo/config.toml → crates/node-litesvm-core/.cargo/config.toml