Codemods to help migrate from Farcaster Frames to MiniApps
npm install @farcaster/miniapp-codemodsThis package provides automated codemods to help migrate your codebase from Farcaster Frames to Mini Apps.
This tool might make mistakes. Make sure you are working from a clean, committed branch and have backed up your project.
``bash`
npm install -g @farcaster/miniapp-codemods
Or run directly with npx:
`bash`
npx @farcaster/miniapp-codemods
Run all codemods on your project:
`bash`
miniapp-migrate ./src
Preview changes without modifying files:
`bash`
miniapp-migrate ./src --dry-run
Run only a specific transformation:
`bash`
miniapp-migrate ./src --transform update-imports
- update-imports - Updates package imports from @farcaster/frame- to @farcaster/miniapp-update-api-methods
- - Updates API method names (e.g., frameHost → miniAppHost)update-types
- - Updates TypeScript type names (e.g., FrameContext → MiniAppContext)update-event-names
- - Updates event names (e.g., frame_added → miniapp_added)
`diff
- import { frameHost } from '@farcaster/frame-sdk'
+ import { miniAppHost } from '@farcaster/miniapp-sdk'
- import { FrameContext } from '@farcaster/frame-core'
+ import { MiniAppContext } from '@farcaster/miniapp-core'
`
`diff
- const context = await frameHost.getFrameContext()
+ const context = await miniAppHost.getMiniAppContext()
- frameHost.addFrame({ url: 'https://example.com' })
+ miniAppHost.addMiniApp({ url: 'https://example.com' })
`
`diff
- const context: FrameContext = { ... }
+ const context: MiniAppContext = { ... }
- export interface MyFrameHost extends FrameHost { ... }
+ export interface MyMiniAppHost extends MiniAppHost { ... }
`
`diff
- sdk.on('frame_added', handler)
+ sdk.on('miniapp_added', handler)
- if (event.type === 'frame_removed') { ... }
+ if (event.type === 'miniapp_removed') { ... }
`
The codemod will update farcaster.json files to include both frame and miniapp properties for backward compatibility:
`diff`
{
"accountAssociation": { ... },
"frame": {
"version": "1",
"name": "My App",
...
}
+ "miniapp": {
+ "version": "1",
+ "name": "My App",
+ ...
+ }
}
After running the codemods, you'll need to:
1. Update your package.json dependencies:
`json`
{
"dependencies": {
"@farcaster/miniapp-sdk": "^0.0.61",
"@farcaster/miniapp-wagmi-connector": "^0.0.5"
}
}
2. Update meta tags in your HTML (if using embeds):
`html`
3. Test your application thoroughly
The migration maintains backward compatibility:
- Old @farcaster/frame-* packages still work but show deprecation warningsframe
- Both and miniapp properties in manifests are supportedfc:frame
- The meta tag continues to work alongside fc:miniapp
Make sure your file extensions match the patterns:
- JavaScript/TypeScript files: .js, .jsx, .ts, .tsxfarcaster.json
- Manifest files: or .well-known/farcaster.json
The codemods use jscodeshift which preserves most formatting, but complex code might need manual adjustment. Always review the changes and run your tests.
Some edge cases might not be covered. Please report issues at:
https://github.com/farcasterxyz/miniapps/issues
`bash`
miniapp-migrate ./src --dry-runReview changes
miniapp-migrate ./src
`bash`
miniapp-migrate ./src --transform update-types
`bash``
miniapp-migrate ./src --verbose