base-miniapp-developer

name	base-miniapp-developer
description	Build or migrate React/Next.js apps into Base/Coinbase Wallet Mini Apps using MiniKit + OnchainKit, while keeping thirdweb as the primary wallet/onboarding/payment integration; manage farcaster.json manifests, readiness, and gasless transactions.

Base Mini App Developer

Trigger

Use when the user needs to build, migrate, or troubleshoot Base Mini Apps, Coinbase Wallet Mini Apps, MiniKit, OnchainKit, Farcaster Mini Apps/Frames, or farcaster.json manifests; or when gasless Base transactions with Paymaster/Bundler are required.

Guardrails

• Keep thirdweb as the primary wallet/onboarding/payment layer unless the user requests otherwise.
• No email/password auth. Wallet connection is the session.
• Do not use window.ethereum or window.location/window.open.
• MiniKit/OnchainKit hooks must be in client components ('use client').
• Manifest must be reachable at https://<domain>/.well-known/farcaster.json over HTTPS.
• Call setFrameReady() once the UI is ready.

Default conversion workflow (React/Next.js)

1. Identify router (App Router vs Pages) and where providers live.
2. Keep the existing thirdweb provider and add OnchainKitProvider with miniKit.enabled; import OnchainKit CSS.
3. Add a small FrameReady component to call setFrameReady() after mount.
4. Create and sign farcaster.json, then redeploy.
5. Keep thirdweb wallet/onboarding UI; only use OnchainKit UI components that do not replace wallet UX.
6. Replace external links with useOpenUrl() or MiniKit actions.
7. Add gasless tx flow (thirdweb AA/paymaster or OnchainKit Transaction + Paymaster).
8. Validate in Base Build Preview and test on device.

Provider guidance

• Preferred Mini App context: OnchainKitProvider (@coinbase/onchainkit) with miniKit={{ enabled: true }}.
• Keep the thirdweb provider intact; make sure its connectors do not rely on injected window.ethereum.
• If the app already uses @coinbase/minikit-react, keep it unless asked to migrate.

Thirdweb-first guidance

• Use thirdweb for onboarding and payments; do not replace with OnchainKit Wallet/Identity components unless requested.
• Prefer thirdweb connectors that work in a WebView (no injected provider assumption).
• Keep thirdweb chain config set to Base and reuse existing contract hooks/components.

When the user says "convert this app"

• Install deps: @coinbase/onchainkit, viem, plus @coinbase/minikit-react only if needed.
• Keep existing thirdweb setup (providers, hooks, UI).
• Add manifest and placeholder assets; remind user to update domain and re-sign.
• Wire providers and readiness.
• Audit for window.ethereum/window.location usage and replace.

References

• Manifest schema + signing: references/manifest.md
• Providers + readiness: references/provider.md
• MiniKit context & safety: references/minikit.md
• Navigation & social actions: references/navigation.md
• OnchainKit UI components: references/onchainkit-components.md
• Paymaster & gasless tx: references/paymaster.md
• thirdweb integration notes: references/thirdweb.md