Skip to content

Commit 443d757

Browse files
ihsrahamihsraham
authored
Merge pull request #1144 from Web3Auth/new-migration-guide
Add detailed v9 to v10 migration guides for Web3Auth
2 parents 8b8d479 + ed05649 commit 443d757

18 files changed

+2651
-739
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)