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)

Identify router (App Router vs Pages) and where providers live.
Keep the existing thirdweb provider and add OnchainKitProvider with miniKit.enabled; import OnchainKit CSS.
Add a small FrameReady component to call setFrameReady() after mount.
Create and sign farcaster.json, then redeploy.
Keep thirdweb wallet/onboarding UI; only use OnchainKit UI components that do not replace wallet UX.
Replace external links with useOpenUrl() or MiniKit actions.
Add gasless tx flow (thirdweb AA/paymaster or OnchainKit Transaction + Paymaster).
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