Web3Auth Web

The SDK supports two primary authentication modes during the connection process:

1. connect-and-sign: connectTo() resolves only after both the connection and the authorization (signing) are complete. External wallets must complete the auth challenge and return a usable ID token.
2. connect-only: connectTo() resolves immediately after the connection step is successful, without triggering an unnecessary authentication challenge.

Ensure that switching between these modes across app reloads does not leave stale state and that failed authorization steps leave the connector in a recoverable state.

When working with Web3Auth hooks (specifically in React and Vue), ensure you are using the standardized error types and state behaviors to maintain consistency across @web3auth/modal and @web3auth/no-modal.

Key behavioral standards include:

• Error Types: Use WalletInitializationError.notReady() for missing-wallet errors in useSignMessage.
• Vue Error Handling: Use Web3Auth-style errors instead of plain Error objects in useWalletServicesPlugin.
• Connection Status: When checking connection status in WalletServicesContextProvider, use CONNECTED_STATUSES.includes() rather than checking for a single CONNECTED string.
• State Derivation: For Solana wallet accounts, prefer memoized derivation over useState + useEffect patterns.
• Loading/Error States: Ensure consistent ordering of loading and error states in useWalletConnectScanner.

When deciding where logic or integrations live, use this ownership model:

When integrating Web3Auth, it is important to understand which logic is shared across the ecosystem and which is specific to the Modal implementation.

Shared Logic (from @web3auth/no-modal)

Most core React hooks and Vue composables are shared implementations designed to work with the canonical shared context.

Local Logic (specific to @web3auth/modal)

The following are kept local to the Modal package to handle specific lifecycle and UI requirements:

The SDK supports rehydrating sessions from cached state. Validate the following:

Session Rehydration

• Auth: Rehydrates if the session is valid; triggers error path if expired.
• MetaMask/Injected: Rehydrates if wallet permission/access is still granted.
• WalletConnect: Rehydrates if the WC session still exists.
• Linked Accounts: If the active account is a linked external wallet, a reload should restore that linked account as active with the correct provider and chain.

Storage Backends

• Ensure state restoration works via localStorage, cookie-backed state (if used), and the initialState provided in the constructor.

Web3Auth uses two primary packages for integration: @web3auth/modal (Plug and Play Modal SDK) and @web3auth/no-modal (for custom UI implementations).

To ensure consistency, @web3auth/no-modal serves as the canonical source of truth for shared logic. Most core implementations for React hooks, Vue composables, Solana integrations, and x402 logic reside in no-modal.

@web3auth/modal acts as an API-compatible layer that:

1. Re-exports shared logic from no-modal via public entrypoints.
2. Provides thin adapters for modal-specific behaviors (e.g., specific Web3Auth class typing, MFA fields in Vue, or the zero-argument connect() flow).
3. Manages modal-specific provider wiring.

The x402 payment flow integrates middleware on the server with a specialized hook on the client:

1. Interception: The paymentMiddleware from @x402/express intercepts requests to protected routes.
2. Challenge: If the request lacks a valid X-PAYMENT header, the server responds with HTTP 402 and a JSON body containing payment instructions.
3. Client Payment: A client-side hook (like useX402Fetch) detects the 402, signs a micro-payment with the user's connected wallet, and retries the request with the X-PAYMENT header attached.
4. Verification: The x402 facilitator verifies the on-chain payment, allowing the server to deliver the protected resource.

Perform this minimum smoke test pass to ensure core functionality is stable:

1. Auth Flows: Social login and Email passwordless.
2. Wallet Connections: MetaMask connect and WalletConnect v2 (test both successful QR connection and cancellation).
3. Session Management:
   • Rehydration after connecting with Auth and one external wallet.
   • Logout after connecting with Auth and one external wallet.
4. Chain/Namespace Management: Multichain switching within a namespace and cross-namespace switching.
5. Account Lifecycle: Perform a full sequence of Account Link $\rightarrow$ Switch $\rightarrow$ Unlink on an Auth-connected session.

Once the Web3Auth packages are built, you can start the Vue demo application. Ensure you are running these commands from the web3auth-web directory.

cd demo/vue-app
npm install
npm run dev

When working within the monorepo or consuming these packages, never use relative cross-package source imports (e.g., ../../../no-modal/src/...). This breaks package boundaries and distribution builds.

Always import shared code through the supported public entrypoints:

• @web3auth/no-modal/react
• @web3auth/no-modal/vue
• @web3auth/no-modal/react/solana
• @web3auth/no-modal/vue/solana
• @web3auth/no-modal/x402/react