Skip to content

Commit 96a0a0b

Browse files
ihsrahamihsraham
committed
Add detailed v9 to v10 migration guides for Web3Auth
Introduced new migration guides covering custom authentication, React & Vue integration, Smart Accounts, and whitelabeling for Web3Auth v9 to v10. Updated the main migration guide to reference these new documents and clarified migration steps for chain configuration, MFA, and method renames. These additions provide step-by-step instructions and code examples to help developers transition to the unified v10 SDK and dashboard-centric configuration.
1 parent d938d98 commit 96a0a0b

File tree

5 files changed

+716
-672
lines changed

5 files changed

+716
-672
lines changed

‎docs/migration-guides/modal-v9-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 v9 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 v9
15+
to v10. This covers the transition from "Verifiers" to "Connections" and "Grouped Connections". This
16+
is a supplementary guide to the main [v9 to v10 migration guide](./modal-v9-to-v10.mdx).
17+
18+
## Overview
19+
20+
In v9, 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 (v9) to Single Connections (v10)
28+
29+
Single verifiers in v9 become connections in v10:
30+
31+
```typescript
32+
// remove-start
33+
const authAdapter = new AuthAdapter({
34+
adapterSettings: {
35+
loginConfig: {
36+
google: {
37+
verifier: "YOUR_GOOGLE_VERIFIER_NAME", // v9 verifier name
38+
typeOfLogin: "google",
39+
clientId: "YOUR_GOOGLE_CLIENT_ID.apps.googleusercontent.com",
40+
},
41+
},
42+
},
43+
});
44+
45+
// OR when using connectTo:
46+
// await web3auth.connectTo("auth", {
47+
// verifier: "YOUR_GOOGLE_VERIFIER_NAME",
48+
// // ...
49+
// });
50+
// remove-end
51+
52+
// add-start
53+
const web3AuthOptions: Web3AuthOptions = {
54+
clientId: "YOUR_CLIENT_ID",
55+
// ...
56+
modalConfig: {
57+
connectors: {
58+
[WALLET_CONNECTORS.AUTH]: {
59+
loginMethods: {
60+
google: {
61+
name: "Google Login",
62+
authConnectionId: "YOUR_GOOGLE_AUTH_CONNECTION_ID", // v10 connection ID
63+
},
64+
},
65+
},
66+
},
67+
},
68+
};
69+
70+
// OR v10: connectTo with a single connection
71+
// await web3auth.connectTo(WALLET_CONNECTORS.AUTH, {
72+
// authConnection: AUTH_CONNECTION.GOOGLE,
73+
// authConnectionId: "YOUR_GOOGLE_AUTH_CONNECTION_ID",
74+
// });
75+
// add-end
76+
```
77+
78+
#### Action
79+
80+
Your existing v9 single verifiers will be automatically migrated to "Connections" on the new
81+
Web3Auth Developer Dashboard. Locate your migrated Connection, note its `authConnectionId`, and use
82+
this ID in your v10 client code (`modalConfig` or `connectTo`). Remove any v9 `AuthAdapter`
83+
configuration previously used for this verifier.
84+
85+
### 2. Aggregate Verifiers (v9) to Grouped Connections (v10)
86+
87+
Aggregate verifiers in v9 become grouped connections in v10:
88+
89+
```typescript
90+
// remove-start
91+
const authAdapter = new AuthAdapter({
92+
adapterSettings: {
93+
loginConfig: {
94+
google: {
95+
// Part of an aggregate verifier
96+
verifier: "MY_AGGREGATE_VERIFIER_NAME", // Main aggregate verifier name
97+
verifierSubIdentifier: "google-sub-verifier", // Specific sub-verifier for Google
98+
typeOfLogin: "google",
99+
clientId: "YOUR_GOOGLE_CLIENT_ID.apps.googleusercontent.com",
100+
},
101+
jwt_email: {
102+
// Another part of the same aggregate verifier
103+
verifier: "MY_AGGREGATE_VERIFIER_NAME",
104+
verifierSubIdentifier: "custom-jwt-sub-verifier",
105+
typeOfLogin: "jwt",
106+
clientId: "YOUR_CUSTOM_JWT_CLIENT_ID", // Not always applicable for JWT
107+
jwtParameters: {
108+
/* ... JWT specific params like domain, verifierIdField ... */
109+
},
110+
},
111+
},
112+
},
113+
});
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 v9 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 v9 `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 [v9 to v10 migration guide](./modal-v9-to-v10.mdx) to continue with other
184+
migration aspects like MFA configurations and method renames.

‎docs/migration-guides/modal-v9-to-v10-react-vue.mdx‎

