> ## Documentation Index
> Fetch the complete documentation index at: https://docs.namespace.ninja/llms.txt
> Use this file to discover all available pages before exploring further.

# RainbowKit Starter (Next.js)

> Ready-to-run Next.js starter with RainbowKit, reverse resolution for ENS subnames, and profile flows.

## ENS Offchain Subnames + RainbowKit Starter Kit

A Next.js starter integrating the [Offchain Manager SDK](/developer-guide/sdks/offchain-manager) with [RainbowKit](https://rainbowkit.com) for creating and managing offchain ENS subnames.

### Features

* RainbowKit UI with offchain subname creation and fetch logic
* Reverse resolution for addresses, e.g., `0x23...` → `happy.offchainsub.eth`

**Repository:** [`thenamespace/ens-subnames-rainbowkit-template`](https://github.com/thenamespace/ens-subnames-rainbowkit-template)

## Prerequisites

* Node.js (v18 or later)
* An ENS name (e.g., `offchainsub.eth`)
* Namespace API key from the [Namespace App](/user-guide/dev-portal/api-keys)

## Setup

<Steps>
  <Step title="Clone and install">
    ```bash theme={null}
    git clone https://github.com/thenamespace/ens-subnames-rainbowkit-template.git
    cd ens-subnames-rainbowkit-template
    npm install
    ```
  </Step>

  <Step title="Environment variables">
    Create a `.env.local` file in the root directory:

    ```env theme={null}
    # Your ENS name (eg. offchainsub.eth)
    NEXT_PUBLIC_ENS_NAME=yourname

    # Your Namespace API key (keep this secret!)
    NAMESPACE_API_KEY=ns_live_xxxxxxxxxx
    ```
  </Step>

  <Step title="Configure your ENS name">
    1. Visit the [Namespace App](https://app.namespace.ninja/offchain)
    2. Change the resolver for your ENS name to Namespace's resolver
    3. Generate and copy your API key
    4. Add both to your `.env.local` file
  </Step>

  <Step title="Run the development server">
    ```bash theme={null}
    npm run dev
    ```

    Open `http://localhost:3000` to see the application.
  </Step>

  <Step title="It's ready!">
    <img src="https://mintcdn.com/namespace-1f56cc70/-O3JTyKjz1q6adH-/assets/developer-guide/integrations/rainbowkit-nextjs/page.png?fit=max&auto=format&n=-O3JTyKjz1q6adH-&q=85&s=19550b5b1720dfa064e4ab7b1060974b" alt="Create subname interface with form to create a new offchain subname" width="3016" height="1722" data-path="assets/developer-guide/integrations/rainbowkit-nextjs/page.png" />
  </Step>
</Steps>

## What’s included

#### 🔗 RainbowKit Integration

* Custom connect button with Namespace subname support
* Account modal with subname creation functionality
* Automatic primary name resolution

#### File Structure

```txt theme={null}
src/
├── app/
│   ├── api/subname/create/route.ts    # Server-side subname creation
│   ├── page.tsx                       # Main demo page
│   └── providers.tsx                  # RainbowKit & Wagmi setup
├── components/
│   └── kit/
│       ├── AccountModal.tsx           # Account management modal
│       └── CustomConnectButton.tsx    # Custom connect button
├── hooks/
│   ├── use-subnames.ts               # Subname fetching hooks
│   └── use-subname-creation.ts       # Subname creation hooks
└── lib/
    ├── namespace.ts                   # Server-side client (with API key)
    └── namespace-client.ts            # Client-side client (read-only)
```

#### 🏗️ Architecture

* Server-side Namespace client (`/src/lib/namespace.ts`) - Uses API key securely for write operations
* Client-side Namespace client (`/src/lib/namespace-client.ts`) - For read-only operations without API key exposure
* API route (`/src/app/api/subname/create/route.ts`) - Server-side subname creation endpoint

#### 🪝 Custom Hooks

* `useSubnames` - Fetch subnames for an address
* `useFirstSubname` - Get the primary subname for an address
* `usePreferredIdentity` - Intelligent name resolution (subname → ENS → truncated address)
* `useCreateSubname` - Create new subnames with validation
* `useSubnameAvailability` - Check if a subname is available

#### 📡 API Endpoints

* `POST /api/subname/create` - Create subnames with custom address and text records

### Security & Limitations

#### ⚠️ Important Security Notes

* Never expose your Namespace API key to the client side
* API key is only used in server-side code (`/src/lib/namespace.ts` and API routes)
* Client-side operations use the public client without API key

#### 📊 Rate Limits

* Up to 2,000 subnames can be created per API key to prevent abuse
* Need more? Contact us on the [Builders Group](https://t.me/+5FAwyiKOTeswNTIy)

## References

* GitHub Repository: [`thenamespace/ens-subnames-rainbowkit-template`](https://github.com/thenamespace/ens-subnames-rainbowkit-template)
* SDK Reference: [Offchain Manager SDK](/developer-guide/sdks/offchain-manager)
* Builders Group: [`Telegram`](https://t.me/+5FAwyiKOTeswNTIy)
* RainbowKit Docs: [`Introduction`](https://rainbowkit.com/docs/introduction)