React Web

Learn how to use the Lens React SDK with a web app.

Quick Start

Follow these steps to integrate the Lens React SDK into your web app.

Install SDK

Install the @lens-protocol/react-web package.

npm install @lens-protocol/react-web@latest

Install Wagmi

This guide illustrates an integration using Wagmi v2 as the library for interacting with the connected wallet. If you're using a different wallet integration strategy, you can create custom bindings tailored to your needs.

Install the Lens Wagmi bindings package and its peer dependencies.

npm install viem@2 wagmi@2 @tanstack/react-query@5 @lens-protocol/wagmi@latest

Follow the Wagmi documentation to create the Wagmi configuration.

import { createConfig, http } from "wagmi";import { polygon } from "wagmi/chains";
const wagmiConfig = createConfig({  chains: [polygon],  transports: {    [polygon.id]: http(),  },});

Create Config

Next, use this configuration with the bindings from the @lens-protocol/wagmi package to generate the LensConfig object.

import { LensConfig, production } from "@lens-protocol/react-web";import { bindings } from "@lens-protocol/wagmi";
const lensConfig: LensConfig = {  environment: production,  bindings: bindings(wagmiConfig),};

Wrap Your App

Finally, wrap your app with the <LensProvider> component and pass the LensConfig object you created earlier.

App.tsximport { LensProvider } from "@lens-protocol/react-web";
export function App() {  return <LensProvider config={lensConfig}>{/** Your App */}</LensProvider>;}

To wrap up, here's an example with all the steps put together.

import { LensConfig, LensProvider, production } from "@lens-protocol/react-web";import { bindings } from "@lens-protocol/wagmi";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";import { WagmiProvider, createConfig, http } from "wagmi";import { polygon } from "wagmi/chains";
const queryClient = new QueryClient();
const wagmiConfig = createConfig({  chains: [polygon],  transports: {    [polygon.id]: http(),  },});
const lensConfig: LensConfig = {  environment: production,  bindings: bindings(wagmiConfig),};
export function App() {  return (    <WagmiProvider config={wagmiConfig}>      <QueryClientProvider client={queryClient}>        <LensProvider config={lensConfig}>{/** Your App */}</LensProvider>      </QueryClientProvider>    </WagmiProvider>  );}

That's it—you're ready to use the Lens React SDK in your app.

Next.js

If you're planning to use Next.js, you can leverage the create-next-app CLI tool along with the lens-next-app template we've prepared. This template includes a Next.js project with the Lens React SDK and ConnectKit already integrated. To bootstrap your new Lens app, simply execute one of the commands below.

npx create-next-app -e https://github.com/lens-protocol/lens-sdk/tree/main/examples/lens-next-app

Additionally, you must set up the WalletConnect's Project ID in the .env file. You can quickly and easily create a free Project ID at WalletConnect Cloud.

Then follow the steps in the README file of the generated project to get started. Happy coding!

Additional Options

SDK Playground

You can play with the Lens React SDK in the Playground.

Custom Bindings

If you're not using Wagmi, you can create your own bindings by implementing the IBindings interface.

The example below demonstrates how to create custom bindings for a Wallet from ethers.js.

import { InfuraProvider, Wallet } from "ethers";import { IBindings } from "@lens-protocol/react-web";
const provider = new providers.InfuraProvider("maticmum");const wallet = new Wallet("<your-private-key>", provider);
export const bindings: IBindings = {  getProvider: () => provider,  getSigner: () => wallet,};

Debug Mode

The LensConfig object allows you to enable debug mode by setting the debug property to true. Doing so will:

Log additional information to the console for debugging purposes.
Disable gas estimation for self-funded transactions.
Enable Apollo Client Devtools, providing you with a detailed look at the operations of the integrated Apollo client.

App.tsxconst lensConfig: LensConfig = {  // ...  debug: true,};

React Suspense

The Lens React SDK offers experimental support for data fetching using React Suspense. This feature is being introduced gradually across all relevant hooks.

Hooks that support React Suspense include a suspense option. When this option is set to true, the hook suspends rendering until data is available. If an unexpected error occurs during this process, it will be thrown, allowing you to handle it using an error boundary.

Any known failure scenarios will be returned as part of the error object, which you can handle as part of your rendering logic.

import { publicationId, usePublication } from "@lens-protocol/react-web";
export function Publication({ id }: { id: string }) {  const { data, error } = usePublication({    forId: publicationId(id),    suspense: true,  });
  // error is NotFoundError  if (error) {    return <p>Publication not found.</p>;  }
  return <PublicationCard publication={data} />;}

The methodology described above can be applied to any of the following hooks:

Wagmi 1.x

If you are using Wagmi 1.x, follow the steps below.

First, install the wagmi-v1 tag of the @lens-protocol/wagmi package.

npm install @lens-protocol/wagmi@wagmi-v1

Then, create the LensConfig object like this.

import { LensConfig, production } from "@lens-protocol/react-web";import { bindings } from "@lens-protocol/wagmi";
const lensConfig: LensConfig = {  environment: production,  bindings: bindings(),};

Below a comprehensive example.

import { LensConfig, LensProvider, production } from "@lens-protocol/react-web";import { bindings } from "@lens-protocol/wagmi";
import { configureChains, createConfig } from "wagmi";import { polygon } from "wagmi/chains";import { InjectedConnector } from "wagmi/connectors/injected";import { publicProvider } from "wagmi/providers/public";
const { publicClient, webSocketPublicClient } = configureChains(  [polygon],  [publicProvider()]);
const wagmiConfig = createConfig({  autoConnect: true,  publicClient,  webSocketPublicClient,  connectors: [    new InjectedConnector({      options: {        shimDisconnect: false,      },    }),  ],});
const lensConfig: LensConfig = {  environment: production,  bindings: bindings(),};
export function App() {  return (    <WagmiConfig config={wagmiConfig}>      <LensProvider config={lensConfig}>{/* Your App */}</LensProvider>    </WagmiConfig>  );}