Integrating MiniKit with Existing Applications

This guide helps developers integrate MiniKit into an existing Next.js project. It includes installation steps, provider setup and environment configuration.

Prerequisites

Before you begin, confirm the following:

You are using a Next.js project with the app/ directory structure.
Your app is deployed and publicly accessible (e.g. via Vercel).
Farcaster account
Coinbase Developer Platform Account: Sign up for a Coinbase Developer Platform to retrieve your CDP API Key.

Step 1: Install required dependencies

MiniKit is available as part of Onchainkit.

npm install @coinbase/onchainkit

Step 2: Add the MiniKitProvider to your app

Create and use the MiniKitProvider to initialise SDK context for your application.

File: providers/MiniKitProvider.tsx

'use client';
 
import { MiniKitProvider } from '@coinbase/minikit';
 
export function MiniKitContextProvider({ children }: { children: ReactNode }) {
  return (
    <MiniKitProvider
      apiKey={process.env.NEXT_PUBLIC_CDP_CLIENT_API_KEY}
      chain={base}
    >
      {props.children}
    </MiniKitProvider>
  );
}

Then wrap your app in app/layout.tsx:

import { MiniKitContextProvider } from '@/providers/MiniKitProvider';
 
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <MiniKitContextProvider>
          {children}
        </MiniKitContextProvider>
      </body>
    </html>
  );
}

Step 3: Initialise MiniKit in your main page

Use the useMiniKit hook to access the frame context and trigger readiness.

File: app/page.tsx

'use client';
 
import { useEffect, useState } from 'react';
import { useMiniKit } from '@coinbase/onchainkit/minikit';
 
export default function HomePage() {
  const { setFrameReady, isFrameReady } = useMiniKit();
 
  // The setFrameReady() function is called when your mini-app is ready to be shown
  useEffect(() => {
    if (!isFrameReady) {
      setFrameReady();
    }
  }, [setFrameReady, isFrameReady]);
 
  return <div>Your app content goes here</div>;
}

What `useMiniKit` Gives You

The useMiniKit() hook gives you access to everything your Mini App needs to understand the Farcaster session. This includes

The useMiniKit() hook also gives you access to session context from the client:

const { context } = useMiniKit();

This includes:

context.user.fid: the Farcaster ID of the user
context.client.added: whether they’ve added the Mini App
context.location: where the app was launched from (e.g. cast, launcher)

You can use this to personalize the experience or trigger events.

Step 4: Set environment variables

Add the required environment variables to your project and deployment platform.

NEXT_PUBLIC_ONCHAINKIT_PROJECT_NAME=
NEXT_PUBLIC_URL=
NEXT_PUBLIC_ICON_URL=
NEXT_PUBLIC_ONCHAINKIT_API_KEY=
 
FARCASTER_HEADER=
FARCASTER_PAYLOAD=
FARCASTER_SIGNATURE=
NEXT_PUBLIC_APP_ICON=
 
NEXT_PUBLIC_APP_SUBTITLE=
NEXT_PUBLIC_APP_DESCRIPTION=
NEXT_PUBLIC_APP_SPLASH_IMAGE=
NEXT_PUBLIC_SPLASH_BACKGROUND_COLOR=
NEXT_PUBLIC_APP_PRIMARY_CATEGORY=
NEXT_PUBLIC_APP_HERO_IMAGE=
NEXT_PUBLIC_APP_TAGLINE=
NEXT_PUBLIC_APP_OG_TITLE=
NEXT_PUBLIC_APP_OG_DESCRIPTION=
NEXT_PUBLIC_APP_OG_IMAGE=

Step 5: Generate the manifest

Use the Onchainkit CLI to generate a farcaster.json file, which describes your app’s metadata to the Farcaster protocol.

npx create-onchain --manifest

The wallet that you connect must be your Farcaster custody wallet. You can import this wallet to your preferred wallet using the recovery phrase. You can find your recovery phrase in the Warpcast app under Settings -> Advanced -> Farcaster recovery phrase.

Once connected, add the vercel url and sign the manifest. This will automatically update your .env variables locally, but we'll need to update Vercel's .env variables.

Step 6: Create .well-known/farcaster.json

The farcaster.json file contains metadata that allows clients to identify the Mini App, the author of the Mini App, and other useful data like descriptions and tags, to allow for discovery.

