Convert a Web App to a Farcaster Mini App
Update any JavaScript web app to be a Farcaster mini app
If looking to create a new mini app from scratch, see here.
Converting an existing JavaScript-based web app to a Farcaster mini app involves the following steps:
- install the Mini App SDK and call
sdk.actions.ready()
- integrate with the SDK’s ethereum provider exposed via
sdk.wallet.ethProvider
- add a
farcaster.json
file with mini app metadata and a signature proving ownership - add a custom HTML
<meta />
tag specifying how embeds should be rendered
Installing the SDK
The Mini App SDK (formerly the Frame SDK) can be added to your project with:
Then call the ready function when your interface is loaded and ready to be displayed:
You should call ready()
as early as possible in the app, but after any pageload processes that might cause the UI to re-render or update significantly. In a React app, it’s generally best to call ready()
inside the page-level component at the root of your UI, e.g. in your homepage component.
Here’s an example of how you might do this in a standard React app:
Connecting to the wallet provider
It’s recommended to use wagmi
for your wallet provider, as the Farcaster team provides the @farcaster/frame-wagmi-connector package for easy configuration.
Run npm i @farcaster/frame-wagmi-connector
to install, and then connecting is as simple as adding the connector to the wagmi config:
With the above configuration, you can access the mini app user’s connected wallet with normal wagmi hooks like useAccount()
.
Adding and signing the farcaster.json file
Mini apps are expected to serve a farcaster.json file, also known as a “manifest”, at /.well-known/farcaster.json
, published at the root of the mini app’s domain.
The manifest consists of a frame
section containing metadata specific to the mini app and an accountAssociation
section consisting of a JSON Farcaster Signature (JFS) to verify ownership of the domain and mini app.
The frame
metadata object only has four required fields (version
, name
, homeUrl
, and iconUrl
), but providing more is generally better to help users and clients discover your mini app. See the full list of options here in the Farcaster docs.
Start by publishing just the frame portion of the manifest:
In a standard react app, you can do this by placing a JSON file in your public folder, to be served as a static file:
Once your domain is live and serving something like the above example at yourURL.com/.well-known/farcaster.json
, you need to generate an accountAssociation
signed with your farcaster custody address:
- go to the manifest tool on Farcaster in your desktop browser
- enter your domain and scroll to the bottom
- click “Claim Ownership”, and follow the steps to sign the manifest with your Farcaster custody address using your phone
- finally, copy the output manifest from the manifest tool and update your domain to serve the full, signed farcaster.json file, which should look something like this:
Configuring embed metadata
To allow your mini app to render properly in social feeds, you must add a meta tag with the name “fc:frame” to the <head>
section of the HTML page serving your mini app.
The full schema can be found here in the Farcaster docs, but the most common button action is launch_frame
, so unless you have a specific use case, you can safely copy the following example: