JustaName React SDK

The JustaName React SDK makes it easy to integrate Ethereum Name Service (ENS) functionalities, including subname management, and user authentication via ENS into React applications. It simplifies interacting with ENS off-chain operations while ensuring secure and easy integration with your dApps.

Table of Contents

• Installation
• Usage
  • Setup with JustaNameProvider
  • Example: Add a Subname
• Hooks
  • Account and ENS Management
  • Subname Management
  • Authentication
  • Other Hooks

Installation

Install the JustaName React SDK using npm or yarn:

npm install @justaname.id/react

# or

yarn add @justaname.id/react

Usage

Setup with JustaNameProvider

To use the JustaName React SDK, wrap your application with the JustaNameProvider. This component provides all child components access to the JustaName context, enabling seamless interaction with ENS services.

Example: Setup with JustaNameProvider

tsx
'use client';
import { JustaNameProvider } from '@justaname.id/react';
import { configureChains, createClient, WagmiConfig } from 'wagmi';
import { publicProvider } from 'wagmi/providers/public';
import { getDefaultWallets, RainbowKitProvider } from '@rainbow-me/rainbowkit';
import '@rainbow-me/rainbowkit/styles.css';
import { AddSubname } from './AddSubname';

const { wallets } = getDefaultWallets();

const config = getDefaultConfig({
  appName: 'JustaName Console',
  projectId: 'YOUR_PROJECT_ID',
  wallets: [
    ...wallets,
    {
      groupName: 'Other',
      wallets: [argentWallet, trustWallet, ledgerWallet],
    },
  ],
  chains: [mainnet, sepolia],
  ssr: true,
});

const justaNameConfig = {
  networks: [{ chainId: 1, providerUrl: 'https://mainnet.infura.io/v3/YOUR_INFURA_KEY' }],
  ensDomains: [
    { 
      chainId: 1, 
      domain: 'your_ens_domain.eth',
      apiKey: 'your-api-key' // Not recommended for production, use a backend server to protect your API key
    }
  ],
  backendUrl: 'https://your-backend-url.com' // Leave empty for same origin (e.g when using Next.js)
};

export const App = () => {
  return (
    <WagmiConfig client={config}>
      <RainbowKitProvider chains={chains}>
        <JustaNameProvider config={justaNameConfig}>
            <AddSubname />
        </JustaNameProvider>
      </RainbowKitProvider>
    </WagmiConfig>
  );
}

Example: Add a Subname

Below is a complete example of a React component where users can claim a subname using the useAddSubname hook. It also checks subname availability with useIsSubnameAvailable.

tsx
Copy code
import { useAddSubname, useIsSubnameAvailable } from '@justaname.id/react';
import { useState } from 'react';
import { useDebounce } from '@uidotdev/usehooks';
import { ConnectButton } from '@rainbow-me/rainbowkit';
import { useAccount } from 'wagmi';

export const AddSubname = () => {
  const { isConnected } = useAccount();
  const [username, setUsername] = useState<string>('');
  const debouncedUsername = useDebounce(username, 500);
  const { isSubnameAvailable } = useIsSubnameAvailable({ 
    username: debouncedUsername 
  });
  const { addSubname } = useAddSubname();

  return (
    <div>
      <h1>Claim your subdomain</h1>
      <ConnectButton />
      <input
        value={username}
        onChange={(e) => setUsername(e.target.value)}
        placeholder="Enter a subdomain"
      />
      <button
        onClick={() => addSubname({ username })}
        disabled={!isSubnameAvailable || !isConnected || !debouncedUsername}
      >
        Claim
      </button>
    </div>
  );
};

Hooks

The SDK offers various hooks for managing ENS accounts, subnames, and authentication.

Account and ENS Management

• useAccountEnsNames: Fetch ENS names associated with the user's account.
• useAddressEnsNames: Fetch ENS names for a given Ethereum address.
• usePrimaryName: Get the primary ENS name of an address.
• useAccountInvitations: Get pending invitations for the connected account.
• useAccountSubnames: Fetch all subnames for the connected account.

Subname Management

• useIsSubnameAvailable: Check if a subname is available.
• useAddSubname: Add a new subname off-chain.
• useAcceptSubname: Accept an invitation for a subname.
• useRejectSubname: Reject a subname invitation.
• useRevokeSubname: Revoke an issued subname.
• useUpdateSubname: Update an ens metadata (off-chain and on-chain).
• useSearchSubnames: Search for subnames based on given parameters.
• useSubname: Get the details of a specific subname.
• useRecords: Fetch records associated with any ENS name.

Authentication

• useEnsSignIn: Authenticate users with their ENS name.
• useEnsSignOut: Sign out the connected user.
• useEnsAvatar: Fetch the avatar of an ENS name.
• useEnsAuth: Manage authentication state with ENS.

Other Hooks

• useJustaName: Access the JustaName context directly.
• useMounted: Check if the component is mounted.
• useMountedAccount: Get the mounted account details.
• useOffchainResolvers: Fetch off-chain resolvers.
• useUpdateChanges: Check for changes in the ENS metadata before updating.
• useUploadMedia: Upload media for ENS metadata.

Contributing

Contributions are welcome! If you have suggestions or find issues, please open an issue or submit a pull request on the GitHub repository.