React utilities that bridge Privy’s embedded wallets with Rango’s wallet-core stack. Drop in the provider, wire up config, and you get social login, multi-chain wallet providers, and signer helpers that feel native to your React app.
npm install @rango-dev/internal-social-walletReact utilities that bridge Privy’s embedded wallets with Rango’s wallet-core stack. Drop in the provider, wire up config, and you get social login, multi-chain wallet providers, and signer helpers that feel native to your React app.
---
1. Features
2. Installation
3. Peer Dependencies
4. API Surface
5. Getting Started
6. Configuration & Environment
7. Development
8. Testing Ideas
9. Known Gaps
10. FAQ
---
- Drop-in provider – SocialWalletProvider wraps Privy, exposes supported chain state via React context, and includes sane defaults for embedded EVM + Solana wallets.
- Multi-namespace hook – useSocialWallet returns a provider map (evm, solana) backed by @rango-dev/wallets-core, handling Privy login, auto-connect, signer instantiation, and error surfacing.
- Config hook – useSocialWalletConfig allows any component to read/update the supported chains without prop drilling.
- Helper utilities – Solana signer wrappers, Privy chain converters, and validation helpers keep chain metadata consistent between Privy and Rango.
---
``bash`
pnpm add @rango-dev/internal-social-walletor
yarn add @rango-dev/internal-social-wallet
Use your workspace package manager if different (npm, bun, etc.).
---
Ensure these packages already exist in your app (matching versions to your stack):
- react, react-dom
-
- , @rango-dev/wallets-shared
- , @rango-dev/signer-solana
- , @solana/kit, bs58, rango-types
---
`ts`
import {
SocialWalletProvider,
useSocialWallet,
useSocialWalletConfig,
} from '@rango-dev/internal-social-wallet';
- SocialWalletProvider – wraps your tree, configures Privy with sane defaults, and accepts a required appId prop.useSocialWallet
- – returns { provider, exportEvmWallet, exportSolanaWallet }.useSocialWalletConfig
- – exposes { supportedChains, setSupportedChains }.
Refer to the source if you need additional helper exports (signers, constants).
---
`tsx
import { SocialWalletProvider } from '@rango-dev/internal-social-wallet';
function App() {
return (
);
}
`
`tsx
import { useEffect } from 'react';
import { useSocialWalletConfig } from '@rango-dev/internal-social-wallet';
import type { BlockchainMeta } from 'rango-types';
const chains: BlockchainMeta[] = [
/ fetched from backend /
];
function ChainBootstrap() {
const { setSupportedChains } = useSocialWalletConfig();
useEffect(() => {
setSupportedChains(chains);
}, [chains, setSupportedChains]);
return null;
}
`
`tsx
import { useSocialWallet } from '@rango-dev/internal-social-wallet';
function ConnectButton() {
const { provider, status } = useSocialWallet();
const connect = async () => {
await provider.get('evm')?.connect();
};
return (
);
}
`
`tsx`
---
- CustomPrivyProvider defines default Solana RPC URLs in CustomPrivyProvider.constants.ts. Override through env variables or inject custom RPCs via props before production.email
- Privy login methods currently default to , google, twitter. To change them, update providers/customPrivyProvider/CustomPrivyProvider.tsx (props-based configuration is not yet wired).NEXT_PUBLIC_PRIVY_APP_ID
- When deploying to multiple environments, align , RPC URLs, and supported chain metadata so Privy and Rango stay in sync.
---
`bash`
pnpm --filter @rango-dev/internal-social-wallet dev # tsc --watch
pnpm --filter @rango-dev/internal-social-wallet build # emits dist/
Before publishing:
- Verify package.json exports target dist/index.*.pnpm --filter @rango-dev/internal-social-wallet build
- Run to regenerate dist/.
- Smoke test the provider in a sandbox app to ensure Privy embeds load correctly.
---
No automated tests ship with this package yet. Suggested coverage:
- useSocialWallet connect/disconnect flows (mock Privy, assert provider map).useSocialWalletConfig
- state updates propagate to consumers.
- Solana signer wrapper – verifies transaction signing + serialization.
- Error boundaries and fallback UI when Privy is unavailable.
---
- exportEvmWallet / exportSolanaWallet functions are placeholders.
- RPC URLs are hardcoded; externalize them for production.
- First embedded wallet is automatically selected; multi-wallet UX is out of scope for now.
---
Q: Does this replace traditional wallet adapters?
A: No. It complements them by giving Privy-powered embedded wallets that conform to the same wallet-core interface.
Q: How do I add a new chain?
A: Update your backend/source of BlockchainMeta, call setSupportedChains, and ensure Privy supports the chain ID + namespace.
Q: Why can’t I connect on Solana?
A: Double-check Solana RPC URLs, make sure @solana/web3.js` is available, and confirm the Privy app has Solana enabled.