Merge pull request #207 from lidofinance/feature/si-1628-create-migra…

…tion-guide-for-the-latest-reef-knot-version

Add migration guide for the latest reef knot version

README.md

@@ -1,32 +1,189 @@
-#  Reef Knot &nbsp; <img src="logo.svg" alt='Reef Knot logo' height='45' align='top'/> &nbsp;   
-[![NPM Version](https://img.shields.io/npm/v/reef-knot)](https://www.npmjs.com/package/reef-knot)  
+# Reef Knot &nbsp; <img src="logo.svg" alt='Reef Knot logo' height='45' align='top'/> &nbsp;
+
+[![NPM Version](https://img.shields.io/npm/v/reef-knot)](https://www.npmjs.com/package/reef-knot)
 
 Web3 Wallets Connection Library
 
+---
+
 ## Documentation
 
 - [How to add a wallet](docs/how-to-add-a-wallet.md)
+- [Migration guide](docs/migration-guide.md)
+
+---
+
+## Installation
+
+### Add the reef-knot package
+
+#### Using NPM
+
+```bash
+npm install reef-knot
+```
+
+#### Using Yarn
+
+```bash
+yarn add reef-knot
+```
+
+### Wagmi and Viem
+
+Reef Knot relies on the `wagmi` and `viem` libraries as peer dependencies. To install these libraries, follow the ["Getting Started"](https://wagmi.sh/react/getting-started) guide in the wagmi documentation.
+
+### Example Setup
+
+For an example of Reef Knot setup and configuration, check out [this demo app](https://github.com/lidofinance/reef-knot/blob/main/apps/demo-react/providers/web3.tsx).
+
+### Required Imports
+
+To set up Reef Knot, you’ll need the following imports:
+
+```typescript
+import { ReefKnotProvider, getDefaultConfig } from 'reef-knot/core-react';
+import {
+  ReefKnotWalletsModal,
+  getDefaultWalletsModalConfig,
+} from 'reef-knot/connect-wallet-modal';
+import { WalletsListEthereum } from 'reef-knot/wallets';
+```
+
+### Setting Up Providers
+
+1. Place the `<ReefKnotProvider>` inside the Wagmi Context Provider.
+2. Place the `<ReefKnotWalletsModal>` component inside the `<ReefKnotProvider>`. This component manages the Wallet Connection Modal.
+
+### Configuration
+
+#### Example
+
+You can refer to [the code of the Reef Knot demo app](https://github.com/lidofinance/reef-knot/blob/main/apps/demo-react/providers/web3.tsx) as a reference for setting up the configuration.
+
+#### Description
+
+Reef Knot provides the `getDefaultConfig` helper function, which acts as a single entry point for configuring both `wagmi` and Reef Knot:
+
+```typescript
+const { wagmiConfig, reefKnotConfig, walletsModalConfig } = getDefaultConfig({
+walletsList: WalletsListEthereum,
+// Other config options
+...
+
+// Wallets configuration
+...getDefaultWalletsModalConfig(),
+});
+```
+
+The `getDefaultWalletsModalConfig` function provides default configuration options for the Wallet Connection Modal, such as:
+
+- The wallets to display or pin
+- Links to the terms of service and privacy policy
+
+For more details, refer to the `connect-wallet-modal` package's [README](packages/connect-wallet-modal/README.md)
+
+### WalletsListEthereum
+
+`WalletsListEthereum` is a default list of wallet adapters.  
+A wallet adapter is a package dedicated to a specific wallet.  
+Each adapter exports an object that specifies the wallet's name,
+its icon, how the wallet should be detected and connected, additional metadata and configuration.
+
+You can import the default `WalletsListEthereum`, or create a custom list of wallet adapters by including only the wallets you need and excluding the unnecessary ones.
+
+### How to Hide a Wallet
+
+To hide a wallet from the Wallet Connection Modal, use the `walletsShown` prop, which is included by default in the configuration returned by `...getDefaultWalletsModalConfig()`.
+
+The `walletsShown` prop is an array of wallet IDs. Simply remove the desired wallet ID from this array to hide the corresponding wallet in the modal.
+
+### Passing Configurations
+
+- Pass the `wagmiConfig` and `reefKnotConfig` objects from `getDefaultConfig` to the `config` props of their respective Context Providers.
+- Pass the `walletsModalConfig` object to the `<ReefKnotWalletsModal>` component.
+
+#### Dark Theme
+
+To enable a dark theme for the Wallet Connection Modal, use the `darkThemeEnabled` prop on the `<ReefKnotWalletsModal>` component.
+
+### Triggering the Wallet Connection Modal
+
+To open the Wallet Connection Modal, use the `useConnect` hook provided by Reef Knot.
+
+#### Import the Hook
+
+```typescript
+import { useConnect } from 'reef-knot/core-react';
+```
+
+#### Use the Hook
+
+Call the `useConnect` hook to get the `connect` callback:
+
+```typescript
+const { connect } = useConnect();
+```
+
+#### How `connect` Works
+
+The `connect` callback determines the current environment (e.g., desktop browser, mobile wallet app, iframe) and behaves accordingly:
+
+- If the dApp is opened inside a wallet's dApp browser, it attempts an automatic connection with this specific wallet.
+- Otherwise, it opens the Wallet Connection Modal for manual wallet selection.
+
+---
+
+## Troubleshooting
+
+### NoSSRWrapper
+
+If you encounter errors during server-side rendering, you may need to wrap certain parts of your code in a `NoSSRWrapper`. This wrapper disables server-side rendering for the specified area, helping to avoid SSR-related issues.
+Here is an example of what the `NoSSRWrapper` code might look like:
+
+```ts
+import React from 'react';
+import dynamic from 'next/dynamic';
+
+const NoSSRWrapper = (props: { children: React.ReactNode }) => (
+  <>{props.children}</>
+);
+
+export default dynamic(() => Promise.resolve(NoSSRWrapper), {
+  ssr: false,
+});
+```
+
+This restriction comes from early versions of wagmi library, which had limitations with SSR.
+It is a known issue, and we are working on removing the need for such wrapping.
+
+---
 
 ## Development
 
 ### Project structure
+
 - The project is organized as monorepo using [turborepo](https://turbo.build/repo) tools.
 - The `packages` dir contains packages, most of them are published to npm, but some are not.
-- The `apps` dir contains an example application, which uses the packages to demonstrate wallets connection. 
+- The `apps` dir contains an example application, which uses the packages to demonstrate wallets connection.
 
 ### Initial setup
+
 Install the dependencies, build everything:
+
 ```
-yarn install & yarn build 
+yarn install & yarn build
 ```
 
 ### Commands
+
 - `yarn dev` runs the `dev` script for all apps and packages.
-Usually apps are launched using `next dev` and packages are built using rollup with `--watch` flag, which rebuilds the bundle when its source files change on disk.
+  Usually apps are launched using `next dev` and packages are built using rollup with `--watch` flag, which rebuilds the bundle when its source files change on disk.
 - `yarn build` - Build all apps and packages.
 - `yarn build-apps` - Build apps only.
 - `yarn build-packages` - Build packages only.
 
 ### How to release a new version
+
 The [Changesets](https://github.com/changesets/changesets) tool is used for publishing new versions.  
 To release a new version, see [the instruction in the docs](docs/how-to-release.md).

docs/migration-guide.md

@@ -0,0 +1,132 @@
+# Migration guide from 0.x to the current version
+
+This guide provides detailed instructions and best practices for migrating your project from Reef Knot v0.x to the current version.
+It covers breaking changes, updated dependencies, and new component implementations to ensure a smooth transition.
+Use this guide to update your project efficiently while leveraging the latest features and improvements in Reef Knot.
+
+If you're looking for instructions to install Reef Knot from scratch, refer to the [README](README.md#installation).
+
+#### Note about wagmi library
+
+Before you begin, you may want to familiarize yourself with the following:
+
+- [wagmi library](https://wagmi.sh/)
+- [viem library](https://viem.sh/)
+
+Historically, Reef Knot v0.x-v1.x utilized both `web3-react` v6 and `wagmi` v0.x at the same time.
+Some wallets relied on the legacy `web3-react` code, while others were transitioned to `wagmi`.
+
+The current version of Reef Knot uses `wagmi` for all wallet connections.
+
+## Dependencies
+
+### 1. Update TS to v5
+
+`wagmi` types require TypeScript >=5.0.4. For more details, refer to the [wagmi TypeScript documentation](https://wagmi.sh/react/typescript).
+
+Since Reef Knot also depends on TypeScript v5, you will need to upgrade your TypeScript version if your dApp is currently using TypeScript v4.
+
+### 2. Update wagmi to v2, add viem, @tanstack/react-query
+
+There is a chance, that your app is using wagmi v0.12.x, which is not maintained anymore.
+
+The current version of Reef Knot is built on wagmi v2.x.
+There were a lot of [breaking changes between 0.x and 1.x versions](https://1.x.wagmi.sh/react/migration-guide),
+and then [between 1.x and 2.x](https://wagmi.sh/react/guides/migrate-from-v1-to-v2).
+
+The good news is that most of this changes were handled inside reef-knot and doesn't require a lot of actions on a dApp side.
+
+Use [manual installation instructions](https://wagmi.sh/react/getting-started#manual-installation) from wagmi docs for details.
+
+Basically, you will need to:
+
+1. Update the `wagmi` dependency to the latest 2.x version
+2. Add `viem` v2.x and `@tanstack/react-query` v5.x
+3. Update config for `WagmiProvider`
+
+### 3. Remove web3-react dependency
+
+web3-react is a library similar to wagmi, previously used to manage wallet connections in reef-knot.
+
+At one point, Reef Knot partially used web3-react for some wallets and wagmi for others.
+However, Reef Knot has since transitioned to using wagmi exclusively for all wallet connections.
+
+As a result, the web3-react dependency is no longer needed and should be completely removed from your project.
+
+### 4. React v18
+
+Reef Knot v0.x was built using React v17. The current version of Reef Knot is now based on React v18.
+If your app is using React v17, you will likely need to upgrade it to React v18.
+
+### 5. Update reef-knot package
+
+Use the latest available version – v7.x at the moment of writing.
+
+### 6. reef-knot subpackages
+
+Ensure that the project depends on 'reef-knot' package only and there are no dependencies on '@reef-knot/\*' subpackages.
+
+## Code changes
+
+### 1. reef-knot imports
+
+Ensure your code does not contain direct imports from Reef Knot subpackages. If found, simply remove the `@` sign to correct the import.
+
+**BAD:**
+
+```ts
+import { useWeb3 } from '@reef-knot/web3-react';
+```
+
+**GOOD:**
+
+```ts
+import { useWeb3 } from 'reef-knot/web3-react';
+```
+
+### 2. Remove deprecated code
+
+1. Search your project's code for the `WalletsModalForEth` component and remove it completely, as the Wallet Connection Modal has been updated.
+2. Search your project's code for the `ProviderWeb3` React Context Provider and remove it if it exists.
+3. If your app depends on reef-knot v2-v5, then remove the `ReefKnot` React Context Provider and the `AutoConnect` component.
+
+### 3. Set Up Reef Knot
+
+Follow the latest [installation instructions](README.md#installation) to properly set up the updated version of Reef Knot in your project.
+
+## Other Notes
+
+### Legacy Lido JS SDK
+
+The Lido JS SDK is a deprecated legacy web3 development kit for Lido projects.
+
+If your app still relies on it, you will need to configure its `ProviderSDK` React Context Provider.
+This configuration may require adjustments due to the update to wagmi v2.
+
+For an example of how to configure `ProviderSDK` in combination with wagmi v2 and ethers.js,
+refer to the Lido ETH Stake Widget: [ProviderSDK Configuration Example](https://github.com/lidofinance/ethereum-staking-widget/blob/c5bac490f92826abe9c12a34e751b004eca679ee/modules/web3/web3-provider/sdk-legacy.tsx).
+
+### NoSSRWrapper
+
+If you are using reef-knot v0.x, then, most likely, your code already has some NoSSRWrapper usage.
+This is still needed. For the additional info, see the [NoSSRWrapper paragraph in README](README.md#nossrwrapper).
+
+### useWeb3 hook deprecation
+
+The `useWeb3` hook provides various details about the connected wallet.
+There is a high chance that it is used extensively throughout your application.
+
+Previously, it played a crucial role by returning information from either the web3-react or wagmi libraries,
+depending on the connected wallet. However, since the web3-react library has been removed from Reef Knot,
+the current version is based solely on wagmi.
+
+As a result, the useWeb3 hook now acts as a redundant proxy for wagmi hooks. While it will continue to function,
+it is recommended to replace it with standard wagmi hooks to avoid unnecessary abstractions.
+
+### Additional references
+
+The most significant changes were introduced during the v2 and v6 updates.
+You can use these PRs as references for updating Reef Knot versions:
+
+- [Update to v2](https://github.com/lidofinance/ethereum-staking-widget/pull/265/files)
+- [Update to v6](https://github.com/lidofinance/reef-knot/pull/183/files)