Skip to content

Commit 8d96ebc

Browse files
ihsrahamihsraham
committed
Add migration guides for Web3Auth v7/v8 to v10
Introduced detailed migration guides for upgrading from Web3Auth modal v7 and v8 to v10, covering custom authentication, external wallets, wallet services, and whitelabeling. Updated sidebars to include new guides and provided step-by-step instructions and code samples to assist developers in transitioning to the unified v10 SDK and dashboard-centric configuration.
1 parent 96a0a0b commit 8d96ebc

14 files changed

+1958
-90
lines changed

‎docs/migration-guides/modal-v7-to-v10-custom-authentication.mdx‎

Lines changed: 184 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,184 @@
1+
---
2+
title: Migrating Custom Authentication from v7 to v10
3+
description:
4+
Comprehensive guide for migrating Web3Auth custom authentication configurations from verifiers to
5+
connections in v10.
6+
sidebar_label: Custom Authentication Migration
7+
---
8+
9+
import Tabs from "@theme/Tabs";
10+
import TabItem from "@theme/TabItem";
11+
12+
# Web3Auth v10 Custom Authentication Migration Guide
13+
14+
This guide focuses specifically on migrating custom authentication configurations from Web3Auth v7
15+
to v10. This covers the transition from "Verifiers" to "Connections" and "Grouped Connections". This
16+
is a supplementary guide to the main [v7 to v10 migration guide](./modal-v7-to-v10.mdx).
17+
18+
## Overview
19+
20+
In v7, custom authentication used `verifier` and `aggregate verifier` configurations for linking
21+
accounts from different social providers to the same underlying user wallet. In v10, this system is
22+
streamlined with "Connections" and "Grouped Connections" configured on the Web3Auth Developer
23+
Dashboard, significantly reducing client-side code complexity.
24+
25+
## Key Changes & Mapping
26+
27+
### 1. Single Verifiers (v7) to Single Connections (v10)
28+
29+
Single verifiers in v7 become connections in v10:
30+
31+
```typescript
32+
// remove-start
33+
const openloginAdapter = new OpenloginAdapter({
34+
adapterSettings: {
35+
loginConfig: {
36+
google: {
37+
verifier: "YOUR_GOOGLE_VERIFIER_NAME", // v7 verifier name
38+
typeOfLogin: "google",
39+
clientId: "YOUR_GOOGLE_CLIENT_ID.apps.googleusercontent.com",
40+
},
41+
},
42+
},
43+
});
44+
45+
web3auth.configureAdapter(openloginAdapter);
46+
await web3auth.initModal();
47+
// remove-end
48+
49+
// add-start
50+
const web3AuthOptions: Web3AuthOptions = {
51+
clientId: "YOUR_CLIENT_ID",
52+
// ...
53+
modalConfig: {
54+
connectors: {
55+
[WALLET_CONNECTORS.AUTH]: {
56+
loginMethods: {
57+
google: {
58+
name: "Google Login",
59+
authConnectionId: "YOUR_GOOGLE_AUTH_CONNECTION_ID", // v10 connection ID
60+
},
61+
},
62+
},
63+
},
64+
},
65+
};
66+
67+
// OR v10: connectTo with a single connection
68+
// await web3auth.connectTo(WALLET_CONNECTORS.AUTH, {
69+
// authConnection: AUTH_CONNECTION.GOOGLE,
70+
// authConnectionId: "YOUR_GOOGLE_AUTH_CONNECTION_ID",
71+
// });
72+
// add-end
73+
```
74+
75+
#### Action
76+
77+
Your existing v7 single verifiers will be automatically migrated to "Connections" on the new
78+
Web3Auth Developer Dashboard. Locate your migrated Connection, note its `authConnectionId`, and use
79+
this ID in your v10 client code (`modalConfig` or `connectTo`). Remove any v7 `OpenloginAdapter`
80+
configuration previously used for this verifier.
81+
82+
### 2. Aggregate Verifiers (v7) to Grouped Connections (v10)
83+
84+
Aggregate verifiers in v7 become grouped connections in v10:
85+
86+
```typescript
87+
// remove-start
88+
const openloginAdapter = new OpenloginAdapter({
89+
adapterSettings: {
90+
loginConfig: {
91+
google: {
92+
// Part of an aggregate verifier
93+
verifier: "MY_AGGREGATE_VERIFIER_NAME", // Main aggregate verifier name
94+
verifierSubIdentifier: "google-sub-verifier", // Specific sub-verifier for Google
95+
typeOfLogin: "google",
96+
clientId: "YOUR_GOOGLE_CLIENT_ID.apps.googleusercontent.com",
97+
},
98+
jwt_email: {
99+
// Another part of the same aggregate verifier
100+
verifier: "MY_AGGREGATE_VERIFIER_NAME",
101+
verifierSubIdentifier: "custom-jwt-sub-verifier",
102+
typeOfLogin: "jwt",
103+
clientId: "YOUR_CUSTOM_JWT_CLIENT_ID", // Not always applicable for JWT
104+
jwtParameters: {
105+
/* ... JWT specific params like domain, verifierIdField ... */
106+
},
107+
},
108+
},
109+
},
110+
});
111+
112+
web3auth.configureAdapter(openloginAdapter);
113+
await web3auth.initModal();
114+
// remove-end
115+
116+
// add-start
117+
const web3AuthOptions: Web3AuthOptions = {
118+
clientId: "YOUR_CLIENT_ID",
119+
// ...
120+
modalConfig: {
121+
connectors: {
122+
[WALLET_CONNECTORS.AUTH]: {
123+
loginMethods: {
124+
google: {
125+
name: "Google Login",
126+
authConnectionId: "YOUR_INDIVIDUAL_GOOGLE_CONNECTION_ID", // ID of the individual Google connection
127+
groupedAuthConnectionId: "YOUR_GROUPED_CONNECTION_ID_FROM_DASHBOARD", // ID of the group
128+
},
129+
myCustomJWT: {
130+
name: "Login with Corp Email",
131+
authConnectionId: "YOUR_INDIVIDUAL_CUSTOM_JWT_CONNECTION_ID",
132+
groupedAuthConnectionId: "YOUR_GROUPED_CONNECTION_ID_FROM_DASHBOARD",
133+
},
134+
},
135+
},
136+
},
137+
},
138+
};
139+
140+
// OR v10: connectTo with a grouped connection
141+
// For Google login part of the group:
142+
// await web3auth.connectTo(WALLET_CONNECTORS.AUTH, {
143+
// authConnection: AUTH_CONNECTION.GOOGLE,
144+
// authConnectionId: "YOUR_INDIVIDUAL_GOOGLE_CONNECTION_ID",
145+
// groupedAuthConnectionId: "YOUR_GROUPED_CONNECTION_ID_FROM_DASHBOARD",
146+
// });
147+
148+
// For Custom JWT login part of the group:
149+
// const idToken = await getMyIdToken();
150+
// await web3auth.connectTo(WALLET_CONNECTORS.AUTH, {
151+
// authConnection: AUTH_CONNECTION.CUSTOM,
152+
// idToken: idToken,
153+
// authConnectionId: "YOUR_INDIVIDUAL_CUSTOM_JWT_CONNECTION_ID",
154+
// groupedAuthConnectionId: "YOUR_GROUPED_CONNECTION_ID_FROM_DASHBOARD",
155+
// });
156+
// add-end
157+
```
158+
159+
You first create individual "Connections" on the dashboard for each auth provider (e.g., one for
160+
Google, one for your custom JWT). Then, you create a "Grouped Connection" on the dashboard,
161+
selecting the individual connections you want to group.
162+
163+
#### Action
164+
165+
1. Your existing v7 Aggregate Verifiers (and their sub-verifiers) will be automatically migrated to
166+
the new v10 dashboard. They will appear as individual "Connections" that are part of a "Grouped
167+
Connection".
168+
2. On the v10 dashboard, locate your migrated Grouped Connection. Note its
169+
`groupedAuthConnectionId`.
170+
3. For each login method within that group, find the corresponding individual migrated Connection
171+
and note its specific `authConnectionId`.
172+
4. Update your v10 client code to use both the `groupedAuthConnectionId` (for the group) and the
173+
specific `authConnectionId` (for the particular login method being invoked) in `modalConfig` or
174+
`connectTo` calls. The v7 `verifierSubIdentifier` is no longer used in the client.
175+
176+
## Summary
177+
178+
This dashboard-centric approach, with automatic migration of existing verifiers, simplifies
179+
client-side logic and provides a more robust way to manage authentication methods.
180+
181+
## Next Steps
182+
183+
Return to the main [v7 to v10 migration guide](./modal-v7-to-v10.mdx) to continue with other
184+
migration aspects like method name changes and initialization updates.

