Getting Started with @gillsdk/react

This guide will walk you through setting up @gillsdk/react in your React application, including configuration for Next.js App Router, Remix, and other frameworks that support React Server Components.

Prerequisites

Before you begin, make sure you have:

A React application (Create React App, Next.js, Vite, etc.)
Node.js LTS (v22 or later) installed
Basic knowledge of React hooks

Setup Steps

Install Dependencies

First, install @gillsdk/react along with its peer dependencies:

npm install gill @gillsdk/react @tanstack/react-query

Create a Solana Client

Create a Solana client using gill's createSolanaClient function:

import { createSolanaClient } from "gill";
 
const client = createSolanaClient({
  urlOrMoniker: "devnet", // or "mainnet", "testnet", or a custom RPC URL
});

The public Solana RPC endpoints are subject to rate limits and should not be used in production. For production applications, use a dedicated RPC provider like Helius, QuickNode, or Alchemy.

Wrap Your App with SolanaProvider

The SolanaProvider is a React context provider that makes the Solana client available to all @gillsdk/react hooks in your component tree.

For Standard React Apps

import { createSolanaClient } from "gill";
import { SolanaProvider } from "@gillsdk/react";
 
const client = createSolanaClient({
  urlOrMoniker: "devnet",
});
 
function App() {
  return <SolanaProvider client={client}>{/* Your app components */}</SolanaProvider>;
}
 
export default App;

For Next.js App Router and React Server Components

For applications that use React Server Components (like Next.js App Router, Remix, or other RSC-enabled frameworks), you need to create a client-side wrapper component.

What is the "use client" directive?

The "use client" directive tells the bundler that this component and its children should run on the client side (in the browser) rather than on the server. This is necessary because:

@gillsdk/react uses React hooks (useState, useEffect, etc.) which only work on the client
The provider creates and hooks consume React context, which is a client-side feature
Without this directive, you'll get errors about using hooks in Server Components.

Here's how to create a client-side provider wrapper:

"use client"; // Required - marks this as a Client Component
 
import { createSolanaClient } from "gill";
import { SolanaProvider } from "@gillsdk/react";
 
const client = createSolanaClient({
  urlOrMoniker: "devnet",
});
 
export function SolanaProviderClient({ children }: { children: React.ReactNode }) {
  return <SolanaProvider client={client}>{children}</SolanaProvider>;
}

Then wrap your app in the root layout with this SolanaProviderClient component:

import { SolanaProviderClient } from "@/providers/solana-provider";
 
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <SolanaProviderClient>{children}</SolanaProviderClient>
      </body>
    </html>
  );
}

Use @gillsdk/react Hooks

Now you can use any @gillsdk/react hook in your components. When using frameworks with React Server Components (like Next.js App Router), remember to add the "use client" directive to any component that uses @gillsdk/react hooks:

"use client"; // Required when using React Server Components
 
import { lamportsToSol } from "gill";
import { useBalance } from "@gillsdk/react";
 
export function WalletBalance() {
  const { balance, isLoading, isError, error } = useBalance({
    address: "nicktrLHhYzLmoVbuZQzHUTicd2sfP571orwo9jfc8c",
  });
 
  if (isLoading) return <div>Loading balance...</div>;
  if (isError) return <div>Error: {error?.message}</div>;
 
  return (
    <div>
      <p>Balance: {lamportsToSol(balance)} SOL</p>
    </div>
  );
}

Configuration Options

Custom RPC Endpoints

For production applications, configure a dedicated RPC endpoint:

const client = createSolanaClient({
  urlOrMoniker: "https://your-rpc-provider.com/your-api-key",
});

Popular RPC Providers

Multiple Clients

You can manage multiple Solana clients using the useUpdateSolanaClient hook:

"use client";
 
import { createSolanaClient } from "gill";
import { useUpdateSolanaClient } from "@gillsdk/react";
 
function NetworkSwitcher() {
  const updateClient = useUpdateSolanaClient();
 
  const switchToMainnet = () => {
    const mainnetClient = createSolanaClient({
      urlOrMoniker: "mainnet",
    });
    updateClient(mainnetClient);
  };
 
  return <button onClick={switchToMainnet}>Switch to Mainnet</button>;
}

TypeScript Configuration

@gillsdk/react is fully typed out of the box. No additional TypeScript configuration is required. However, ensure your tsconfig.json has:

{
  "compilerOptions": {
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "jsx": "react-jsx" // or "preserve" for Next.js
  }
}

Troubleshooting

"use client" Errors

If you see errors like "You're importing a component that needs useEffect. It only works in a Client Component" or "useState only works in Client Components", this means you're trying to use @gillsdk/react in a Server Component. (which NextJS App router does by default unless the "use client" directive is explicitly used).

Why this happens:

React Server Components run on the server during build/request time
@gillsdk/react uses browser-specific features like React hooks and Web APIs
The Solana client needs to make RPC calls from the browser

To fix:

Add "use client" at the top of any file using @gillsdk/react hooks
Ensure your SolanaProvider wrapper has "use client" at the top
Make sure the provider is properly wrapped around your component tree

Common scenarios:

Forgot to add "use client" to a component using useBalance, useAccount, etc.
Trying to use @gillsdk/react hooks directly in a page.tsx without the directive
Importing a Client Component into a Server Component without proper boundaries

RPC Rate Limiting

If you're hitting rate limits:

Switch from public endpoints to a dedicated RPC provider
Implement request batching and caching strategies
Consider using the staleTime and cacheTime options in hooks

Bundle Size

To minimize bundle size:

Import only the hooks you need
Ensure tree-shaking is enabled in your bundler
Use dynamic imports for heavy components

Ready to start using @gillsdk/react? Check out the available hooks to begin fetching blockchain data in your React application.

Getting Started with @gillsdk/react

On this page