# 🟩 How to Build your first Base Mini App **Published by:** [deca12x](https://paragraph.com/@deca12x/) **Published on:** 2025-09-09 **URL:** https://paragraph.com/@deca12x/first-miniapp ## Content Why?By: Deca Date: 9th September 2025 The past two weekends I built two Base Mini Apps at the Aleph Hack (Aug 29-31, 2025) and ETHWarsaw (Sep 5-7, 2025) respectively. Upon Evan and Clemens’ request, I made this mini report, which distills the actual developer experience into a clear setup flow with caveats, tips, and dev tools. Shoutout to 🍋Limone , Caso and Bianc8 who gave me advice along the way. Follow these three steps in order to build and test your Mini App effectively. 📚 Step 1: Choose your SDKs wiselyYou’ll only need two libraries:One for Mini App logicOne for wallet connection Use one of these combos:farcaster/miniapp-sdk + coinbase/wallet-sdk ← works best right nowcoinbase/onchainkit + coinbase/wallet-sdkđŸš« Avoid farcaster/frame-sdk - it’s deprecated and will cause issues. đŸš«Don’t use BOTH farcaster/miniapp-sdk AND coinbase/onchainkit - pick one of the two. Once you've picked, move on to Step 2: manifest setup. Docs:https://miniapps.farcaster.xyz/docs/getting-started OR https://docs.base.org/onchainkit/getting-startedhttps://docs.cdp.coinbase.com/coinbase-wallet/coinbase-wallet-sdk/install đŸ§Ÿ Step 2: Fill out the Farcaster ManifestUse the official manifest builder: https://farcaster.xyz/~/developers/mini-apps/manifest?domain=yourdomain.com Hint 1: You’ll need to generate and include five images at exact dimensions:icon.png: 512×512 pxsplash.png: 400×400 pxhero.png: 1200×630 pxscreenshot1.png: 1200×800 pxscreenshot2.png: 1200×800 pxIf using Next.js, place them in your /public folder. You can use Canva to easily create documents of the correct size. Hint 2: To generate your manifest, do not do it via the CLI! npx create-onchain --manifest Instead, to get your farcaster header, payload and signature, do it directly from the Farcaster app on your phone:Open settingsOpen advanced tab > enable developer modeOn developer tools > domains, enter your domain and generate manifestCopy and paste the values of header, payload, and signature you have in the clipboard in the related env variables ✅ Once all fields are green in the manifest tool, you're ready to build out your Mini App’s functionality. đŸ§Ș Step 3: Testing and Debugging - What Works and What Doesn’tBy default, simply opening your app at localhost:3000 and using browser devtools is not sufficient to test Farcaster-specific behavior. Here’s why:The SDK provides a context object (sdk.context) populated only when the Mini App is rendered within a Farcaster client - like Base App, Farcaster App, or the Farcaster manifest preview tool.You can test your own user context this way (e.g. sdk.context.user) via the preview site.But if your logic depends on other context, like the author of the cast (sdk.context.location.cast.author), the preview tool won’t work - it doesn’t simulate the full cast environment. This means that to test all context fields fully, you must push your app to production, post a cast linking to it, and open it from Base App. But:Pushing to prod takes time - typically 1-5 minutes per change (depends on host like Vercel, your git branches setup, whether you test the build locally, etc.)You can’t access browser logs from Base App - debugging becomes hard. 🧰 Two Workable Debugging SolutionsOption 1: Use a tunneling service (e.g. ngrok)Lets you test locally using a public URLWorks with the Farcaster manifest preview sitePreserves full access to browser logs (e.g. console.log) Setup:Terminal 1: npm run devTerminal 2: npm run ngrok (set up a script for this in your package.json file)Paste the generated URL (e.g. random-id.ngrok.io) into the manifest preview tool (without https://) Pros:Fast feedback loopEasy access to logsCons:Can't access full cast context (e.g. sdk.context.location.cast.author)You might run into extra issues if your app’s logic changes based on domain (e.g. different auth providers per subdomain)Tunnels may need to be reset often...Clear cookies, browser cache, and app stateRestart both servers (npm run dev AND npm run ngrok) 🔎 This setup is useful when you're building more complex flows. Option 2: Use an in-app DebugPanel componentThis is what I used:Create a component that logs and displays relevant data visually inside the Mini App if (debugMode) { return ; }Serve the app at yourdomain.com/?debug=truePost a cast containing this URLOpen the cast in Base App → DebugPanel is visibleCopy-paste DebugPanel logs from your phone to your laptop (possibly feed them to an LLM) Real example I built with DebugPanel: 🔗 https://base.app/post/0x23f1a925729e1f3a2ae58b2385b8e72764925121 Pros:Full access to all real context fields (sdk.context.location.cast.author, etc.)No compromise - this is your final deployed Mini AppCons:Slow feedback loop (prod push every change)You must manually transfer logs to your dev machine If this was useful, please Recast this guide! ✌Deca ## Publication Information - [deca12x](https://paragraph.com/@deca12x/): Publication homepage - [All Posts](https://paragraph.com/@deca12x/): More posts from this publication - [RSS Feed](https://api.paragraph.com/blogs/rss/@deca12x): Subscribe to updates - [Twitter](https://twitter.com/deca12x): Follow on Twitter