Critical: Thirdweb v5 Sub-Path Imports

Thirdweb v5 uses sub-path imports. Never import from the root thirdweb package for specialized modules:

ts
1// CORRECT
2import { createThirdwebClient } from 'thirdweb';
3import { inAppWallet, createWallet } from 'thirdweb/wallets';
4import { darkTheme } from 'thirdweb/react';
5import { createAuth } from 'thirdweb/auth';
6import { privateKeyToAccount } from 'thirdweb/wallets';
7
8// WRONG — do not import wallet/auth/react from root
9import { inAppWallet } from 'thirdweb'; // ❌

Project Setup

Client (Web — apps/web/src/lib/thirdweb.ts)

ts
1import { createThirdwebClient } from 'thirdweb';
2
3export const client = createThirdwebClient({
4  clientId: process.env.NEXT_PUBLIC_THIRDWEB_CLIENT_ID!,
5});

Client (API — apps/api/src/lib/thirdweb.ts)

ts
1import { createThirdwebClient } from 'thirdweb';
2
3export const thirdwebClient = createThirdwebClient({
4  secretKey: process.env.THIRDWEB_SECRET_KEY,
5});

Wallets Configuration

ts
1import { inAppWallet, createWallet } from 'thirdweb/wallets';
2
3export const wallets = [
4  inAppWallet({
5    auth: { options: ['email', 'google', 'apple', 'passkey'] },
6  }),
7  createWallet('io.metamask'),
8  createWallet('com.coinbase.wallet'),
9  createWallet('walletConnect'),
10];

SIWE Auth (Server-Side)

ts
1import { createAuth } from 'thirdweb/auth';
2import { privateKeyToAccount } from 'thirdweb/wallets';
3
4const adminAccount = privateKeyToAccount({
5  client: thirdwebClient,
6  privateKey: process.env.THIRDWEB_ADMIN_PRIVATE_KEY as `0x${string}`,
7});
8
9export const thirdwebAuth = createAuth({
10  domain: process.env.AUTH_DOMAIN,
11  client: thirdwebClient,
12  adminAccount,
13});

Auth flow: thirdwebAuth.generatePayload() → client signs → thirdwebAuth.verifyPayload() → JWT via thirdwebAuth.generateJWT().

Provider Stack (Web)

Wrap app with QueryClientProvider (from @tanstack/react-query) + ThirdwebProvider:

tsx
1import { ThirdwebProvider } from 'thirdweb/react';
2
3<QueryClientProvider client={queryClient}>
4  <ThirdwebProvider>{children}</ThirdwebProvider>
5</QueryClientProvider>

Theme

This project uses darkTheme() from thirdweb/react with custom indigo accent colors. See apps/web/src/lib/thirdweb.ts for the full theme config.

Environment Variables

Key Hooks

• useActiveAccount() — Get connected wallet account
• useActiveWallet() — Get connected wallet instance
• useConnect() — Connect a wallet programmatically
• useDisconnect() — Disconnect current wallet

Chain Configuration

This project targets Celo mainnet (chain ID 42220). When using ConnectButton, set chain={celo} from thirdweb/chains.