Oviato Connect

Installation & Setup

Install and configure @oviato/connect in your React application

This guide will walk you through installing and setting up @oviato/connect in your React or Next.js application.

Prerequisites

Before you begin, make sure you have:

An Oviato App ID - Create one at dashboard.oviato.com
- See Setting Up Your App for instructions
Node.js 16+ installed
A React or Next.js project (supports React 18+)

Installation

Install @oviato/connect using your preferred package manager:

# npm
npm install @oviato/connect

# pnpm
pnpm add @oviato/connect

# yarn
yarn add @oviato/connect

# bun
bun add @oviato/connect

Setup by Framework

Next.js App Router (Recommended)

Step 1: Add Provider to Root Layout

Create or update your root layout to include the OviConnectProvider:

app/layout.tsx

import { OviConnectProvider } from "@oviato/connect/client";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <OviConnectProvider
          appId={process.env.NEXT_PUBLIC_OVIATO_APP_ID!}
          network="bitcoinmainnet"
        >
          {children}
        </OviConnectProvider>
      </body>
    </html>
  );
}

Step 2: Create Environment Variables

Create a .env.local file in your project root:

.env.local

NEXT_PUBLIC_OVIATO_APP_ID=your-app-id-here

Step 3: Use in Client Components

Create a client component to use Oviato authentication:

app/page.tsx

"use client";

import { useOviConnect, ConnectButton } from "@oviato/connect/client";

export default function HomePage() {
  const { session, isLoading, disconnect } = useOviConnect();

  if (isLoading) {
    return <div>Loading...</div>;
  }

  if (!session) {
    return (
      <div>
        <h1>Welcome to My App</h1>
        <ConnectButton text="Connect Wallet" />
      </div>
    );
  }

  return (
    <div>
      <h1>Welcome, {session.username}!</h1>
      <p>Address: {session.address}</p>
      <p>Network: {session.network}</p>
      <button onClick={disconnect}>Disconnect</button>
    </div>
  );
}

Next.js Pages Router

Step 1: Add Provider to _app.tsx

pages/_app.tsx

import type { AppProps } from "next/app";
import { OviConnectProvider } from "@oviato/connect/client";

export default function App({ Component, pageProps }: AppProps) {
  return (
    <OviConnectProvider
      appId={process.env.NEXT_PUBLIC_OVIATO_APP_ID!}
      network="bitcoinmainnet"
    >
      <Component {...pageProps} />
    </OviConnectProvider>
  );
}

Step 2: Use in Pages

pages/index.tsx

import { useOviConnect, ConnectButton } from "@oviato/connect/client";

export default function HomePage() {
  const { session, disconnect } = useOviConnect();

  return (
    <div>
      {session ? (
        <div>
          <p>Connected: {session.address}</p>
          <button onClick={disconnect}>Disconnect</button>
        </div>
      ) : (
        <ConnectButton text="Connect Wallet" />
      )}
    </div>
  );
}

Create React App / Vite

Step 1: Add Provider to App Root

src/App.tsx

import { OviConnectProvider } from "@oviato/connect/client";
import HomePage from "./pages/HomePage";

function App() {
  return (
    <OviConnectProvider appId="your-app-id" network="bitcoinmainnet">
      <HomePage />
    </OviConnectProvider>
  );
}

export default App;

Step 2: Use in Components

src/pages/HomePage.tsx

import { useOviConnect, ConnectButton } from "@oviato/connect/client";

export default function HomePage() {
  const { session, disconnect } = useOviConnect();

  return (
    <div>
      {session ? (
        <div>
          <p>Connected: {session.address}</p>
          <button onClick={disconnect}>Disconnect</button>
        </div>
      ) : (
        <ConnectButton text="Connect Wallet" />
      )}
    </div>
  );
}

Environment Variables (Vite)

Create a .env.local file:

.env.local

VITE_OVIATO_APP_ID=your-app-id-here

Use in your code:

<OviConnectProvider appId={import.meta.env.VITE_OVIATO_APP_ID} />

Provider Configuration

The OviConnectProvider accepts several configuration options:

<OviConnectProvider
  appId="your-app-id" // Required: Your Oviato App ID
  network="bitcoinmainnet" // Optional: Default network (default: 'bitcoinmainnet')
  theme="light" // Optional: UI theme ('light' | 'dark')
  accentColor="#3B82F6" // Optional: Brand color
  logoUrl="/logo.png" // Optional: Your app logo
  name="My App" // Optional: Your app name
>
  {children}
</OviConnectProvider>

Configuration Options

Option	Type	Default	Description
`appId`	`string`	Required	Your Oviato application ID
`network`	`string`	`'bitcoinmainnet'`	Default blockchain network
`theme`	`'light' \| 'dark'`	System preference	UI theme for auth modal
`accentColor`	`string`	`'#3B82F6'`	Primary brand color (hex)
`logoUrl`	`string`	Oviato logo	Your app logo URL
`name`	`string`	`'App'`	Your app name

Supported Networks

bitcoinmainnet - Bitcoin Mainnet
bitcointestnet - Bitcoin Testnet
ethmainnet - Ethereum Mainnet (soon)
ethsepolia - Ethereum Sepolia Testnet (soon)

Verify Installation

Create a simple test to verify everything is working:

"use client"; // Only needed for Next.js App Router

import { useOviConnect, ConnectButton } from "@oviato/connect/client";

export default function TestPage() {
  const { session, ready, isLoading } = useOviConnect();

  return (
    <div>
      <h1>Oviato Connection Test</h1>
      <p>SDK Ready: {ready ? "✅" : "❌"}</p>
      <p>Loading: {isLoading ? "Yes" : "No"}</p>
      <p>Session: {session ? "✅ Connected" : "❌ Not connected"}</p>

      {!session && <ConnectButton text="Test Connection" />}

      {session && (
        <div>
          <p>Username: {session.username}</p>
          <p>Address: {session.address}</p>
        </div>
      )}
    </div>
  );
}

TypeScript Configuration

@oviato/connect includes full TypeScript definitions. No additional setup required!

Import types as needed:

import type {
  UserSession,
  OviatoConfig,
  BridgeResponse,
  OviConnectProviderProps,
} from "@oviato/connect";

import type { UseOviConnectReturn } from "@oviato/connect/client";

Troubleshooting

"Cannot find module '@oviato/connect/client'"

Make sure you're importing from the correct entry point:

✅ from '@oviato/connect/client' (for React components/hooks)
✅ from '@oviato/connect' (for core functions/types)

"'use client' directive" errors

If you see errors about client directives:

Ensure you're using Next.js 13+ with App Router
Add 'use client' at the top of components using hooks
Make sure you're importing from /client entry point

Session not persisting

Check that:

Your domain is added to allowed domains in the dashboard
Cookies are enabled in the browser
You're using HTTPS in production (required for WebAuthn)

Type errors with session

Make sure TypeScript can resolve the types:

import type { UserSession } from "@oviato/connect";

const session: UserSession | null = getSession();

Next Steps

Using Hooks - Learn about useOviConnect and useOviStore
Components Reference - Explore pre-built UI components
Signing Messages - Sign messages with the wallet
Signing Transactions - Send transactions

What is @oviato/connect?

React SDK for Oviato authentication with hooks, providers, and pre-built components

Using Hooks

React hooks for Oviato Connect - useOviConnect and useOviStore

Installation & Setup

On this page