Migration Guide

How to migrate from v7.x.x to v8.x.x of @stacks/connect

For a while now, the Stacks community has been working on a new standard for wallet-to-dapp communication. Stacks Connect and related projects now use standards like WBIPs and SIP-030 to allow wallets to communicate with dapps in a more simplified and flexible way.

Migration Status

Feel free to continue using Stacks Connect 7.x.x while things stabilize. The 7.x.x version may still be more well supported by some wallets.

For the legacy version of @stacks/connect using JWT tokens, you can use:

npm install @stacks/connect@7.10.1

Deprecations

The following classes, methods, and types are deprecated in favor of the new request RPC methods:

  • show... and open... methods
  • authenticate method
  • UserSession class and related functionality
  • AppConfig class
  • SessionOptions interface
  • SessionData interface
  • UserData interface
  • SessionDataStore class
  • InstanceDataStore class
  • LocalStorageStore class
Backwards Compatibility

To make migrating easier, the familiar UserSession & AppConfig class still exists and is semi-backwards compatible for the 8.x.x release. It will "cache" the user's address in local storage and allow access to it via the loadUserData method (as previously done).

Migration Steps

To update from <=7.x.x to latest/8.x.x, follow these steps:

npm install @stacks/connect@latest

Switch from showXyz, openXyz, doXyz methods to the request method:

  • request follows the pattern request(method: string, params: object), see Usage for more details
  • request is an async function, so replace the onFinish and onCancel callbacks with .then().catch() or try & await

Examples:

  • showConnect(), authenticate() → connect()
  • useConnect().doContractCall({}) → request("stx_callContract", {})
  • openContractDeploy() → request("stx_deployContract", {})

Switch from showConnect or authenticate to connect() methods:

  • connect() is an alias for request({forceWalletSelect: true}, 'getAddresses')
  • connect() by default caches the user's address in local storage
  • Switch from UserSession.isSignedIn() to isConnected()
  • Switch from UserSession.signUserOut() to disconnect()
  • Remove code referencing deprecated methods (AppConfig, UserSession, etc.)
  • Remove the @stacks/connect-react package
    • You may need to manually reload a component to see local storage updates
    • No custom hooks are needed to use Stacks Connect anymore
    • We are working on a new @stacks/react package that will make usage even easier in the future (e.g., tracking transaction status, reloading components when a connection is established, updating the page when the network changes, and more)

Address Access

Previously, the UserSession class was used to access the user's addresses and data, which abstracted away the underlying implementation details. Now, the request method is used to directly interact with the wallet, giving developers more explicit control and clarity over what's happening under the hood. This manual approach makes the wallet interaction more transparent and customizable. Developers can manually manage the currently connected user's address in e.g. local storage, jotai, etc. or use the connect()/request() method to cache the address in local storage.

Security Note

For security reasons, the 8.x.x release only returns the current network's address (where previously both mainnet and testnet addresses were returned).

How is this guide?

Contents

DeprecationsMigration StepsAddress Access