From 2c7af138788f3b11b84f7f99277309bbd3e9a121 Mon Sep 17 00:00:00 2001 From: Joaquim Verges Date: Thu, 18 Jul 2024 11:27:54 +1200 Subject: [PATCH] react docs improvements (#517) * react docs improvements * lint --- .../v5/react-native/getting-started/page.mdx | 25 +- src/app/typescript/v5/react-native/page.mdx | 31 ++- .../react/connecting-wallets/hooks/page.mdx | 53 ++++ .../v5/react/connecting-wallets/page.mdx | 90 ++---- .../connecting-wallets/ui-components/page.mdx | 46 ++++ .../typescript/v5/react/extensions/page.mdx | 18 +- .../v5/react/getting-started/page.mdx | 257 ++++++++++++++++++ src/app/typescript/v5/react/page.mdx | 55 +++- src/app/typescript/v5/sidebar.tsx | 16 +- 9 files changed, 496 insertions(+), 95 deletions(-) create mode 100644 src/app/typescript/v5/react/connecting-wallets/hooks/page.mdx create mode 100644 src/app/typescript/v5/react/connecting-wallets/ui-components/page.mdx create mode 100644 src/app/typescript/v5/react/getting-started/page.mdx diff --git a/src/app/typescript/v5/react-native/getting-started/page.mdx b/src/app/typescript/v5/react-native/getting-started/page.mdx index 23a46293..8ed70d06 100644 --- a/src/app/typescript/v5/react-native/getting-started/page.mdx +++ b/src/app/typescript/v5/react-native/getting-started/page.mdx @@ -9,9 +9,17 @@ We recommend starting a new thirdweb React Native project using our CLI, which s In your CLI, run: ```bash -npx thirdweb create --react-native +npx thirdweb create --legacy-peer-deps --react-native ``` +or clone the [expo-starter](https://github.com/thirdweb-dev/expo-starter) repo using git. + + + ### Manual Installation To manually install the React Native SDK, you'll need to install the `@thirdweb/react-native-adapter` package from npm on top of the `thirdweb` package. @@ -48,9 +56,13 @@ amazon-cognito-identity-js // for authentication react-native-aes-gcm-crypto // for encryption react-native-quick-crypto@0.7.0-rc.6 // for fast hashing -// optional for coinbase wallet +// needed for coinbase wallet @coinbase/wallet-mobile-sdk react-native-mmkv + +// needed for UI components +react-native-svg +@react-native-clipboard/clipboard ``` @@ -161,12 +173,3 @@ If the Expo CLI says "Using Expo Go" when starting the app, press `s` to switch -### Starter app - -If you want to get started quickly run `npx thirdweb create --react-native`, or clone the [expo-starter](https://github.com/thirdweb-dev/expo-starter) repo using git. - - diff --git a/src/app/typescript/v5/react-native/page.mdx b/src/app/typescript/v5/react-native/page.mdx index 091da8cc..b8fa5eb8 100644 --- a/src/app/typescript/v5/react-native/page.mdx +++ b/src/app/typescript/v5/react-native/page.mdx @@ -17,7 +17,7 @@ import { Callout } from "@doc"; You can use all of the `thirdweb` and `thirdweb/react` exports in your React Native app, with some exceptions (see differences). -## Get Started +## Quickstart Many of the components and hooks in the React Native SDK use a [`client`](/typescript/v5/core/client) to interface with the core SDK and your private RPC endpoints. You'll need to create a `clientId` in the [Dashboard](https://thirdweb.com/create-api-key) to generate this client. @@ -27,14 +27,33 @@ Many of the components and hooks in the React Native SDK use a [`client`](/types title="Getting started" icon={ZapIcon} href="/typescript/v5/react-native/installation" + description="Get started with the React Native SDK" /> +## Starter kit + +If you want to get started quickly run: + +```bash +npx thirdweb create --legacy-peer-deps --react-native +``` + +or clone the [expo-starter](https://github.com/thirdweb-dev/expo-starter) repo using git. + + + + ## Usage - -### Starter app - -If you want to get started quickly run `npx thirdweb create --react-native`, or clone the [expo-starter](https://github.com/thirdweb-dev/expo-starter) repo using git. - - diff --git a/src/app/typescript/v5/react/connecting-wallets/hooks/page.mdx b/src/app/typescript/v5/react/connecting-wallets/hooks/page.mdx new file mode 100644 index 00000000..533cca00 --- /dev/null +++ b/src/app/typescript/v5/react/connecting-wallets/hooks/page.mdx @@ -0,0 +1,53 @@ +import { ArticleIconCard, createMetadata, DocImage, Stack } from "@doc"; +import { Wallet2Icon } from "lucide-react"; +import { ComponentIcon } from "lucide-react"; + +export const metadata = createMetadata({ + image: { + title: "Connecting Wallets", + icon: "react", + }, + title: "Connecting Wallets in thirdweb React SDK", + description: + "Connect wallets using ConnectButton, ConnectEmbed or useConnect hook", +}); + +# Connecting Wallets + +## Using Hooks + +You can build a completely custom UI for connecting the wallet using the [`useConnect`](/references/typescript/v5/useConnect) hook to connect any of [supported wallets](/typescript/v5/supported-wallets). + +```tsx +import { createThirdwebClient } from "thirdweb"; +import { useConnect } from "thirdweb/react"; +import { createWallet, injectedProvider } from "thirdweb/wallets"; + +const client = createThirdwebClient({ clientId }); + +function Example() { + const { connect, isConnecting, error } = useConnect(); + return ( + + ); +} +``` + +Refer to [`createWallet`](/references/typescript/v5/createWallet) and [`injectedProvider`](/references/typescript/v5/injectedProvider) for more information. + +## Post Connection + +Once the wallet is connected, you can use the [Wallet Connection hooks](/references/typescript/v5/hooks#wallet-connection) to get information about the connected wallet like getting the address, account, etc diff --git a/src/app/typescript/v5/react/connecting-wallets/page.mdx b/src/app/typescript/v5/react/connecting-wallets/page.mdx index bc9d9fb2..cd2ea2ac 100644 --- a/src/app/typescript/v5/react/connecting-wallets/page.mdx +++ b/src/app/typescript/v5/react/connecting-wallets/page.mdx @@ -1,7 +1,16 @@ import { ArticleIconCard, createMetadata, DocImage, Stack } from "@doc"; -import { Wallet2Icon } from "lucide-react"; -import ConnectWalletHeroImage from "../components/ConnectButton/images/connect-wallet-hero.webp"; -import { ComponentIcon } from "lucide-react"; +import { + ZapIcon, + ScrollTextIcon, + ArrowRightLeftIcon, + WalletIcon, + BlocksIcon, + CodeIcon, + FolderTreeIcon, + PlugZapIcon, + ComponentIcon, + CableIcon, +} from "lucide-react"; export const metadata = createMetadata({ image: { @@ -15,76 +24,23 @@ export const metadata = createMetadata({ # Connecting Wallets -The SDK supports 350+ wallets out of the box, all you need to pass is their id. +Use the prebuilt UI components or create your own UX with hooks to connect wallets in your app. - - -## Using Components - -You can use [`ConnectButton`](/typescript/v5/react/components/ConnectButton) or [`ConnectEmbed`](/typescript/v5/react/components/ConnectEmbed) component for a quick, easy and customizable UI. - -These components provide a beautiful UI for connecting various wallets and take care of a lot of wallet-specific edge cases - so you can focus on building your app. - -These components support over 300+ wallets, including support in-app wallets and account abstraction. - -It also automatically shows all installed `EIP-6963` compliant wallet extensions installed by the user. - - - -## Using Hooks - -You can build a completely custom UI for connecting the wallet using the [`useConnect`](/references/typescript/v5/useConnect) hook to connect any of [support wallets](/typescript/v5/wallets). - -Refer to [`createWallet`](/references/typescript/v5/createWallet) and [`injectedProvider`](/references/typescript/v5/injectedProvider) for more information. - -```tsx -import { createThirdwebClient } from "thirdweb"; -import { useConnect } from "thirdweb/react"; -import { createWallet, injectedProvider } from "thirdweb/wallets"; - -const client = createThirdwebClient({ clientId }); - -function Example() { - const { connect, isConnecting, error } = useConnect(); - return ( - - ); -} -``` + -## Post Connection + -Once the wallet is connected, you can use the [Wallet Connection hooks](/references/typescript/v5/hooks#wallet-connection) to get information about the connected wallet like getting the address, account, etc diff --git a/src/app/typescript/v5/react/connecting-wallets/ui-components/page.mdx b/src/app/typescript/v5/react/connecting-wallets/ui-components/page.mdx new file mode 100644 index 00000000..6127dea2 --- /dev/null +++ b/src/app/typescript/v5/react/connecting-wallets/ui-components/page.mdx @@ -0,0 +1,46 @@ +import { ArticleIconCard, createMetadata, DocImage, Stack } from "@doc"; +import { Wallet2Icon } from "lucide-react"; +import ConnectWalletHeroImage from "../../components/ConnectButton/images/connect-wallet-hero.webp"; +import { ComponentIcon } from "lucide-react"; + +export const metadata = createMetadata({ + image: { + title: "Connecting Wallets", + icon: "react", + }, + title: "Connecting Wallets in thirdweb React SDK", + description: + "Connect wallets using ConnectButton, ConnectEmbed or useConnect hook", +}); + +# Connecting Wallets (UI Components) + +## Using Components + +You can use [`ConnectButton`](/typescript/v5/react/components/ConnectButton) or [`ConnectEmbed`](/typescript/v5/react/components/ConnectEmbed) component for a quick, easy and customizable UI. + +These components provide a beautiful UI for connecting various wallets and take care of a lot of wallet-specific edge cases - so you can focus on building your app. + +These components support over 300+ wallets, including support in-app wallets and account abstraction. + +It also automatically shows all installed `EIP-6963` compliant wallet extensions installed by the user. + + + +The SDK supports 350+ wallets out of the box, all you need to pass is their id. + + + + + + + +## Post Connection + +Once the wallet is connected, you can use the [Wallet Connection hooks](/references/typescript/v5/hooks#wallet-connection) to get information about the connected wallet like getting the address, account, etc + diff --git a/src/app/typescript/v5/react/extensions/page.mdx b/src/app/typescript/v5/react/extensions/page.mdx index 7634e096..75e45dc1 100644 --- a/src/app/typescript/v5/react/extensions/page.mdx +++ b/src/app/typescript/v5/react/extensions/page.mdx @@ -1,6 +1,20 @@ +import { Details, ArticleIconCard, Stack } from "@doc"; +import { + BlocksIcon, +} from "lucide-react"; + # Extensions -## Read extensions +Get familiar with the concept of extensions and how to use them in your project. + + + +## Using read extensions in React Any extension that reads from the blockchain can be used with `useReadContract`. The extension function itself be passed as the first argument, and the extension's parameters must be passed as the second argument. @@ -23,7 +37,7 @@ const MyComponent = () => { }; ``` -## Write extensions +## Using write extensions in React For extensions that write to the blockchain, they work the same way as raw contract calls using `useSendTransaction`. diff --git a/src/app/typescript/v5/react/getting-started/page.mdx b/src/app/typescript/v5/react/getting-started/page.mdx new file mode 100644 index 00000000..dbb441cd --- /dev/null +++ b/src/app/typescript/v5/react/getting-started/page.mdx @@ -0,0 +1,257 @@ +import { Stack, InstallTabs, Callout, Steps, Step, GithubTemplateCard } from "@doc"; + +# Getting Started + +You can get started by creating a new project or adding thirdweb to an existing project. + +## New Projects + +You can quickly create a new project with the thirdweb CLI + +```bash +npx thirdweb create app --legacy-peer-deps +``` + +or clone the the Next.js or Vite starter repo: + + + + + + + +## Existing Projects + +Install the thirdweb packages in your project + + + +## Build your app + + + + +At the root of your application, wrap your app with a `ThirdwebProvider` component. This keeps state around like the active wallet and chain. + +```tsx +// src/main.tsx +import { ThirdwebProvider } from "thirdweb/react"; + +function Main() { + return ( + + + + ); +} +``` + + + + + +Head to the [thirdweb dashboard](https://thirdweb.com/dashboard), create your account (or sign in), and click **Settings** to reach the [api keys](https://thirdweb.com/dashboard/settings/api-keys) page. + +Create an API key with `localhost` included in the allowed domains. Securely store your secret key and copy your client id for use in the next step. + +Create a `.env` file and add your client ID there. Then create a `client.ts` file with the following content: + +```tsx +// src/client.ts +import { createThirdwebClient } from "thirdweb"; + +export const client = createThirdwebClient({ + clientId: process.env.NEXT_PUBLIC_THIRDWEB_CLIENT_ID, +}); +``` + +You only need to define the client once. Exporting the client vartiable will allow you to use anywhere in your app. + + + + + +There are two ways to connect users to your app: + +- The prebuilt `ConnectButton` or `ConnectEmbed` components. +- Your own custom button. + +In this guide, we'll use the prebuilt `ConnectButton` component. + +```tsx +// src/app.tsx +import { client } from "./client"; +import { ConnectButton } from 'thirdweb/react'; + +function App() { + return ( +
+ +
+ ) +} +``` + +The `ConnectButton` and `ConnectEmbed` components come with built-in support for 350+ of wallets, 2000+ chains, fiat on-ramping, crypto swapping, transaction tracking, and more. + +You can also build your own custom button using the [`useConnect`](/typescript/v5/react/) hook. + + + + + +Once the user has connected their wallet, you can get the wallet address, balance, and other details. + +```tsx +import { useActiveAccount, useWalletBalance } from "thirdweb/react"; + +export default function App() { + const account = useActiveAccount(); + const { data: balance, isLoading } = useWalletBalance({ + client, + chain, + address: account.address, + }); + + return
+

Wallet address: {account.address}

+

Wallet balance: {balance?.displayValue} {balance?.symbol}

+
; +} +``` + + + + + +You can read contract state with the [`useReadContract`](/references/typescript/v5/useReadContract) hook. This works with any contract call. Simply specify the solidity function signature to get a type safe API for your contract. + +```tsx +import { client } from "./client"; +import { getContract } from "thirdweb"; +import { sepolia } from "thirdweb/chains"; +import { useReadContract } from "thirdweb/react"; + +const contract = getContract({ client, address: "0x...", chain: sepolia }); + +export default function App() { + const { data, isLoading } = useReadContract({ + contract, + method: "function tokenURI(uint256 tokenId) returns (string)", + params: [1n], // type safe params + }); + + return
+

Token URI: {data}

+
; +} +``` + +Using [Extensions](/typescript/v5/react/extensions) you can do powerful queries like getting all the owned NFTs of a specific address, and generate performant typesafe functions for your contract. + +```tsx +import { client } from "./client"; +import { getContract } from "thirdweb"; +import { sepolia } from "thirdweb/chains"; +import { useReadContract } from "thirdweb/react"; +import { getOwnedNFTs } from "thirdweb/extensions/erc721"; + +const contract = getContract({ client, address: "0x...", chain: sepolia }); + +export default function App() { + const { data: ownedNFTs } = useReadContract(getOwnedNFTs, { + contract, + address: "0x...", + }); + + return
+

Owned NFTs: {ownedNFTs}

+
; +} +``` + + + + + +You can execute transactions with the [`useSendTransaction`](/references/typescript/v5/useSendTransaction) hook. Prepare a transaction with the [`prepareContractCall`](/references/typescript/v5/prepareContractCall) function and pass it to the `sendTransaction` function. + +```tsx +import { client } from "./client"; +import { getContract } from "thirdweb"; +import { sepolia } from "thirdweb/chains"; +import { useSendTransaction } from "thirdweb/react"; + +const contract = getContract({ client, address: "0x...", chain: sepolia }); + +export default function App() { + const { mutate: sendTransaction } = useSendTransaction(); + + const onClick = async () => { + const transaction = prepareContractCall({ + contract, + method: "function mint(address to)", + params: ["0x..."], // type safe params + }); + sendTransaction(transaction); + }; + + return
+ +
; +} +``` + +Using [Extensions](/typescript/v5/react/extensions) you can do more complex transactions like a claim, batch mint, and more. These will handle all the preprocessing needed before calling the contract. + +```tsx +import { client } from "./client"; +import { getContract } from "thirdweb"; +import { sepolia } from "thirdweb/chains"; +import { useSendTransaction } from "thirdweb/react"; +import { mintTo } from "thirdweb/extensions/erc721"; + +const contract = getContract({ client, address: "0x...", chain: sepolia }); + +export default function App() { + const { mutate: sendTransaction } = useSendTransaction(); + + const onClick = async () => { + // this mint extension handles uploading metadata to IPFS and pining it + const transaction = mintTo({ + contract, + to: "0x...", + nft: { + name: "NFT Name", + description: "NFT Description", + image: "https://example.com/image.png", + }, + }); + sendTransaction(transaction); + }; + + return
+ +
; +} +``` + + + + +## Learn more + +You know have all the basics to build your own app with thirdweb. You can also check out the [thirdweb SDK reference](/references/typescript/v5) to learn more about the different hooks and functions available. \ No newline at end of file diff --git a/src/app/typescript/v5/react/page.mdx b/src/app/typescript/v5/react/page.mdx index d43564c2..a9ccdb9c 100644 --- a/src/app/typescript/v5/react/page.mdx +++ b/src/app/typescript/v5/react/page.mdx @@ -1,4 +1,4 @@ -import { Details, ArticleIconCard, Stack } from "@doc"; +import { Details, ArticleIconCard, Stack, GithubTemplateCard } from "@doc"; import { ZapIcon, ScrollTextIcon, @@ -11,45 +11,94 @@ import { ComponentIcon, CableIcon, } from "lucide-react"; +import { TypeScriptIcon } from "@/icons"; # React SDK `thirdweb/react` exports various Components and Hooks to easily connect wallets & interact with smart contracts -## Get Started +## Quickstart + +Follow this [guide](/typescript/v5/react/getting-started) to get started with the React SDK. + + + + +## Starter kits + +You can quickly create a new project with the thirdweb CLI + +```bash +npx thirdweb create app --legacy-peer-deps +``` + +or clone the the Next.js or Vite starter repo: + + + + + + + +## Usage Many of the components and hooks in the React SDK use a [`client`](/typescript/v5/core/client) to interface with the core SDK and your private RPC endpoints. You'll need to create a `clientId` in the [Dashboard](https://thirdweb.com/create-api-key) to generate this client. + + diff --git a/src/app/typescript/v5/sidebar.tsx b/src/app/typescript/v5/sidebar.tsx index 5fe5bbeb..35cf06a2 100644 --- a/src/app/typescript/v5/sidebar.tsx +++ b/src/app/typescript/v5/sidebar.tsx @@ -114,6 +114,10 @@ export const sidebar: SideBar = { name: "Overview", href: reactSlug, }, + { + name: "Getting Started", + href: `${reactSlug}/getting-started`, + }, { name: "ThirdwebProvider", href: `${reactSlug}/ThirdwebProvider`, @@ -121,6 +125,16 @@ export const sidebar: SideBar = { { name: "Connecting Wallets", href: `${reactSlug}/connecting-wallets`, + links: [ + { + name: "UI Components", + href: `${reactSlug}/connecting-wallets/ui-components`, + }, + { + name: "Hooks", + href: `${reactSlug}/connecting-wallets/hooks`, + }, + ], }, { name: "UI Components", @@ -158,7 +172,7 @@ export const sidebar: SideBar = { }, { name: "Hooks", - href: `/references/typescript/v5/hooks`, + href: "/references/typescript/v5/hooks", }, ], },