‎docs/migration-guides/modal-v7-to-v10-external-wallets.mdx‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
---
2+
title: Migrating External Wallets from v7 to v10
3+
description: Comprehensive guide for migrating Web3Auth external wallet adapters from v7 to v10.
4+
sidebar_label: External Wallet Adapters Migration
5+
---
6+
7+
import Tabs from "@theme/Tabs";
8+
import TabItem from "@theme/TabItem";
9+
10+
# Web3Auth v10 External Wallet Adapters Migration Guide
11+
12+
This guide focuses specifically on migrating external wallet adapter configurations from Web3Auth v7
13+
to v10. This is a supplementary guide to the main
14+
[v7 to v10 migration guide](./modal-v7-to-v10.mdx).
15+
16+
## Overview
17+
18+
In v7, external wallets required manual adapter configuration. V10 simplifies this by using MIPD
19+
(Multiple Injected Provider Discovery) to automatically detect and provide access to external
20+
wallets without manual setup.
21+
22+
## Migration Steps
23+
24+
### External Wallet Adapter Migration
25+
26+
```typescript
27+
// remove-start
28+
// Individual wallet adapters in v7
29+
import { MetamaskAdapter } from "@web3auth/metamask-adapter";
30+
import { PhantomAdapter } from "@web3auth/phantom-adapter";
31+
import {
32+
WalletConnectV2Adapter,
33+
getWalletConnectV2Settings,
34+
} from "@web3auth/wallet-connect-v2-adapter";
35+
import { WalletConnectModal } from "@walletconnect/modal";
36+
37+
// Manual adapter configuration
38+
const metamaskAdapter = new MetamaskAdapter();
39+
web3auth.configureAdapter(metamaskAdapter);
40+
41+
const phantomAdapter = new PhantomAdapter();
42+
web3auth.configureAdapter(phantomAdapter);
43+
44+
const defaultWcSettings = await getWalletConnectV2Settings("eip155", ["1"], "PROJECT_ID");
45+
const walletConnectV2Adapter = new WalletConnectV2Adapter({
46+
adapterSettings: { qrcodeModal: WalletConnectModal, ...defaultWcSettings.adapterSettings },
47+
loginSettings: { ...defaultWcSettings.loginSettings },
48+
});
49+
web3auth.configureAdapter(walletConnectV2Adapter);
50+
51+
await web3auth.initModal();
52+
// remove-end
53+
54+
// add-start
55+
// All external wallets are automatically detected via MIPD
56+
// No manual adapter configuration needed
57+
await web3auth.init();
58+
// add-end
59+
```
60+
61+
## Key Changes
62+
63+
- **Package Removal**: Remove all external wallet adapter packages
64+
- **MIPD Integration**: External wallets are automatically detected using MIPD (Multiple Injected
65+
Provider Discovery)
66+
- **No Configuration**: No need to manually configure or register external adapters
67+
- **WalletConnect Support**: WalletConnect-compatible wallets are automatically available
68+
69+
## Package Removal
70+
71+
Remove these deprecated packages from your project:
72+
73+
```bash npm2yarn
74+
# Remove all external wallet adapter packages
75+
npm uninstall @web3auth/metamask-adapter @web3auth/phantom-adapter @web3auth/solflare-adapter @web3auth/wallet-connect-v2-adapter @walletconnect/modal
76+
```
77+
78+
## How It Works in v10
79+
80+
V10 uses MIPD (Multiple Injected Provider Discovery) to automatically detect injected wallets in the
81+
browser. When users attempt to connect, they'll see:
82+
83+
1. **Detected Wallets**: All installed browser extension wallets
84+
2. **WalletConnect**: For mobile and other wallet connections
85+
3. **Social Logins**: Built-in Web3Auth authentication methods
86+
87+
No configuration needed - everything works out of the box!
88+
89+
## Next Steps
90+
91+
Return to the main [v7 to v10 migration guide](./modal-v7-to-v10.mdx) to continue with other
92+
migration aspects.

