Guides
NEXUS
Guides
NEXUS

Getting Started

Getting Started with the Connect Kit

Get a working connect button — embedded wallet, mobile app, extension, and external wallets included — in three steps.

1. Install

pnpm add @nexus-cross/connect-kit-react \
         wagmi viem @tanstack/react-query react react-dom

@nexus-cross/connect-kit-react pulls in connect-kit-wagmi, connect-kit-core, and @nexus-cross/dapp-ui automatically.

📘

Some transitive dependencies live on the CROSS package registry. Add this line to your project's .npmrc:

@to-nexus:registry=https://package.cross-nexus.com/repository/cross-sdk-js

2. Create the config

createConnectKitConfig is the batteries-included preset: it wires the embedded wallet connector, the ONEpocket app/extension adapters, and the external-wallet (Reown) adapter, and picks default networks for your environment.

// config.ts
import { createConnectKitConfig } from '@nexus-cross/connect-kit-react/client';

export const config = createConnectKitConfig({
  crossProjectId: 'YOUR_CROSS_PROJECT_ID',   // required
  reownProjectId: 'YOUR_REOWN_PROJECT_ID',   // needed for MetaMask / Binance Wallet
  app: { name: 'My DApp', url: 'https://example.com' },
});
🚧

@nexus-cross/connect-kit-react/client touches browser APIs at module load. In Next.js, import it only from Client Components ('use client'), never from a module reachable by a Server Component.

Useful options at this level:

OptionType / valuesDescription
crossProjectIdstring (required)CROSS relay project ID. Also used as the embedded-wallet project ID unless embeddedProjectId is set.
reownProjectIdstringReown (WalletConnect) project ID — enables MetaMask / Binance Wallet.
embeddedProjectIdstringEmbedded-wallet (ONEpocket) project ID. Falls back to crossProjectId.
app{ name, url, description?, icons? }Your app metadata, shown during wallet pairing.
environment'production' | 'staging' | 'dev'Selects default networks (mainnet vs testnet). Also read from VITE_CROSSX_ENVIRONMENT / NEXT_PUBLIC_CROSSX_ENVIRONMENT.
networks / defaultNetworkNetworkConfig[]Override the environment defaults. Presets exported: crossMainnetNetwork, crossTestnetNetwork, bscMainnetNetwork, bscTestnetNetwork.
wallets'all' | 'cross-only' | 'external-only' | WalletId[]Which wallets appear in the connect modal.
embeddedboolean (default true)Toggle the social-login embedded wallet.
theme'light' | 'dark' (default 'dark')Kit theme; autoDetectTheme: true follows prefers-color-scheme.
legal{ termsUrl?, privacyUrl? }Terms / privacy links in the connect-modal footer.
onRampEnabled / kycEnabled / onePopEnabledboolean (default false)Feature toggles — see Features.
ssrbooleanEnable cookie-based SSR hydration (Next.js).

3. Mount the provider and button

// App.tsx
import { CrossConnectKitProvider, ConnectButton } from '@nexus-cross/connect-kit-react';
import { config } from './config';

export function App() {
  return (
    <CrossConnectKitProvider config={config}>
      <ConnectButton portfolio />
      {/* your app */}
    </CrossConnectKitProvider>
  );
}

That's it. CrossConnectKitProvider mounts WagmiProvider and QueryClientProvider internally — you don't set up wagmi yourself, and all standard wagmi hooks (useAccount, useSignMessage, useSendTransaction, ...) work inside it. ConnectButton renders the connect pill; once connected it opens the full wallet info panel.

ONEpocketConnectKitProvider is an alias of CrossConnectKitProvider — both names work.

Using wagmi hooks

Everything below the provider is a normal wagmi app:

import { useAccount, useSignMessage } from 'wagmi';

function Profile() {
  const { address, isConnected } = useAccount();
  const { signMessageAsync } = useSignMessage();

  if (!isConnected) return null;
  return (
    <button onClick={() => signMessageAsync({ message: 'hello' })}>
      Sign as {address}
    </button>
  );
}

Next.js App Router (SSR)

Set ssr: true in the config, then hydrate wagmi state from the request cookie so the connected state survives reloads without a flash:

// app/layout.tsx (Server Component)
import { headers } from 'next/headers';
import { cookieToCrossConnectKitState } from '@nexus-cross/connect-kit-wagmi';
import { Providers } from './providers';
import { config } from './config';

export default async function RootLayout({ children }) {
  const initialState = cookieToCrossConnectKitState(config, (await headers()).get('cookie'));
  return (
    <html>
      <body>
        <Providers initialState={initialState}>{children}</Providers>
      </body>
    </html>
  );
}
// app/providers.tsx
'use client';
import { CrossConnectKitProvider } from '@nexus-cross/connect-kit-react';
import { config } from './config';

export function Providers({ children, initialState }) {
  return (
    <CrossConnectKitProvider config={config} initialState={initialState}>
      {children}
    </CrossConnectKitProvider>
  );
}

Advanced: low-level config

If you need full control (custom adapters, wallet guides, design-system overrides), use createCrossxConfig from @nexus-cross/connect-kit-wagmi directly:

import { createCrossxConfig, crossTestnetNetwork, bscTestnetNetwork } from '@nexus-cross/connect-kit-wagmi';
import { toNexusAdapter } from '@nexus-cross/connect-kit-wagmi/to-nexus';
import { reownAdapter } from '@nexus-cross/connect-kit-wagmi/reown';
import { embeddedConnectorFactory } from '@nexus-cross/connect-kit-wagmi/embedded';

export const config = createCrossxConfig({
  crossProjectId: '...',
  reownProjectId: '...',
  appMetadata: { name: 'My DApp', url: 'https://example.com' },
  networks: [crossTestnetNetwork, bscTestnetNetwork],
  defaultNetwork: crossTestnetNetwork,
  ssr: true,
  crossProvider: toNexusAdapter(),   // ONEpocket app + extension
  reownProvider: reownAdapter(),     // MetaMask / Binance Wallet
  embeddedConnectorFactory,          // ONEpocket embedded (social login)
});

You can also skip React entirely and drive the connectors from the registry yourself — @nexus-cross/connect-kit-wagmi has no React dependency.

Next Steps

  • Features — wallet panel, portfolio, buy, send, bridge, app launcher menu, and the feature toggles
  • JS-Wagmi SDK — the connector layer underneath the kit

Updated 2 days ago