@farcaster/connect-kit v0.0.31

@farcaster/connect-kit

A React library that makes it easy to add Sign In With Farcaster to your application.

Getting Started

Installation

Install ConnectKit and its peer dependency viem.

npm install @farcaster/connect-kit viem

Note: ConnectKit is a React library. If you're using another frontend framework, take a look at the @farcaster/connect client library instead.

Import

Import styles and functions.

import "@farcaster/connect-kit/styles.css";
import { ConnectKitProvider } from "@farcaster/connect-kit";

Add Provider

Wrap your application with ConnectKitProvider.

const config = {
  // For a production app, replace this with an Optimism Mainnet
  // RPC URL from a provider like Alchemy or Infura.
  rpcUrl: "https://mainnet.optimism.io",
  domain: "example.com",
  siweUri: "https://example.com/login",
};

const App = () => {
  return (
    <ConnectKitProvider config={config}>{/* Your App */}</ConnectKitProvider>
  );
};

Add the connect button

Then, in your app, import and render the ConnectButton component.

import { ConnectButton } from "@farcaster/connect-kit";

export const Login = ({ nonce }: { nonce: string }) => {
  return <ConnectButton nonce={nonce} />;
};

A Sign in with Farcaster button will be rendered. When the user clicks it they will be prompted to complete sign in using their Farcaster wallet application. Once they complete sign in a signed message will be returned to your callback.

Examples

You can find official examples here.

Components

ConnectKitProvider

Wrap your application in a ConnectKitProvider to use Farcaster Connect.

const config = {
  domain: "example.com",
  siweUri: "https://example.com/login",
  rpcUrl: "https://mainnet.optimism.io",
  relay: "https://relay.farcaster.xyz",
};

const App = () => {
  return (
    <ConnectKitProvider config={config}>{/* Your App */}</ConnectKitProvider>
  );
};

Props

config options:

ConnectButton

The main component. Renders a "Sign in With Farcaster" button that prompts the user to scan a QR code with their phone on web or redirects directly on a mobile device. You can use a callback prop or a hook to access the user's authentication status and profile information.

import { ConnectButton } from "@farcaster/connect-kit";

export const Login = ({ nonce }: { nonce: string }) => {
  return (
    <ConnectButton
      nonce={nonce}
      onSuccess={({ fid, username }) =>
        console.log(`Hello, ${username}! Your fid is ${fid}.`)
      }
    />
  );
};

Props

Hooks

useSignIn

Hook for signing in a user. Connects to the relay server, generates a QR code and sign in link to present to the user, and polls relay server for wallet signature.

import { useAppClient } from "@farcaster/connect-kit";

function App() {
  const {
    signIn,
    qrCodeUri,
    data: { username },
    onSuccess: ({ fid }) => console.log("Your fid:", fid);
  } = useSignIn();

  return (
    <div>
      <button onClick={signIn}>Sign In</button>
      {qrCodeUri && (
        <span>
          Scan this: <img src={qrCodeUri} />
        </span>
      )}
      {username && `Hello, ${username}!`}
    </div>
  );
}

Parameters

Returns

  {
    signIn: () => void;
    reconnect: () => void;
    isSuccess: boolean;
    isPolling: boolean;
    isError: boolean;
    error: ConnectError;
    channelToken: string;
    connectUri: string;
    qrCodeUri: string;
    data: {
        state: "pending" | "complete";
        nonce: string;
        message: string;
        signature: string;
        fid: number;
        username: string;
        bio: string;
        displayName: string;
        pfpUrl: string;
    },
    validSignature: boolean;
  };

useUserData

Hook for reading information about the authenticated user.

import { useUserData } from "@farcaster/connect-kit";

function App() {
  const {
    isAuthenticated,
    userData: { fid, pfpUrl, username, displayName, bio },
  } = useUserData();

  return (
    <div>
     { isAuthenticated ? <p>Hello, {username}! Your fid is {fid}.<p>  : <p>You're not signed in.</p>}
    </div>
  );
}

Returns

  {
    isAuthenticated: boolean;
    userData: {
        fid: number;
        username: string;
        bio: string;
        displayName: string;
        pfpUrl: string;
    },
  };

useSignInMessage

Hook for reading the SIWE message and signature used to authenticate the user.

import { useUserData } from "@farcaster/connect-kit";

function App() {
  const { message, signature } = useSignInMessage();

  return (
    <div>
      <p>You signed: {message}</p>
      <p>Your signature: {signature}</p>
    </div>
  );
}

Returns

{
  message: string;
  signature: string;
}