Turn your Website/app into a Mini App on Farcaster!

We assume you are familiar with what a Farcaster Mini App is. Additionally nothing more then minimal frontend development experience is assumed, we’ll go through each individual step.

Make the website render large with custom preview and action buttons

We can have our website render as a Farcaster Mini App, so it shows up with our own big preview image and call to action button. The button will open a webpage in app, so we can use this either to show the URL shared or use it as call to action for marketing or lead generation.

A pure HTML simplest Mini App Github Repo to see it all tied together is available here.

To achieve our website being embedded into Farcaster client’s like Warpcast nicely follow these steps

1. Provide the metadata about the app/website in the HTML metadata:

   The Mini App metadata is typed in JSON which we will fill in with our information. Please ensure the following properties about your metadata

   • imageUrl image is 3:2 format less than 10mb in size
   • the title as well as name are less than 32 characters
   • the splashImageUrl must be 200x200px and less than 1MB

   The full type specification can be found in the Mini App specification

   The metadata JSON looks as follows:

   {
     "version": "next",
     "imageUrl": "https://dtech.vision/frame-thumbnail.png",
     "button": {
       "title": "Learn Farcaster",
       "action": {
         "type": "launch_frame",
         "name": "dTech - Farcaster Boutique",
         "url": "https://dtech.vision/farcaster/",
         "splashImageUrl": "https://dtech.vision/icon.png",
         "splashBackgroundColor": "#f7f7f7"
       }
     }
   }

   The valid JSON is added to the HTML head section ( in Javascript/Typescript you may define it as a variable and then use JSON.stringify ).

   <meta
     property="fc:frame"
     content="<Insert metadata JSON here. Ensure it's valid JSON!>"
   />

2. Add a .well-known/farcaster.json file to your website

   To generate the accountAssociation we will use the Warpcast mobile app (though if you have a valid signer you could also do this on your own)

   NOTE: Make sure you’re in the mobile app!

   In Warpcast navigate to Settings > Developer > Domains where you can type in your domain e.g. dtech.vision to generate the domain manifest. If you don’t see the Developer menu, you may need to scroll down or go to Settings > Advanced > scroll down and enable Developer mode.

   Clicking generate domain manifest will give use the accountAssociation section and potentially a sample mini app section we can paste and adjust to our needs. One such sample is as follows:

   {
     "accountAssociation": {
       "header": "",
       "payload": "",
       "signature": ""
     },
     "frame": {
       "name": "dTech - Farcaster docs",
       "version": "0.0.1",
       "iconUrl": "https://dtech.vision/icon.png",
       "homeUrl": "https://dtech.vision/farcaster",
       "splashImageUrl": "https://dtech.vision/icon.png",
       "splashBackgroundColor": "#f7f7f7",
       "webhookUrl": "https://dtech.vision/webhookurl"
     }
   }

3. Call the mini app SDK’s ready() function to hide the loading screen

   The mini app SDK will show a loading screen until the mini app is ready to be displayed. To hide this loading screen, call the ready() function. To get there we need to use the Farcaster Mini App SDK. If we have a Typescript (or JS) project we can install and import the SDK. In case we don’t, we can embed the script directly:

   <script src="https://cdn.jsdelivr.net/npm/@farcaster/frame-sdk/dist/index.min.js"></script>
   <script>
     frame.sdk.actions.ready();
   </script>

   now that ready is called, the loading screen will be hidden and your webpage accessible via Farcaster Mini App - your done!

   For users of Typescript (or JS) we install the mini app sdk

   bun
   bun add @farcaster/frame-sdk
   npm
   npm install @farcaster/frame-sdk
   pnpm
   pnpm install @farcaster/frame-sdk
   yarn
   yarn add @farcaster/frame-sdk

   now on our page we call the ready function. The following is a simplified visualisation of a Hello World page, adapt this to your application.

   import sdk from "@farcaster/frame-sdk";
   
   export function Home() {
     sdk.actions.ready();
   
     return <div>Hello from dTech!</div>;
   }

   Try loading your website as Mini App in the developer playground after deploying it.

   A more robust useEffect based setup that most React developers will be familiar with is as follows for you Index page:

   import type { Context } from '@farcaster/frame-core';
   
   export default function Index() {
     const [isSDKLoaded, setIsSDKLoaded] = useState(false);
     const [context, setContext] = useState<Context.FrameContext>();
   
     // Farcaster Mini App Integration (see https://dtech.vision/farcaster/)
     useEffect(() => {
       const load = async () => {
         setContext(await sdk.context);
         sdk.actions.ready();
       };
       if (sdk && !isSDKLoaded) {
         setIsSDKLoaded(true);
         load();
       }
     }, [isSDKLoaded]);
     // end Farcaster Mini App Integration
   
     return <div>Hello from dTech!</div>;
   }

   In the above sample we’re using the Mini App context and setting it too! It’s powerful data tracking where the Mini App was opened from and which user opened it, what post they saw or if they clicked on a notification and more.

Hinweis

Putting it all together you can have a pure HTML Farcaster Mini App! They are websites after all! How cool is that!? The following Github is the simplest Mini App you can build and since it’s HTML AI can help you customize it easily!

Did you know you can also take that HTML and throw it into a code widget? you maybe able to turn your web2 stack into a mini app with it!

A pure HTML simplest Mini App Github Repo