Provider Setup

The NearProvider component makes a Near client instance available to all components in your app via React Context.

Basic Setup

Create the Near client

Create your Near instance with your desired configuration. This can be done outside your component tree.

import { Near } from "near-kit"

const near = new Near({
  network: "mainnet",
})

Wrap your app with NearProvider

Place the NearProvider at the root of your component tree.

import { NearProvider } from "@near-kit/react"

function App() {
  return (
    <NearProvider near={near}>
      <YourApp />
    </NearProvider>
  )
}

Use hooks in any component

All hooks from @near-kit/react will now have access to the Near client.

import { useBalance } from "@near-kit/react"

function WalletDisplay() {
  const { data: balance } = useBalance({ accountId: "alice.near" })
  return <p>Balance: {balance}</p>
}

Provider Props

Near

required

The Near client instance to provide to all child components.

ReactNode

required

React children to render inside the provider.

useNear Hook

Access the Near client directly when you need the full API:

import { useNear } from "@near-kit/react"

function AdvancedComponent() {
  const near = useNear()

  const handleComplex = async () => {
    // Full access to the Near client API
    const result = await near
      .transaction("alice.near")
      .functionCall("contract.near", "method", { arg: "value" })
      .transfer("bob.near", "1 NEAR")
      .send()
  }

  return <button onClick={handleComplex}>Complex Transaction</button>
}

useNear() will throw an error if called outside of a NearProvider. Always ensure your components are wrapped.

Framework-Specific Setup

Next.js (App Router)
Next.js (Pages Router)
Vite / CRA

Create a client component for the provider:

// providers/near-provider.tsx
"use client"

import { Near } from "near-kit"
import { NearProvider } from "@near-kit/react"

const near = new Near({ network: "mainnet" })

export function NearProviderWrapper({ children }: { children: React.ReactNode }) {
  return <NearProvider near={near}>{children}</NearProvider>
}

Use it in your root layout:

// app/layout.tsx
import { NearProviderWrapper } from "@/providers/near-provider"

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>
        <NearProviderWrapper>{children}</NearProviderWrapper>
      </body>
    </html>
  )
}

The @near-kit/react package includes the "use client" directive, so you don’t need to add it to your imports. However, components using the hooks must be client components.

Set up the provider in _app.tsx:

// pages/_app.tsx
import type { AppProps } from "next/app"
import { Near } from "near-kit"
import { NearProvider } from "@near-kit/react"

const near = new Near({ network: "mainnet" })

export default function App({ Component, pageProps }: AppProps) {
  return (
    <NearProvider near={near}>
      <Component {...pageProps} />
    </NearProvider>
  )
}

Set up the provider in your entry point:

// main.tsx or index.tsx
import React from "react"
import ReactDOM from "react-dom/client"
import { Near } from "near-kit"
import { NearProvider } from "@near-kit/react"
import App from "./App"

const near = new Near({ network: "mainnet" })

ReactDOM.createRoot(document.getElementById("root")!).render(
  <React.StrictMode>
    <NearProvider near={near}>
      <App />
    </NearProvider>
  </React.StrictMode>
)

With Wallet Connection

For dApps where users connect their own wallets, create the Near instance dynamically:

"use client"

import { useState, useEffect } from "react"
import { Near, fromHotConnect } from "near-kit"
import { NearProvider } from "@near-kit/react"
import { NearConnector } from "@hot-labs/near-connect"

export function WalletProvider({ children }: { children: React.ReactNode }) {
  const [near, setNear] = useState<Near | null>(null)

  useEffect(() => {
    const connector = new NearConnector({ network: "mainnet" })

    connector.on("wallet:signIn", async () => {
      setNear(
        new Near({
          network: "mainnet",
          wallet: fromHotConnect(connector),
        })
      )
    })

    connector.connect()
  }, [])

  // Show loading or connect button when not connected
  if (!near) {
    return <ConnectWalletButton />
  }

  return <NearProvider near={near}>{children}</NearProvider>
}

For a complete wallet integration example, see the Frontend Integration guide.

Error: Nested Provider

NearProvider throws an error if nested inside another NearProvider. This prevents accidental context shadowing.

// ❌ This will throw an error
<NearProvider near={near1}>
  <NearProvider near={near2}>  {/* Error! */}
    <App />
  </NearProvider>
</NearProvider>

// ✅ Use a single provider at the root
<NearProvider near={near}>
  <App />
</NearProvider>

If you need multiple Near clients (rare), manage them outside of context:

const mainnetNear = new Near({ network: "mainnet" })
const testnetNear = new Near({ network: "testnet" })

// Use the specific client directly where needed
const balance = await testnetNear.getBalance("alice.testnet")

Getting Started

Essentials

React

Building dApps

Advanced

Reference

Basic Setup

Provider Props

useNear Hook

Framework-Specific Setup

With Wallet Connection

Error: Nested Provider

​Basic Setup

​Provider Props

​useNear Hook

​Framework-Specific Setup

​With Wallet Connection

​Error: Nested Provider

Basic Setup

Provider Props

useNear Hook

Framework-Specific Setup

With Wallet Connection

Error: Nested Provider