Frontend Stack

Core technology choices and patterns for frontend apps. See Frontend Architecture for overview and ownership.

Data fetching & async state

@tanstack/react-query: default choice for async data and server state (caching, dedupe, retries)
@repo/react: generated React Query hooks and integration for the OpenAPI client surface
@repo/core: generated, runtime-agnostic API client and types
@lukemorales/query-key-factory: centralized query key factories (for hand-written queries)

URL and local state

nuqs: URL-based state for shareable UI state (filters, search, tabs, pagination)
ahooks: useSetState for grouped ephemeral state, useLocalStorageState for persistence

Validation, errors, utilities

zod: schema validation at boundaries (prefer z.infer<typeof schema>)
react-error-boundary: component subtree failure isolation (see Error Handling)
@repo/utils: shared utilities (prefer subpath imports)
lodash-es: per-function imports for common operations
nanoid: unique IDs when needed

Web3 & wallet auth

Wallet hooks live in apps/next (@/hooks/, @/wallet/). @repo/react exposes only verify hooks (useVerifyWeb3Auth, useVerifyLinkWallet).

useWallet (@/hooks/use-wallet): returns adapter for a chain from WalletProvider context
useWalletAuth (@/hooks/use-wallet-auth): wallet sign-in via SIWE/SIWS
useLinkWallet (@/hooks/use-link-wallet): link connected wallet to account (Bearer required)
useLinkEmail (@repo/react): request link email + verify from token

WalletProvider and adapters: In apps/next, WalletAdaptersInjector bridges wagmi + Solana into adapters, enforces single-wallet mode, and triggers sign-out on wallet disconnect when session was created by wallet.

Post-login home: After auth (magic link or wallet), users are redirected to /. The home page renders merged dashboard content including Link wallet, Link email (formerly on /dashboard).

See Authentication for auth flows, SIWE/SIWS, and account linking.

Web3 stack hierarchy

Chain libraries

viem: low-level Ethereum interactions (address validation, transactions)
wagmi: React hooks for Ethereum (built on viem + TanStack Query)
@solana/wallet-adapter-react: Solana wallet connection

Query key factory (example)

import { createQueryKeys } from "@lukemorales/query-key-factory"

export const users = createQueryKeys("users", {
  detail: (id: string) => ({
    queryKey: [id],
    queryFn: () => fetchUser(id),
  }),
})

nuqs URL state (example)

import { parseAsInteger, parseAsString, useQueryStates } from "nuqs"

const [filters, setFilters] = useQueryStates({
  search: parseAsString.withDefault(""),
  page: parseAsInteger.withDefault(1),
})

Frontend Stack

On this page