‎docs/migration-guides/modal-v7-to-v10-wallet-services.mdx‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
---
2+
title: Migrating Wallet Services from v7 to v10
3+
description: Comprehensive guide for migrating Web3Auth Wallet Services plugin from v7 to v10.
4+
sidebar_label: Wallet Services Migration
5+
---
6+
7+
import Tabs from "@theme/Tabs";
8+
import TabItem from "@theme/TabItem";
9+
10+
# Web3Auth v10 Wallet Services Migration Guide
11+
12+
This guide focuses specifically on migrating Wallet Services functionality from Web3Auth v7 to v10.
13+
This is a supplementary guide to the main [v7 to v10 migration guide](./modal-v7-to-v10.mdx).
14+
15+
## Overview
16+
17+
In v7, Wallet Services (Checkout, Swap, WalletConnect Scanner, Embedded Wallet UI) required
18+
installing and configuring a separate `@web3auth/wallet-services-plugin` package. V10 integrates
19+
these services directly into the main SDK.
20+
21+
## Migration Steps
22+
23+
### Plugin Access Migration
24+
25+
```typescript
26+
// remove-start
27+
import { WalletServicesPlugin } from "@web3auth/wallet-services-plugin";
28+
29+
const walletServicesPlugin = new WalletServicesPlugin({
30+
// plugin configuration options
31+
});
32+
33+
web3auth.addPlugin(walletServicesPlugin);
34+
await web3auth.initModal();
35+
36+
// Usage
37+
await walletServicesPlugin.showWalletUi();
38+
await walletServicesPlugin.showCheckout();
39+
await walletServicesPlugin.showWalletConnectScanner();
40+
// remove-end
41+
42+
// add-start
43+
import { EVM_PLUGINS } from "@web3auth/modal";
44+
45+
await web3auth.init();
46+
47+
// Get the built-in wallet services plugin
48+
const walletServicesPlugin = web3auth.getPlugin(EVM_PLUGINS.WALLET_SERVICES);
49+
50+
// Usage (methods now require { show: true } parameter)
51+
await walletServicesPlugin.showWalletUi({ show: true });
52+
await walletServicesPlugin.showCheckout({ show: true });
53+
await walletServicesPlugin.showSwap({ show: true });
54+
await walletServicesPlugin.showWalletConnectScanner({ show: true });
55+
// add-end
56+
```
57+
58+
## Key Changes
59+
60+
- **Package Removal**: Remove `@web3auth/wallet-services-plugin` package
61+
- **Built-in Integration**: Wallet Services are now automatically included in the main SDK
62+
- **Plugin Access**: Use `web3auth.getPlugin(EVM_PLUGINS.WALLET_SERVICES)` to access functionality
63+
- **Parameter Updates**: Methods now require a `{ show: true }` parameter
64+
65+
## Package Removal
66+
67+
Remove the deprecated package from your project:
68+
69+
```bash npm2yarn
70+
npm uninstall @web3auth/wallet-services-plugin
71+
```
72+
73+
## Next Steps
74+
75+
Return to the main [v7 to v10 migration guide](./modal-v7-to-v10.mdx) to continue with other
76+
migration aspects.

0 commit comments

Comments
 (0)