DOCSEARCHbyAlgolia
Submit Docs

OnchainKit Documentation

repository·main·Indexed 22 days ago

https://github.com/coinbase/onchainkit

OnchainKit provides React components and TypeScript utilities for building high-quality onchain applications, specifically optimized for Base and Farcaster Mini-Apps. It includes the create-onchain CLI for bootstrapping Next.js projects, a Mini-App manifest generator, and integrated support for Wagmi and Tailwind CSS. Version 1.0.0 requires React 19 and Node.js v20+.

Tokens
24.5K
Snippets
79
Records
119
Agent score
77%

What's inside OnchainKit

  1. How OnchainKit v1.0.0 styling and theming works

    main

    OnchainKit v1.0.0 uses a scoped styling system built with Tailwind CSS v4. Styles are self-contained and designed to prevent conflicts with your application's theme.

    Scoped Styles

    • Class Prefixing: All OnchainKit classes are prefixed with ock:.
    • Theme Variables: Custom CSS properties use the --ock- prefix.
    • Data Attributes: Theming is controlled via the data-ock-theme attribute on an element (typically <html>).

    Custom Theming

    If you are customizing OnchainKit themes, you must migrate your CSS variables to use the --ock- prefix and apply them within a [data-ock-theme] selector.

    /* After (v1.0) */
[data-ock-theme='custom'] {
  --ock-text-foreground: #000000;
  --ock-background: #ffffff;
}

    To apply a theme:

    <html data-ock-theme="default-dark">
  {/* Your app content */}
</html>

  2. Bootstrap an onchain app with create-onchain

    main

    To quickly start building an onchain application with all necessary dependencies and configurations included, use the create-onchain CLI tool.

    Run the following command in your terminal:

    npm create onchain

  3. Generate a Mini-App manifest for an existing project

    main

    If you have an existing project and need to generate a Farcaster Mini-App manifest, run the tool with the --manifest flag. The process involves:

    1. Launching a UI to connect your Farcaster custody wallet.
    2. Generating and signing your manifest.
    3. Automatically saving the credentials to your .env file using the following keys:
      • FARCASTER_HEADER
      • FARCASTER_PAYLOAD
      • FARCASTER_SIGNATURE
    npx create-onchain --manifest

  4. Setup the OnchainKit Next.js template

    main

    This project is a Next.js application bootstrapped using create-onchain. To get started locally, install the dependencies and run the development server.

    1. Install dependencies

    Use your preferred package manager:

    npm install
# or
yarn install
# or
pnpm install
# or
bun install

    2. Run the development server

    Start the local server with:

    npm run dev
# or
yarn dev
# or
pnpm dev
# or
bun dev

    Once running, open http://localhost:3000 in your browser. You can begin customizing the application by editing app/page.tsx, which supports hot-reloading.

    npm install
npm run dev

  5. Install dependencies and run the MiniKit Next.js template

    main

    This project is a Next.js application bootstrapped with create-onchain. To get started locally, install the project dependencies using your preferred package manager and then start the development server.

    1. Install dependencies

      npm install
# or
yarn install
# or
pnpm install
# or
bun install

    2. Run the development server

      npm run dev
# or
yarn dev
# or
pnpm dev
# or
bun dev

    3. View the application Open http://localhost:3000 in your browser.

    To begin customizing the application, modify app/page.tsx. The development server supports Hot Module Replacement (HMR) and will auto-update the page as you save changes.

    npm install
npm run dev

  6. Bootstrap a Farcaster Mini-App project

    main

    Use create-onchain with the --mini flag to bootstrap a project optimized for building Farcaster Mini-Apps. This template includes:

    • Next.js 14+ with App Router
    • MiniKit components and hooks
    • Farcaster Frame utilities
    • OnchainKit for Wallet Connection and sample Transactions
    • Tailwind CSS for styling
    • TypeScript support
    • ESLint and Prettier configuration
    npx create-onchain --mini
# or
npx create-onchain --template=minikit-basic

  7. Install and run OnchainKit packages in the monorepo

    main

    OnchainKit is managed as a monorepo using pnpm workspaces.

    Requirements

    • Node.js v20
    • pnpm v10

    Running scripts

    To run a script within a specific package, use the --filter (or -F) flag:

    pnpm [-F | --filter] <package-name> <script-name>

    To run a script across all packages in the monorepo:

    pnpm run <script-name>

  8. Develop the Mini-App Manifest Generator

    main

    To develop this package locally, ensure you have Node.js v18 and pnpm v10 installed. Use the following commands to manage the development lifecycle:

    • Install dependencies: pnpm install
    • Start development server: pnpm dev
    • Build for production: pnpm build
    • Run tests: pnpm test
    • Run tests with coverage: pnpm test:coverage
    pnpm install
pnpm dev
pnpm build
pnpm test
pnpm test:coverage

  9. Run the Playground development server

    main
    To start the development server for the playground, use the pnpm dev:watch command. This command starts the Next.js development server and enables a watch mode that monitors the src directory for changes, automatically rebuilding the @coinbase/onchainkit package whenever updates are detected. Once running, the application is accessible at http://localhost:3000.
    pnpm dev:watch

  11. Upgrade OnchainKit from v0.x to v1.0.0

    main

    Upgrading to v1.0.0 requires updating dependencies, consolidating providers, and updating Farcaster SDK references.

    Prerequisites

    • React: v19 (v18 is no longer supported)
    • Node.js: v20 or higher
    • TypeScript: v5.8+ (recommended)

    Step 1: Update Dependencies

    Install the new version along with the required peer dependencies (viem and wagmi):

    npm install @coinbase/onchainkit@1.0.0 react@19 react-dom@19 viem@^2.27 wagmi@^2.16

    Step 2: Update Provider Setup

    MiniKitProvider has been removed. You must now use OnchainKitProvider and include the required CSS import. MiniKit functionality is now configured via the miniKit prop.

    import { OnchainKitProvider } from "@coinbase/onchainkit";
import "@coinbase/onchainkit/styles.css";

export function RootProvider({ children }) {
  return (
    <OnchainKitProvider
      apiKey={process.env.NEXT_PUBLIC_ONCHAINKIT_API_KEY}
      chain={base}
      config={{
        appearance: {
          mode: "dark", // or "light" or "auto"
        },
        wallet: {
          display: "modal", // or "dropdown"
          preference: "all",
        },
      }}
      miniKit={{
        enabled: true,
        autoConnect: true,
        notificationProxyUrl: undefined, // optional
      }}
    >
      {children}
    </OnchainKitProvider>
  );
}

    Step 3: Update Farcaster SDK

    Replace the old Farcaster frame SDK with the new Mini App SDK in your package.json:

    • Remove: @farcaster/frame-sdk
    • Add: @farcaster/miniapp-sdk