V10 migration guide - modal added

docs/migration-guides/modal-v9-to-v10.mdx

@@ -0,0 +1,273 @@
+---
+title: PnP Modal SDK - v9 to v10
+description: "PnP Modal SDK - v9 to v10 | Documentation - Web3Auth"
+sidebar_label: v9 to v10
+---
+
+This migration guide provides steps for upgrading from version v9 to v10 of the Web3Auth PnP Modal SDK. Version 10 introduces a simpler architecture by eliminating verifiers and adapters from the frontend codebase, consolidating all configurations within the Web3Auth Developer Dashboard.
+
+## Breaking Changes
+
+### 1. `verifier` and `verifierSubIdentifier` replaced with `authConnectionId` and `groupedAuthConnectionId`
+
+In v9, aggregating social logins to return the same account (for the same user email) required using an aggregate verifier with `verifierSubIdentifier`:
+
+```ts title="v9 - Before"
+loginConfig: {
+  google: {
+    verifier: "aggregate-verifier",
+    verifierSubIdentifier: "w3a-google",
+    typeOfLogin: "google",
+    clientId: "<GOOGLE_CLIENT_ID>",
+  },
+  github: {
+    verifier: "aggregate-verifier",
+    verifierSubIdentifier: "w3a-github",
+    typeOfLogin: "github",
+    clientId: "<GITHUB_CLIENT_ID>",
+  },
+}
+```
+
+In v10, this logic is now abstracted to the dashboard. Use `authConnectionId` for each provider and group them using the new `groupedAuthConnectionId`:
+
+```ts title="v10 - After"
+modalConfig: {
+  connectors: {
+    [WALLET_CONNECTORS.AUTH]: {
+      label: "auth",
+      loginMethods: {
+        google: {
+          authConnection: AUTH_CONNECTION.GOOGLE,
+          authConnectionId: "w3a-google",
+          groupedAuthConnectionId: "group-main",
+        },
+        github: {
+          authConnection: AUTH_CONNECTION.GITHUB,
+          authConnectionId: "w3a-github",
+          groupedAuthConnectionId: "group-main",
+        },
+      },
+    },
+  },
+}
+```
+
+> ✅ This results in the same user account when logging in with Google or GitHub using the same email, no additional setup needed in code.
+
+---
+
+### 2. `adapters` are fully removed — use `connectors` instead
+
+In v9, adapters had to be manually configured:
+
+```ts title="v9 - Before"
+import { AuthAdapter } from "@web3auth/auth-adapter";
+
+const authAdapter = new AuthAdapter(adapterSettings);
+web3auth.configureAdapter(authAdapter);
+```
+
+In v10, connectors replace adapters entirely:
+
+```ts title="v10 - After"
+modalConfig: {
+  connectors: {
+    [WALLET_CONNECTORS.AUTH]: {
+      label: "auth",
+      loginMethods: {
+        google: {
+          authConnection: AUTH_CONNECTION.GOOGLE,
+          authConnectionId: "w3a-google",
+        },
+      },
+    },
+  },
+}
+```
+
+> ✅ No need to configure or import adapters anymore.
+
+---
+
+### 3. `privateKeyProvider` and `chainConfig` are deprecated
+
+In v9, you had to manually pass chain config and instantiate a private key provider:
+
+```ts title="v9 - Before"
+const chainConfig = getEvmChainConfig(chainId, clientId);
+const privateKeyProvider = new EthereumPrivateKeyProvider({ config: { chainConfig } });
+
+const web3auth = new Web3Auth({
+  clientId,
+  privateKeyProvider,
+  web3AuthNetwork: WEB3AUTH_NETWORK.SAPPHIRE_MAINNET,
+});
+```
+
+In v10, all chain settings are handled via the dashboard. These parameters are no longer required or accepted:
+
+```ts title="v10 - After"
+const web3auth = new Web3Auth({
+  clientId,
+  web3AuthNetwork: WEB3AUTH_NETWORK.SAPPHIRE_MAINNET,
+  modalConfig: {
+    connectors: {
+      [WALLET_CONNECTORS.AUTH]: {
+        label: "auth",
+        loginMethods: {
+          google: {
+            authConnection: AUTH_CONNECTION.GOOGLE,
+            authConnectionId: "w3a-google",
+          },
+        },
+      },
+    },
+  },
+});
+```
+
+> ✅ Cleaner setup, with all chain management handled through the dashboard.
+
+---
+
+### 4. Modal configuration is now part of the constructor
+
+In v9, you had to call `initModal()` and pass `modalConfig` separately:
+
+```ts title="v9 - Before"
+await web3auth.initModal({
+  modalConfig: {
+    [WALLET_ADAPTERS.AUTH]: {
+      loginMethods: {
+        google: {
+          name: "google",
+          showOnModal: true,
+        },
+      },
+    },
+  },
+});
+```
+
+In v10, the configuration is moved into the constructor. `initModal()` is still required but without parameters:
+
+```ts title="v10 - After"
+const web3auth = new Web3Auth({
+  clientId,
+  web3AuthNetwork: WEB3AUTH_NETWORK.SAPPHIRE_MAINNET,
+  modalConfig: {
+    connectors: {
+      [WALLET_CONNECTORS.AUTH]: {
+        label: "auth",
+        loginMethods: {
+          google: {
+            authConnection: AUTH_CONNECTION.GOOGLE,
+            authConnectionId: "w3a-google",
+          },
+        },
+      },
+    },
+  },
+});
+
+await web3auth.initModal();
+```
+
+> ✅ Setup is now centralized and more intuitive.
+
+---
+
+### 5. Changes to Modal Hooks (`useWeb3Auth`)
+
+In v9, you had to create a full `Web3AuthContextConfig` and pass `adapters`, `plugins`, and `privateKeyProvider`:
+
+```ts title="v9 - Before"
+const web3AuthContextConfig: Web3AuthContextConfig = {
+  web3AuthOptions: {
+    clientId,
+    web3AuthNetwork: WEB3AUTH_NETWORK.SAPPHIRE_MAINNET,
+    privateKeyProvider,
+  },
+  modalConfig: {
+    [WALLET_ADAPTERS.AUTH]: {
+      loginMethods: {
+        google: {
+          showOnModal: true,
+        },
+      },
+    },
+  },
+  adapters: [authAdapter],
+  plugins: [walletServicesPlugin],
+};
+```
+
+In v10, all complexity is removed. Just pass connectors directly inside `modalConfig`:
+
+```ts title="v10 - After"
+const web3AuthContextConfig: Web3AuthContextConfig = {
+  web3AuthOptions: {
+    clientId,
+    web3AuthNetwork: WEB3AUTH_NETWORK.SAPPHIRE_MAINNET,
+  },
+  modalConfig: {
+    connectors: {
+      [WALLET_CONNECTORS.AUTH]: {
+        label: "Social Login",
+        loginMethods: {
+          google: {
+            authConnection: AUTH_CONNECTION.GOOGLE,
+            authConnectionId: "w3a-google",
+          },
+        },
+      },
+    },
+  },
+};
+```
+
+> ✅ Fewer props, no adapters/plugins, and modal config becomes declarative.
+
+---
+
+
+### 6. `@web3auth/base` is deprecated — use `@web3auth/modal` instead
+
+In v9, imports were often split across `@web3auth/base`, `@web3auth/modal`, and other packages:
+
+```ts title="v9 - Before"
+import { Web3Auth } from "@web3auth/modal";
+import { WALLET_ADAPTERS, WEB3AUTH_NETWORK } from "@web3auth/base";
+```
+
+In v10, everything you need is available directly from `@web3auth/modal`. The `@web3auth/base` package is deprecated and should no longer be used:
+
+```ts title="v10 - After"
+import { Web3Auth, WALLET_CONNECTORS, WEB3AUTH_NETWORK, AUTH_CONNECTION } from "@web3auth/modal";
+```
+
+> ✅ Cleaner import structure — use `@web3auth/modal` for everything.
+
+---
+
+## Summary of Key Migration Steps
+
+| Feature              | v9                                  | v10                                        |
+| -------------------- | ----------------------------------- | ------------------------------------------ |
+| Verifier             | `verifier`, `verifierSubIdentifier` | ⛔ Removed, use `authConnectionId` instead |
+| Account Linking      | Manual via aggregate verifiers      | ✅ Automatic via `groupedAuthConnectionId` |
+| Adapter Setup        | Required (`AuthAdapter`, etc.)      | ⛔ Removed, use `connectors` only          |
+| Chain Configuration  | Required in code                    | ✅ Handled via dashboard                   |
+| Private Key Provider | Required                            | ⛔ No longer needed                        |
+| Modal Config Setup   | Inside `initModal()`                | ✅ Now in constructor                      |
+| Base Package Usage   | `@web3auth/base` + `@web3auth/modal`| ✅ Use only `@web3auth/modal`              |
+
+---
+
+For SDK reference and examples, check out:
+
+- [Web3Auth Docs](https://web3auth.io/docs/sdk/pnp/web/modal)
+- [Web3Auth Pnp Examples](https://github.com/web3auth/web3auth-pnp-examples)
+
+Need help? Reach out on [Web3Auth Community](https://web3auth.io/community)

sidebars.ts

@@ -1278,6 +1278,7 @@ const sidebars: SidebarsConfig = {
           type: "category",
           label: "Plug and Play Modal SDK",
           items: [
+            "migration-guides/modal-v9-to-v10",
             "migration-guides/modal-v8-to-v9",
             "migration-guides/modal-v7-to-v8",
             "migration-guides/modal-v6-to-v7",