> ## Documentation Index > Fetch the complete documentation index at: https://base-a060aa97-eb-mini-app-ia-overhaul.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Migrate an Existing App > Guide for integrating MiniKit into an existing Next.js project with installation, provider setup, and environment configuration This guide helps developers integrate MiniKit into an existing Next.js project. It includes installation steps, provider setup and environment configuration. This guide assumes you want to add MiniKit to an existing application. For new projects, use the [MiniKit CLI](/base-app/build-with-minikit/quickstart) for automatic setup. ## Prerequisites Before you begin, confirm the following: You are using a Next.js project with the `app/` directory structure (App Router). Your app is deployed and publicly accessible (e.g. via Vercel) with HTTPS enabled. You have an active Farcaster account for testing and access to your custody wallet. Sign up for a [Coinbase Developer Platform](https://portal.cdp.coinbase.com/) to retrieve your CDP API Key. ## Integration Steps MiniKit is available as part of OnchainKit. ```shell npm install @coinbase/onchainkit ``` Verify installation by checking that `@coinbase/onchainkit` appears in your `package.json`. Create and use the `MiniKitProvider` to initialise SDK context for your application. **File: `providers/MiniKitProvider.tsx`** ```jsx 'use client'; import { MiniKitProvider } from '@coinbase/onchainkit/minikit'; import { ReactNode } from 'react'; import { base } from 'wagmi/chains'; export function MiniKitContextProvider({ children }: { children: ReactNode }) { return ( {children} ); } ``` Then wrap your app in `app/layout.tsx`: ```jsx import { MiniKitContextProvider } from '@/providers/MiniKitProvider'; export default function RootLayout({ children, }: { children: React.ReactNode, }) { return ( {children} ); } ``` The provider automatically configures wagmi and react-query, and sets up connectors to use Farcaster when available. Use the `useMiniKit` hook to access the frame context and trigger readiness. **File: `app/page.tsx`** ```jsx '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

Your app content goes here

; } ``` The `setFrameReady()` function removes the splash screen and shows your application. Only call this when your app is fully loaded and ready for user interaction. Add the required environment variables to your project and deployment platform. These variables are essential for your MiniKit app to function: The name of your Mini App as it appears to users The deployed URL of your application (must be HTTPS) Your Coinbase Developer Platform API key Generated during manifest creation for account association Generated during manifest creation for account association Generated during manifest creation for account association These variables enhance your app's appearance and metadata: URL to your app's icon (recommended: 48x48px PNG) Brief subtitle shown in app listings Detailed description of your app's functionality URL to splash screen image shown during app loading Hex color code for splash screen background (e.g., "#000000") Primary category for app discovery (e.g., "social", "gaming", "utility") Hero image URL displayed in cast previews Short, compelling tagline for your app Open Graph title for social media sharing Open Graph description for social media sharing Open Graph image URL for social media previews Don't forget to include all referenced images in your `public/` folder and ensure they're accessible via HTTPS. Use the OnchainKit CLI to generate account association credentials and update your environment variables. ```shell npx create-onchain --manifest ``` **Important:** The wallet you connect must be your Farcaster custody wallet. You can import this wallet using the recovery phrase found in Farcaster under Settings → Advanced → Farcaster recovery phrase. Follow these substeps: 1. Connect your Farcaster custody wallet 2. Add your deployed Vercel URL 3. Sign the manifest to generate association credentials 4. The CLI will automatically update your local `.env` file After running this command locally, remember to update your deployment platform's environment variables with the generated `FARCASTER_HEADER`, `FARCASTER_PAYLOAD`, and `FARCASTER_SIGNATURE` values. The farcaster.json file contains metadata that allows clients to identify your Mini App and its capabilities. Create a route handler at `app/.well-known/farcaster.json/route.ts`: ```typescript function withValidProperties( properties: Record ) { 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, // use only while testing noindex: true, }), }); } ``` While testing your Mini App please add noIndex:true to your manifest - this is so the app is not indexed while in developement. Test this endpoint by visiting `https://yourdomain.com/.well-known/farcaster.json` to ensure it returns valid JSON. Configure the metadata that clients use to render your Mini App in posts and generate preview cards. **File: `app/layout.tsx`** ```typescript import { Metadata } from 'next'; export async function generateMetadata(): Promise { 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, }, }, }), }, }; } ``` All image and API URLs used here must be publicly accessible via HTTPS. Test each URL in your browser before deploying. Before sharing your Mini App, validate that everything is working correctly. Verify the following before going live: * ✅ App is deployed at a public HTTPS domain * ✅ All environment variables are set on your deployment platform * ✅ All referenced images are accessible in your `public/` folder * ✅ The `.well-known/farcaster.json` endpoint returns valid JSON * ✅ Your app loads without errors in a browser Use these tools to test your configuration: **Manifest Validator:** ``` https://farcaster.xyz/~/developers/mini-apps/manifest ``` This tool validates: * Manifest can be loaded successfully * Frame metadata is correctly formatted * Button actions and preview images are functioning * Account association is properly configured **Manual Testing:** 1. Visit your deployed URL directly in a browser 2. Check browser console for any errors 3. Verify the MiniKit context loads properly 4. Test frame readiness functionality Once validation passes: 1. **Create a cast** with your app's URL in Farcaster 2. **Verify the preview** displays your hero image and launch button 3. **Test the launch experience** by clicking the button 4. **Share with others** for feedback and testing If your app doesn't render as an embed, double-check your manifest configuration and ensure all URLs are publicly accessible. If you encounter issues, check our comprehensive debugging guide for common problems and solutions. ## Understanding MiniKit Context ### What `useMiniKit` Gives You The `useMiniKit()` hook provides access to everything your Mini App needs to understand the Farcaster session: The Farcaster ID of the current user Whether the user has added your Mini App to their account Where the app was launched from (e.g., "cast", "launcher", "notification") Whether your app has called `setFrameReady()` and is ready to be shown Function to call when your app is fully loaded and ready for interaction You can use this context to personalize the experience, trigger different flows, or track user behavior. ## Available MiniKit Hooks MiniKit provides a comprehensive set of hooks designed to help you build rich, social experiences: Send in-app and push notifications to users who have added your frame Allow users to save your mini app to their Farcaster client for easy access Programmatically close the mini app frame when appropriate Open external URLs from within the frame context Configure and handle primary button interactions Navigate users to Farcaster profiles (their own or others) Handle Farcaster authentication and sign-in flows Learn about all available MiniKit hooks, their parameters, and usage examples ## Next Steps Now that your Mini App is integrated and deployed: Share your Mini App URL in Farcaster and test all functionality with real users. Use analytics to understand how users interact with your app and identify areas for improvement. Consider adding notifications, authentication, or other MiniKit hooks to enhance the user experience.