mcpField
C
converting-minikit-to-farcaster

converting-minikit-to-farcaster

github.com/baseDevelopment120317 installsUpdated 1d ago
Repository

About converting-minikit-to-farcaster

A migration reference for developers moving applications from MiniKit to Farcaster SDK. It maps hooks to SDK actions and covers version changes, async context access, and common migration errors.

Key features

  1. 01MiniKit hook to SDK action mapping
  2. 02SDK v0.2.0+ change notes
  3. 03Async context access examples
  4. 04Migration and dependency update steps
  5. 05Common error troubleshooting

Use cases

  1. 01Move a MiniKit app to Farcaster SDK
  2. 02Adjust context access after an SDK update
  3. 03Troubleshoot migration type or component errors

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/base/skills --skill converting-minikit-to-farcaster

After installing, type/converting-minikit-to-farcasterin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

AUTH.md
DEPENDENCIES.md
EXAMPLES.md
LICENSE
MANIFEST.md
MAPPING.md
PITFALLS.md
PROVIDER.md
README.md
analyze_project.py
validate_conversion.py

Details

From the project README

MiniKit to Farcaster SDK

Breaking Changes (SDK v0.2.0+)

  1. sdk.context is a Promise — must await
  2. sdk.isInMiniApp() accepts no parameters
  3. sdk.actions.setPrimaryButton() has no onClick callback

Check version: npm list @farcaster/miniapp-sdk

Quick Reference

MiniKitFarcaster SDKNotes
useMiniKit().setFrameReady()await sdk.actions.ready()
useMiniKit().contextawait sdk.contextAsync
useMiniKit().isSDKLoadedawait sdk.isInMiniApp()No params
useClose()await sdk.actions.close()
useOpenUrl(url)await sdk.actions.openUrl(url)
useViewProfile(fid)await sdk.actions.viewProfile({ fid })
useViewCast(hash)await sdk.actions.viewCast({ hash })
useComposeCast()await sdk.actions.composeCast({ text, embeds })
useAddFrame()await sdk.actions.addMiniApp()
usePrimaryButton(opts, cb)await sdk.actions.setPrimaryButton(opts)No callback
useAuthenticate()sdk.quickAuth.getToken()See AUTH.md

Context Access Pattern

// WRONG
const fid = sdk.context?.user?.fid;

// CORRECT
const context = await sdk.context;
const fid = context?.user?.fid;

In React components, use state:

const [context, setContext] = useState(null);

useEffect(() => {
  const load = async () => {
    const ctx = await sdk.context;
    setContext(ctx);
  };
  load();
}, []);

Conversion Workflow

  1. Verify Node.js >= 22.11.0
  2. Update dependencies — see DEPENDENCIES.md
  3. Replace imports: @coinbase/onchainkit/minikit → @farcaster/miniapp-sdk
  4. Convert hooks using reference above
  5. Add FrameProvider — see PROVIDER.md
  6. Update manifest: frame → miniapp — see MANIFEST.md

Common Errors

"Property 'user' does not exist on type 'Promise'" → Await sdk.context before accessing properties

"Expected 0 arguments, but got 1" → Remove parameters from sdk.isInMiniApp()

Context is null in components → Ensure FrameProvider is in your provider chain

References

Comments

Markdown supported