Farcaster Frames to Mini Apps Migration Codemods

This package provides automated codemods to help migrate your codebase from Farcaster Frames to Mini Apps.

Warnings

This tool might make mistakes. Make sure you are working from a clean, committed branch and have backed up your project.

Installation

``bash
npm install -g @farcaster/miniapp-codemods
`

Or run directly with npx:

`bash
npx @farcaster/miniapp-codemods
`

Usage

$3

Run all codemods on your project:

`bash
miniapp-migrate ./src
`

$3

Preview changes without modifying files:

`bash
miniapp-migrate ./src --dry-run
`

$3

Run only a specific transformation:

`bash
miniapp-migrate ./src --transform update-imports
`

$3

- 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)

What gets migrated

$3

`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'
`

$3

`diff
- const context = await frameHost.getFrameContext()
+ const context = await miniAppHost.getMiniAppContext()

- frameHost.addFrame({ url: 'https://example.com' })
+ miniAppHost.addMiniApp({ url: 'https://example.com' })
`

$3

`diff
- const context: FrameContext = { ... }
+ const context: MiniAppContext = { ... }

- export interface MyFrameHost extends FrameHost { ... }
+ export interface MyMiniAppHost extends MiniAppHost { ... }
`

$3

`diff
- sdk.on('frame_added', handler)
+ sdk.on('miniapp_added', handler)

- if (event.type === 'frame_removed') { ... }
+ if (event.type === 'miniapp_removed') { ... }
`

$3

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",
+ ...
+ }
}
`

Manual steps after migration

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

Backward compatibility

The migration maintains backward compatibility:
- Old @farcaster/frame-* packages still work but show deprecation warnings
- Both frame and miniapp properties in manifests are supported
- The fc:frame meta tag continues to work alongside fc:miniapp

Troubleshooting

$3

Make sure your file extensions match the patterns:
- JavaScript/TypeScript files: .js, .jsx, .ts, .tsx
- Manifest files: farcaster.json or .well-known/farcaster.json

$3

The codemods use jscodeshift which preserves most formatting, but complex code might need manual adjustment. Always review the changes and run your tests.

$3

Some edge cases might not be covered. Please report issues at:
https://github.com/farcasterxyz/miniapps/issues

Examples

$3

`bash
miniapp-migrate ./src --dry-run


Review changes


miniapp-migrate ./src
`

$3

`bash
miniapp-migrate ./src --transform update-types
`

$3

`bash
miniapp-migrate ./src --verbose
``