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