Lines changed: 206 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,206 @@
1+
---
2+
title: Migrating React and Vue Applications from v9 to v10
3+
description:
4+
Comprehensive guide for migrating Web3Auth React and Vue applications from v9 to v10 with hooks
5+
and composables.
6+
sidebar_label: React & Vue Migration
7+
---
8+
9+
import Tabs from "@theme/Tabs";
10+
import TabItem from "@theme/TabItem";
11+
12+
# Web3Auth v10 React & Vue Migration Guide
13+
14+
This guide focuses specifically on migrating React and Vue applications from Web3Auth v9 to v10.
15+
This is a supplementary guide to the main [v9 to v10 migration guide](./modal-v9-to-v10.mdx).
16+
17+
For general migration points (chain configuration, MFA, method renames, etc.), please refer to the
18+
main migration guide.
19+
20+
## Migrating a React Application
21+
22+
This section focuses on changes specific to migrating a Web3Auth v9 React application to v10 using
23+
`@web3auth/modal/react`.
24+
25+
### React Hooks Path and WalletServicesPlugin Updates
26+
27+
Previously, React hooks were at `@web3auth/modal-react-hooks`. Now, they are consolidated and
28+
imported from `@web3auth/modal/react`. Even WalletServicesPlugin is now integrated into the hooks.
29+
Previously, it was a separate package named `@web3auth/wallet-services-plugin-react-hooks`.
30+
31+
The `Web3AuthProvider` component remains essential for initializing the Web3Auth SDK and providing
32+
its context. Key changes include:
33+
34+
- **Import Path**: `Web3AuthProvider` is imported from `@web3auth/modal/react`.
35+
- **Configuration Prop**: `Web3AuthProvider` in v10 typically takes a single `config` prop. This
36+
`config` object (e.g., `web3AuthContextConfig`) will contain your `web3AuthOptions` and any
37+
client-side SDK configurations.
38+
- **Dashboard Configuration**: Many configurations (like chain details for standard EVM chains, and
39+
verifier/connection settings) are now primarily managed through the Web3Auth Developer Dashboard.
40+
41+
### v10 `Web3AuthProvider` and Hook Usage
42+
43+
`Web3AuthProvider` is configured with a `config` object, and all hooks are streamlined under
44+
`@web3auth/modal/react`.
45+
46+
```typescript title="main.tsx / index.tsx"
47+
import ReactDOM from "react-dom/client";
48+
import { Web3AuthProvider } from "@web3auth/modal/react"; // v10 import
49+
import web3AuthContextConfig from "./web3authContext"; // see context file below
50+
import App from "./App";
51+
52+
// Example with Wagmi, though not strictly necessary for Web3AuthProvider
53+
import { WagmiProvider } from "@web3auth/modal/react/wagmi";
54+
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
55+
const queryClient = new QueryClient();
56+
57+
58+
ReactDOM.createRoot(document.getElementById("root")!).render(
59+
<Web3AuthProvider config={web3AuthContextConfig}>
60+
<QueryClientProvider client={queryClient}>
61+
<WagmiProvider>
62+
<App />
63+
</WagmiProvider>
64+
</QueryClientProvider>
65+
</Web3AuthProvider>
66+
);
67+
```
68+
69+
```typescript title="web3authContext.ts"
70+
import { WEB3AUTH_NETWORK, Web3AuthOptions } from "@web3auth/modal"; // v10 modal options
71+
import { type Web3AuthContextConfig } from "@web3auth/modal/react"; // v10 context config type
72+
73+
const clientId = "YOUR_V10_CLIENT_ID"; // Get from https://dashboard.web3auth.io
74+
75+
const web3AuthContextConfig: Web3AuthContextConfig = {
76+
web3AuthOptions: {
77+
clientId,
78+
web3AuthNetwork: WEB3AUTH_NETWORK.SAPPHIRE_MAINNET,
79+
},
80+
};
81+
82+
export default web3AuthContextConfig;
83+
```
84+
85+
All hooks are now streamlined under `@web3auth/modal/react`:
86+
87+
```typescript title="App.tsx"
88+
import {
89+
useWeb3Auth,
90+
useWeb3AuthConnect,
91+
useWeb3AuthDisconnect,
92+
useIdentityToken,
93+
useWeb3AuthUser,
94+
useSwitchChain,
95+
useEnableMFA,
96+
useManageMFA,
97+
useWalletConnectScanner, // Wallet Services
98+
useWalletUI, // Wallet Services
99+
useCheckout, // Wallet Services
100+
useSwap, // Wallet Services
101+
useWalletServicesPlugin, // Wallet Services
102+
} from "@web3auth/modal/react";
103+
```
104+
105+
### React Hook Structure
106+
107+
The new hook structure is more granular:
108+
109+
- **Core Web3Auth:**
110+
- `useWeb3Auth`: Core hook for initialization status and overall SDK state.
111+
- **Authentication:**
112+
- `useWeb3AuthConnect`: Handles connection.
113+
- `useWeb3AuthDisconnect`: Manages disconnection.
114+
- **Identity:**
115+
- `useIdentityToken`: Retrieves identity tokens.
116+
- `useWeb3AuthUser`: Accesses authenticated user's information.
117+
- **Blockchain:**
118+
- `useSwitchChain`: Allows switching networks.
119+
- **MFA:**
120+
- `useEnableMFA`: Enables MFA.
121+
- `useManageMFA`: Manages MFA settings.
122+
- **Wallet Services Plugin (now integrated):**
123+
- `useWalletServicesPlugin`: Hook to access the Wallet Services Plugin context.
124+
- `isPluginConnected`: `boolean`
125+
- `showWalletConnectScanner(params?)`: `Promise<void>`
126+
- `showCheckout(params?)`: `Promise<void>`
127+
- `showWalletUI(params?)`: `Promise<void>`
128+
- `showSwap(params?)`: `Promise<void>`
129+
130+
Refer to the [React Modal SDK Hooks documentation](/docs/sdk/web/react/hooks) for the detailed SDK
131+
reference.
132+
133+
## Migrating a Vue Application
134+
135+
This section focuses on changes specific to migrating a Web3Auth v9 Vue application to v10 using
136+
`@web3auth/modal/vue`.
137+
138+
### Vue Composables Path and WalletServicesPlugin Updates
139+
140+
Previously, Vue composables were at `@web3auth/modal-vue-composables`. Now, they are consolidated
141+
and imported from `@web3auth/modal/vue`. WalletServicesPlugin functionality is also integrated into
142+
these composables, whereas previously with v9 it was imported via
143+
`@web3auth/wallet-services-plugin-vue-composables`.
144+
145+
### v10 Vue Composables Usage
146+
147+
All composables are now streamlined under `@web3auth/modal/vue`:
148+
149+
```typescript
150+
import {
151+
useWeb3Auth,
152+
useWeb3AuthConnect,
153+
useWeb3AuthDisconnect,
154+
useIdentityToken,
155+
useWeb3AuthUser,
156+
useSwitchChain,
157+
useEnableMFA,
158+
useManageMFA,
159+
useWalletConnectScanner, // Wallet Services
160+
useWalletUI, // Wallet Services
161+
useCheckout, // Wallet Services
162+
useSwap, // Wallet Services
163+
useWalletServicesPlugin, // Wallet Services
164+
} from "@web3auth/modal/vue";
165+
```
166+
167+
### Vue Composable Structure
168+
169+
The new composable structure is more granular:
170+
171+
- **Core Web3Auth:**
172+
- `useWeb3Auth`: Core composable for Web3Auth initialization and state management.
173+
- **Authentication:**
174+
- `useWeb3AuthConnect`: Handles Web3Auth connection processes.
175+
- `useWeb3AuthDisconnect`: Manages disconnection from Web3Auth.
176+
- **Identity:**
177+
- `useIdentityToken`: Retrieves and manages identity tokens.
178+
- `useWeb3AuthUser`: Provides access to the authenticated user's information.
179+
- **Blockchain:**
180+
- `useSwitchChain`: Allows switching between different blockchain networks.
181+
- **MFA:**
182+
- `useEnableMFA`: Enables Multi-Factor Authentication (MFA) for enhanced security.
183+
- `useManageMFA`: Provides functionality to manage MFA settings.
184+
- **Wallet Services Plugin (now integrated):**
185+
- `useWalletServicesPlugin`: Composable to access the Wallet Services Plugin context and its
186+
functions.
187+
- `useWalletConnectScanner`: Integrates WalletConnect scanner functionality.
188+
- `useWalletUI`: Manages wallet UI components and user interactions.
189+
- `useCheckout`: Facilitates cryptocurrency checkout processes.
190+
- `useSwap`: Enables token swapping capabilities.
191+
192+
Please refer to the [Vue Modal SDK documentation](/docs/sdk/web/vue/) for the SDK reference.
193+
194+
## Package Removal
195+
196+
When migrating React or Vue applications, ensure you remove these deprecated packages:
197+
198+
- `@web3auth/modal-react-hooks` (for React users)
199+
- `@web3auth/modal-vue-composables` (for Vue users)
200+
- `@web3auth/wallet-services-plugin-react-hooks` (for React users)
201+
- `@web3auth/wallet-services-plugin-vue-composables` (for Vue users)
202+
203+
## Next Steps
204+
205+
Return to the main [v9 to v10 migration guide](./modal-v9-to-v10.mdx) to continue with other
206+
migration aspects like MFA configurations, method renames, and chain configuration changes.

0 commit comments

Comments
 (0)