Skip to main content

Migrating from beacon-sdk to octez.connect-sdk

During February 2026, the beacon-sdk packages have been renamed and moved to the @tezos-x namespace under octez.connect. This guide will help you migrate your project to the new package names.

Overview​

The migration involves:

  1. Updating your package.json dependencies.
  2. Updating import statements in your code.
  3. Updating any local scripts or configurations referencing the old package names.

Package Mapping​

Beacon SDK Packages​

Old Package (@airgap/*)New Package (@tezos-x/*)
@airgap/beacon-sdk@tezos-x/octez.connect-sdk
@airgap/beacon-dapp@tezos-x/octez.connect-dapp
@airgap/beacon-wallet@tezos-x/octez.connect-wallet
@airgap/beacon-core@tezos-x/octez.connect-core
@airgap/beacon-types@tezos-x/octez.connect-types
@airgap/beacon-ui@tezos-x/octez.connect-ui
@airgap/beacon-utils@tezos-x/octez.connect-utils
@airgap/beacon-transport-matrix@tezos-x/octez.connect-transport-matrix
@airgap/beacon-transport-postmessage@tezos-x/octez.connect-transport-postmessage
@airgap/beacon-transport-walletconnect@tezos-x/octez.connect-transport-walletconnect
@airgap/beacon-blockchain-tezos@tezos-x/octez.connect-blockchain-tezos
@airgap/beacon-blockchain-tezos-sapling@tezos-x/octez.connect-blockchain-tezos-sapling
@airgap/beacon-blockchain-substrate@tezos-x/octez.connect-blockchain-substrate

Migration Script​

You can use the following script to automatically find and replace the package names in your codebase.

1. Create a file named migrate-to-octez.sh:

#!/bin/bash
set -e

# Function to migrate a package pair
migrate_package() {
  local FROM="$1"
  local TO="$2"

  echo "Migrating $FROM -> $TO"

  # Find files containing the exact string (excluding binary, node_modules, git)
  local FILES=$(git grep -lF "$FROM" || true)

  if [ -z "$FILES" ]; then
    return
  fi

  # Iterate and replace
  for file in $FILES; do
    # Check if text file to avoid corrupting binaries
    if file -b --mime-type "$file" | grep -qE "text|json"; then
       # Replace in place (Mac/Linux compatible sed)
       if [[ "$OSTYPE" == "darwin"* ]]; then
         sed -i '' "s|$FROM|$TO|g" "$file"
       else
         sed -i "s|$FROM|$TO|g" "$file"
       fi
       echo "  Patched $file"
    fi
  done
}

echo "Starting migration..."

# --- Beacon Packages ---
migrate_package "@airgap/beacon-sdk" "@tezos-x/octez.connect-sdk"
migrate_package "@airgap/beacon-dapp" "@tezos-x/octez.connect-dapp"
migrate_package "@airgap/beacon-wallet" "@tezos-x/octez.connect-wallet"
migrate_package "@airgap/beacon-core" "@tezos-x/octez.connect-core"
migrate_package "@airgap/beacon-types" "@tezos-x/octez.connect-types"
migrate_package "@airgap/beacon-transport-matrix" "@tezos-x/octez.connect-transport-matrix"
migrate_package "@airgap/beacon-transport-postmessage" "@tezos-x/octez.connect-transport-postmessage"
migrate_package "@airgap/beacon-blockchain-tezos" "@tezos-x/octez.connect-blockchain-tezos"

echo "Migration script finished."

2. Make the script executable and run it:

chmod +x migrate-to-octez.sh
./migrate-to-octez.sh

3. Install new dependencies:

After running the script, your package.json will be updated. Run the installation command to update your node modules and lockfile.

npm install
# or
yarn install

Manual Verification​

After running the automated migration, please verify:

  1. Imports: Check that your import statements now reference @tezos-x/octez.connect-*.
  2. Styles/CSS: If you imported CSS from the old packages, check that the paths are still valid (folder structures generally remain similar, but check for any name changes).
  3. Local references: If you had manual paths pointing to node_modules/beacon-sdk, update them to node_modules/@tezos-x/octez.connect-sdk.

Troubleshooting​

If you encounter issues:

  • Clean install: Delete node_modules and your lockfile (package-lock.json or yarn.lock) and reinstall.
  • Check peer dependencies: Ensure all related packages are updated to compatible versions.