Skip to Content
On this page

This guide shows you how to add the DogeOS SDK to an existing React app. To learn the SDK by building a small app from scratch, follow Get Started instead.

Install the Package#

Install the SDK and its wagmi peer dependency with pnpm:

pnpm add @dogeos/dogeos-sdk@^4.0.7 wagmi

Commit the updated lockfile. To confirm the version your app resolves, run pnpm why @dogeos/dogeos-sdk.

npm can’t install the SDK at the moment: it stops with Unsupported URL Type "catalog:", because of an optional dependency of Wagmi’s connectors. Use pnpm until this is fixed; see Troubleshooting.

Get a Client ID#

  1. Create a project in the developer console .
  2. Copy its Sandbox client ID for development. Use the Live client ID in production.
  3. Register every origin your app runs on in the matching environment, for example https://app.example.com and https://staging.example.com. Your project overview shows whether automatic localhost and 127.0.0.1 access is ready.

The client ID is public, so it can go in your browser bundle.

Mount the Provider#

Wrap the part of your app that uses wallets in WalletConnectProvider, and import the SDK stylesheet once:

"use client"
 
import type { ReactNode } from "react"
import { WalletConnectProvider, type WalletConnectKitConfig } from "@dogeos/dogeos-sdk"
import "@dogeos/dogeos-sdk/style.css"
 
const dogeConfig: WalletConnectKitConfig = {
  clientId: "YOUR_DOGEOS_CLIENT_ID",
}
 
export function DogeOSProvider({ children }: { children: ReactNode }) {
  return <WalletConnectProvider config={dogeConfig}>{children}</WalletConnectProvider>
}

Most apps also set chains; see Use DogeOS Chikyū and Other Networks. The Configuration reference lists every option.

Set Up Next.js#

WalletConnectProvider runs only in the browser, so load it with next/dynamic and ssr: false. This works in both the App Router and the Pages Router.

  1. Put the provider in its own component:

    // components/dogeos-provider.tsx
"use client"
 
import type { ReactNode } from "react"
import { WalletConnectProvider, type WalletConnectKitConfig } from "@dogeos/dogeos-sdk"
import "@dogeos/dogeos-sdk/style.css"
 
const dogeConfig: WalletConnectKitConfig = {
  clientId: process.env.NEXT_PUBLIC_DOGEOS_CLIENT_ID!,
}
 
export function DogeOSProvider({ children }: { children: ReactNode }) {
  return <WalletConnectProvider config={dogeConfig}>{children}</WalletConnectProvider>
}

  2. Load it without server rendering:

    // components/providers.tsx
"use client"
 
import dynamic from "next/dynamic"
 
export const Providers = dynamic(() => import("./dogeos-provider").then((mod) => mod.DogeOSProvider), {
  ssr: false,
})

  3. Wrap the parts of your app that use wallets. In the App Router, that can be your root layout:

    // app/layout.tsx
import type { ReactNode } from "react"
import { Providers } from "../components/providers"
 
export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="en">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  )
}

    In the Pages Router, wrap <Component {...pageProps} /> in pages/_app.tsx the same way.

  4. Set NEXT_PUBLIC_DOGEOS_CLIENT_ID before you start or build the app.

Everything inside Providers renders only in the browser. If your pages need server-rendered content, wrap only the sections that use wallets instead of the whole layout.

Next Steps#