Getting Started with React ⚛️

Overview

Starkweb is a React Hooks library for Starknet. To learn more about the rationale behind the project, check out the Why We Built Starkweb section.

Automatic Installation

For new projects, we recommend setting up your Starkweb application with the create-starkweb command line interface (CLI). This tool initializes a new Starkweb project with TypeScript and installs all required dependencies.

pnpm

pnpm create starkweb

Once the command runs, you'll see some prompts to complete.

Project name: › starkweb-project
Select a framework: › React
...

After the prompts, create-starkweb will create a directory with your project name and install the required dependencies. Check out the README.md for further instructions (if required).

Manual Installation

Before you begin, here are a few important notes:

TanStack Query: This async state manager handles requests, caching, and more, making it a valuable tool when working with Wolf.
TypeScript: While TypeScript is optional, we highly recommend it for improved type safety and development experience.

Install Packages

To manually add Starkweb to your project, install the required packages:

pnpm

pnpm add starkweb @tanstack/react-query

You can also use Starkweb via an ESM-compatible CDN like esm.sh. Just add a <script type="module"> tag at the end of your HTML file with the content below:

<script type="module">
  import React from "https://esm.sh/react@18.3.1"
  import { QueryClient } from "https://esm.sh/@tanstack/react-query"
  import { createConfig } from "https://esm.sh/starkweb"
</script>

Create Config

Create and export a new Starkweb config using createConfig:

config.ts

import { http, createConfig } from "starkweb/react";
import { mainnet, sepolia } from "starkweb/react/chains";
 
export const config = createConfig({
  chains: [mainnet, sepolia],
  transports: {
    [mainnet.chain_id]: http(),
    [sepolia.chain_id]: http(),
  },
});

In this example, Starkweb is configured to use the Mainnet and Sepolia chains and the injected connector. For more configuration options, check out the createConfig docs.

Wrap App in Context Provider

Wrap your app in the StarkwebProvider React Context Provider and pass the config you created earlier to the value property:

app.tsx

import { StarkwebProvider } from "starkweb/react"
import { config } from "./config"
 
function App() {
  return (
    <StarkwebProvider config={config}>
      {/** ... */}
    </StarkwebProvider> 
  )
}

Setup TanStack Query

Inside the StarkwebProvider, wrap your app in a TanStack Query React Context Provider, e.g. QueryClientProvider, and pass a new QueryClient instance to the client property:

app.tsx

import { QueryClient, QueryClientProvider } from "@tanstack/react-query"
import { StarkwebProvider } from "starkweb/react"
import { config } from "./config"
 
const queryClient = new QueryClient() 
 
function App() {
  return (
    <StarkwebProvider config={config}>
      <QueryClientProvider client={queryClient}>
        {/** ... */}
      </QueryClientProvider>
    </StarkwebProvider>
  )
}

Use Wolf

Now that everything is set up, every component inside the Wolf and TanStack Query Providers can use Wolf React Hooks.

profile.tsx

import { useAccount, useBalance } from "starkweb/react"
 
export function Profile() {
  const { address } = useAccount()
  const { data, error, status } = useBalance({ address })
  if (status === "pending") return <div>Loading token balance</div>
  if (status === "error")
    return <div>Error fetching token balance: {error.message}</div>
  return <div>Token Balance: {data}</div>
}

Next Steps

For more information on what to explore next, check out the following:

React Hooks: Browse the available React Hooks and learn how to use them.