Turn your Website/app into a mini app in Farcaster!

Note: It’s assumed you are familiar with what a mini app is.

There’s a webpage, any webpage, and it should now be shown as mini app within Farcaster clients like Warpcast? Then what you need to do is provide the information that it’s a mini app to the Farcaster client.

There are two steps involved

1. Provide the information that it is a mini app and information about the mini app
2. Return the webpage link that should be opened as mini app

The code samples will be Typescript, NextJS based but you can use any programming tooling to respond the same way to the GET and POST requests respectively.

Provide the metadata about the mini app

To show the mini app the Farcaster client must be able to GET request call the provided mini app url (e.g. yourwebsite.de).

What needs to be shown is part of the Farcaster Specification.

Here’s a Typescript sample serving the GET request to show the metadata.

res.status(200).json({
        "type": "composer",
        "name": "Create Poll",
        "icon": "checkbox", // supported list: https://docs.farcaster.xyz/reference/actions/spec#valid-icons
        "description": "Create a poll frame",
        "aboutUrl": "https://your-app-server.example.com/about",
        "imageUrl": "https://your-app-server.example.com/static/logo.png",
        "action": {
          "type": "post",
        }
    });

Return the webpage to be opened as mini app to the Farcaster client

To tell the client which weburl to load, we respond to the POST request with a 200 and the URL (you can add URL parameters and do much more).

res.status(200).json({
      type: 'form',
      title: 'dTech.vision',
      url: 'http://localhost:3000', // make sure this is your public URL e.g. http://localhost:3000 for local testing
    });

Note that this is authenticated! You get a signed frame message (signedmessagebytes) in the POST body, so you could login users like shown in the Frame auth tutorial.

Putting it all together

Now if you handle both the GET and POST, your webpage will be without any adjustment to yourwebsite.de shown as mini app.

The following code sample is from our starter repo on Github.

A full tutorial on building your Mini Apps / Composer Actions is available here and includes a video version!

import type { NextApiRequest, NextApiResponse } from "next";

export default function handler(
  req: NextApiRequest,
  res: NextApiResponse<ComposerActionFormResponse | ComposerActionMetadata>,
) {
  if (req.method === 'POST') {
    const data = req.body;
    console.log(data);

    res.status(200).json({
      type: 'form',
      title: 'dTech.vision',
      url: 'http://localhost:3000', // make sure this is your public URL e.g. http://localhost:3000 for local testing
    });
  } else if (req.method === 'GET') {
    res.status(200).json({
        "type": "composer",
        "name": "Create Poll",
        "icon": "checkbox", // supported list: https://docs.farcaster.xyz/reference/actions/spec#valid-icons
        "description": "Create a poll frame",
        "aboutUrl": "https://your-app-server.example.com/about",
        "imageUrl": "https://your-app-server.example.com/static/logo.png",
        "action": {
          "type": "post",
        }
    });
  } else {
    res.status(405).end(); // Method Not Allowed
  }
}