Create a route handler for the Farcaster integration at app/.well-known/farcaster.json/route.ts:

 
function withValidProperties(
  properties: Record<string, undefined | string | string[]>,
) {
  return Object.fromEntries(
    Object.entries(properties).filter(([key, value]) => {
      if (Array.isArray(value)) {
        return value.length > 0;
      }
      return !!value;
    }),
  );
}
 
export async function GET() {
  const URL = process.env.NEXT_PUBLIC_URL;
 
  return Response.json({
    accountAssociation: {
      header: process.env.FARCASTER_HEADER,
      payload: process.env.FARCASTER_PAYLOAD,
      signature: process.env.FARCASTER_SIGNATURE,
    },
    frame: withValidProperties({
      version: "1",
      name: process.env.NEXT_PUBLIC_ONCHAINKIT_PROJECT_NAME,
      subtitle: process.env.NEXT_PUBLIC_APP_SUBTITLE,
      description: process.env.NEXT_PUBLIC_APP_DESCRIPTION,
      screenshotUrls: [],
      iconUrl: process.env.NEXT_PUBLIC_APP_ICON,
      splashImageUrl: process.env.NEXT_PUBLIC_APP_SPLASH_IMAGE,
      splashBackgroundColor: process.env.NEXT_PUBLIC_SPLASH_BACKGROUND_COLOR,
      homeUrl: URL,
      webhookUrl: `${URL}/api/webhook`,
      primaryCategory: process.env.NEXT_PUBLIC_APP_PRIMARY_CATEGORY,
      tags: [],
      heroImageUrl: process.env.NEXT_PUBLIC_APP_HERO_IMAGE,
      tagline: process.env.NEXT_PUBLIC_APP_TAGLINE,
      ogTitle: process.env.NEXT_PUBLIC_APP_OG_TITLE,
      ogDescription: process.env.NEXT_PUBLIC_APP_OG_DESCRIPTION,
      ogImageUrl: process.env.NEXT_PUBLIC_APP_OG_IMAGE,
    }),
  });
}

Step 7: Define Farcaster frame metadata

Use the generateMetadata function to create the metadata that clients use to render your Mini App in posts. This function generates the preview card, button configuration, and launch parameters that appear when your app's URL is shared.

File: app/layout.tsx

export async function generateMetadata(): Promise<Metadata> {
  const URL = process.env.NEXT_PUBLIC_URL;
  return {
    title: process.env.NEXT_PUBLIC_ONCHAINKIT_PROJECT_NAME,
    description:
      "Generated by `create-onchain --mini`, a Next.js template for MiniKit",
    other: {
      "fc:frame": JSON.stringify({
        version: "next",
        imageUrl: process.env.NEXT_PUBLIC_APP_HERO_IMAGE,
        button: {
          title: `Launch ${process.env.NEXT_PUBLIC_ONCHAINKIT_PROJECT_NAME}`,
          action: {
            type: "launch_frame",
            name: process.env.NEXT_PUBLIC_ONCHAINKIT_PROJECT_NAME,
            url: URL,
            splashImageUrl: process.env.NEXT_PUBLIC_SPLASH_IMAGE,
            splashBackgroundColor:
              process.env.NEXT_PUBLIC_SPLASH_BACKGROUND_COLOR,
          },
        },
      }),
    },
  };
}

Step 8: Learn about MiniKit hooks

MiniKit provides a set of hooks designed to help you build rich, social experiences within your mini app.

These include:

-useNotification – to send in-app and push notifications to users

-useAddFrame – to allow users to save your mini app to their Farcaster client

-UseViewProfile - Display a users profile

These hooks help your mini app feel native to the Farcaster feed and enable deeper engagement.

For a complete list of available utilities and examples, refer to the MiniKit Documentation.

Step 8: Share and Preview Your Mini App on Farcaster

Once your Mini App is deployed and correctly configured, sharing its URL in a cast will automatically render an embedded experience in Warpcast and other Farcaster clients.

What to check before sharing:

Your app is deployed at a public domain and accessible via HTTPS.
Your manifest.json is correctly generated and served at:

https://yourdomain.com/manifest.json

How to test:

Use Warpcast’s manifest dev tool to preview how your app will appear: https://warpcast.com/~/developers/mini-apps/manifest

This tool validates:

That your manifest can be loaded
Your frame metadata is correctly formatted
Button actions and preview image are functioning

You can also use our debugging guide

How to share:

Once verified, simply create a cast with a link to your app’s URL. If all setup steps are correct, Warpcast will automatically display your Mini App as an interactive embed.