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:

npm install @farcaster/frame-sdk

Then call the ready function when your interface is loaded and ready to be displayed:

import { sdk } from '@farcaster/frame-sdk';
 
await sdk.actions.ready();

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:

import { useEffect, useState } from "react";
import { sdk } from '@farcaster/frame-sdk';

export default function Home() {
  const [isLoaded, setIsLoaded] = useState(false);

  useEffect(() => {
    const load = async () => {
      await sdk.actions.ready();
      setIsLoaded(true);
    };
    if (sdk && !isLoaded) {
      load();
    }
  }, [isLoaded]);

  return (...)
}

​
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:

import { http, createConfig } from 'wagmi';
import { base } from 'wagmi/chains';
import { farcasterFrame as miniAppConnector } from '@farcaster/frame-wagmi-connector';
 
export const wagmiConfig = createConfig({
  chains: [base],
  transports: {
    [base.id]: http(),
  },
  connectors: [
    miniAppConnector()
    // add other wallet connectors like metamask or coinbase wallet if desired
  ]
});

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:

{
  "frame": {
    "version": "1",
    "name": "Yoink!",
    "iconUrl": "https://yoink.party/logo.png",
    "homeUrl": "https://yoink.party/framesV2/",
    "imageUrl": "https://yoink.party/framesV2/opengraph-image",
    "buttonTitle": "🚩 Start",
    "splashImageUrl": "https://yoink.party/logo.png",
    "splashBackgroundColor": "#f5f0ec",
    "webhookUrl": "https://yoink.party/api/webhook"
  }
}

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:

public/
├── .well-known/
    └── farcaster.json

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:
{
  "accountAssociation": {
    "header": "eyJmaWQiOjM2MjEsInR5cGUiOiJjdXN0b2R5Iiwia2V5IjoiMHgyY2Q4NWEwOTMyNjFmNTkyNzA4MDRBNkVBNjk3Q2VBNENlQkVjYWZFIn0",
    "payload": "eyJkb21haW4iOiJ5b2luay5wYXJ0eSJ9",
    "signature": "MHgwZmJiYWIwODg3YTU2MDFiNDU3MzVkOTQ5MDRjM2Y1NGUxMzVhZTQxOGEzMWQ5ODNhODAzZmZlYWNlZWMyZDYzNWY4ZTFjYWU4M2NhNTAwOTMzM2FmMTc1NDlmMDY2YTVlOWUwNTljNmZiNDUxMzg0Njk1NzBhODNiNjcyZWJjZTFi"
  },
  "frame": {
    "version": "1",
    "name": "Yoink!",
    "iconUrl": "https://yoink.party/logo.png",
    "homeUrl": "https://yoink.party/framesV2/",
    "imageUrl": "https://yoink.party/framesV2/opengraph-image",
    "buttonTitle": "🚩 Start",
    "splashImageUrl": "https://yoink.party/logo.png",
    "splashBackgroundColor": "#f5f0ec",
    "webhookUrl": "https://yoink.party/api/webhook"
  }
}

​
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.

<meta name="fc:frame" content="<stringified Embed JSON>" />

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:

{
  "version": "next",
  "imageUrl": "https://yoink.party/framesV2/opengraph-image",
  "button": {
    "title": "🚩 Start",
    "action": {
      "type": "launch_frame",
      "name": "Yoink!",
      "url": "https://yoink.party/framesV2",
      "splashImageUrl": "https://yoink.party/logo.png",
      "splashBackgroundColor": "#f5f0ec"
    }
  }
}