> ## Documentation Index
> Fetch the complete documentation index at: https://docs.monad.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# How to build a Farcaster Mini App

In this guide, you will learn how to use the [Monad Farcaster Mini App Template](https://github.com/monad-developers/monad-miniapp-template) to build apps.

The template demonstrates all Mini App capabilities and lets you easily modify it, so you can build Mini Apps.

## Cloning the Template

You can the following command to clone the Mini App template to your local machine:

```bash theme={null}
git clone https://github.com/monad-developers/monad-miniapp-template.git
```

### Install the dependencies

```bash theme={null}
yarn
```

### Copy `.env.example` over to `.env.local`

```bash theme={null}
cp .env.example .env.local
```

### Run the template

```bash theme={null}
yarn run dev
```

### View the App in Farcaster Embed tool

Farcaster has a neat [Embed tool](https://farcaster.xyz/~/developers/mini-apps/embed) that you can use to inspect the Mini App before you publish it.

Unfortunately, the embed tool can only work with remote URL. Inputting a localhost URL does not work.

As a workaround, you may make the local app accessible remotely using a tool like `cloudflared` or `ngrok`. In this guide we will use `cloudflared`.

#### Install Cloudflared

```bash theme={null}
brew install cloudflared
```

For more installation options see the [official docs](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/).

#### Expose localhost

Run the following command in your terminal:

```bash theme={null}
cloudflared tunnel --url http://localhost:3000
```

Be sure to specify the correct port for your local server.

#### Set `NEXT_PUBLIC_URL` environment variable in `.env.local` file

```bash theme={null}
NEXT_PUBLIC_URL=<url-from-cloudflared-or-ngrok>
```

#### Use the provided url

`cloudflared` will generate a random subdomain and print it in the terminal for you to use. Any traffic to this URL will get sent to your local server.

Enter the provided URL in the [Farcaster Embed tool](https://farcaster.xyz/~/developers/mini-apps/embed).

<img src="https://mintcdn.com/monadfoundation-40611fb6/c3ZcPFY7YVeS_v57/static/img/guides/farcaster-miniapp/1.png?fit=max&auto=format&n=c3ZcPFY7YVeS_v57&q=85&s=146bfd708a1d135908b1a0a140624091" alt="embed-tool" width="3024" height="1964" data-path="static/img/guides/farcaster-miniapp/1.png" />

Let's investigate the various components of the template.

## Customizing the Mini App Embed

Mini App Embed is how the Mini App shows up in the feed or in a chat conversation when the URL of the app is shared.

The Mini App Embed looks like this:

<img src="https://mintcdn.com/monadfoundation-40611fb6/c3ZcPFY7YVeS_v57/static/img/guides/farcaster-miniapp/2.png?fit=max&auto=format&n=c3ZcPFY7YVeS_v57&q=85&s=2bf8e35feb0b1c620e26274b29b255a2" alt="embed-preview" width="3024" height="1964" data-path="static/img/guides/farcaster-miniapp/2.png" />

You can customize this by editing the file `app/page.tsx`:

```js lines title="app/page.tsx" theme={null}
...

const appUrl = env.NEXT_PUBLIC_URL;

const frame = {
  version: "next",
  imageUrl: `${appUrl}/images/feed.png`, // Embed image URL (3:2 image ratio)
  button: {
    title: "Template", // Text on the embed button
    action: {
      type: "launch_frame",
      name: "Monad Farcaster Mini App Template",
      url: appUrl, // URL that is opened when the embed button is tapped or clicked.
      splashImageUrl: `${appUrl}/images/splash.png`,
      splashBackgroundColor: "#f7f7f7",
    },
  },
};

...
```

You can either edit the URLs for the images or replace the images in `public/images` folder in the template.

Once you are happy with the changes, click `Refetch` in the Embed tool to get the latest configuration.

<Note>
  If you are developing locally, ensure that your Next.js app is running locally and the cloudflare tunnel is open.
</Note>

## Customizing the Splash Screen

Upon opening the Mini App, the first thing the user will see is the Splash screen:

<img src="https://mintcdn.com/monadfoundation-40611fb6/c3ZcPFY7YVeS_v57/static/img/guides/farcaster-miniapp/3.png?fit=max&auto=format&n=c3ZcPFY7YVeS_v57&q=85&s=03d6c982690b1a4f48ca6c2d74bb766c" alt="splash-screen" width="2260" height="1464" data-path="static/img/guides/farcaster-miniapp/3.png" />

You can edit the `app/page.tsx` file to customize the Splash screen.

```js lines title="app/page.tsx" theme={null}
...

const appUrl = env.NEXT_PUBLIC_URL;

const frame = {
  version: "next",
  imageUrl: `${appUrl}/images/feed.png`,
  button: {
    title: "Launch Template",
    action: {
      type: "launch_frame",
      name: "Monad Farcaster Mini App Template",
      url: appUrl,
      splashImageUrl: `${appUrl}/images/splash.png`, // App icon in the splash screen (200px * 200px)
      splashBackgroundColor: "#f7f7f7", // Splash screen background color
    },
  },
};

...
```

For `splashImageUrl`, you can either change the URL or replace the image in `public/images` folder in the template.

## Modifying the Mini App

Upon opening the template Mini App, you should see a screen like this:

<img src="https://mintcdn.com/monadfoundation-40611fb6/c3ZcPFY7YVeS_v57/static/img/guides/farcaster-miniapp/4.png?fit=max&auto=format&n=c3ZcPFY7YVeS_v57&q=85&s=03ac39fbe78420bbe9bfa3dec532df3c" alt="miniapp" width="3024" height="1964" data-path="static/img/guides/farcaster-miniapp/4.png" />

The code for this screen is in the `components/pages/app.tsx` file:

```tsx lines title="components/pages/app.tsx" theme={null}
export default function Home() {
  const { context } = useMiniAppContext();
  return (
    // SafeAreaContainer component makes sure that the app margins are rendered properly depending on which client is being used.
    <SafeAreaContainer insets={context?.client.safeAreaInsets}>
      {/* You replace the Demo component with your home component */}
      <Demo />
    </SafeAreaContainer>
  )
}
```

You can remove or edit the code in this file to build your Mini App.

### Accessing User Context

<img src="https://mintcdn.com/monadfoundation-40611fb6/c3ZcPFY7YVeS_v57/static/img/guides/farcaster-miniapp/5.png?fit=max&auto=format&n=c3ZcPFY7YVeS_v57&q=85&s=c05e8854fddb6ecbb121a2b939a942a1" alt="user-context" width="2260" height="1464" data-path="static/img/guides/farcaster-miniapp/5.png" />

Your Mini App receives various information about the user, including `username`, `fid`, `displayName`, `pfpUrl` and other fields.

The template provides a helpful hook `useMiniAppContext` that you can use to access these fields:

```js lines title="components/Home/User.tsx" theme={null}
export function User() {
    const { context } = useMiniAppContext();
    return <p>{context.user.username}</p>
}
```

The template also provide an example of the same in `components/Home/User.tsx` file.

You can learn more about Context [here](https://miniapps.farcaster.xyz/docs/sdk/context).

### Performing App Actions

<img src="https://mintlify.s3.us-west-1.amazonaws.com/monadfoundation-40611fb6/static/img/guides/farcaster-miniapp/composeCast.gif" style={{ marginBottom: 10, marginLeft: "auto", marginRight: "auto" }} />

Mini Apps have the capability to perform native actions that enhance the user experience!

Actions like:

* `addFrame`: Allows the user to save (bookmark) the app in a dedicated section
* `composeCast`: Allows the Mini App to prompt the user to cast with prefilled text and media
* `viewProfile`: Presents a profile of a Farcaster user in a client native UI

Learn more about Mini App actions [here](https://miniapps.farcaster.xyz/docs/sdk/actions/add-frame)

The template provides an easy way to access the actions via the `useMiniAppContext` hook!

```js title="components/Home/FarcasterActions.tsx" theme={null}
const { actions } = useMiniAppContext();
```

An example for the same can be found in `components/Home/FarcasterActions.tsx` file.

### Prompting Wallet Actions

<img src="https://mintcdn.com/monadfoundation-40611fb6/c3ZcPFY7YVeS_v57/static/img/guides/farcaster-miniapp/6.png?fit=max&auto=format&n=c3ZcPFY7YVeS_v57&q=85&s=d57454e67fec88353104579145075726" alt="wallet-actions" width="2260" height="1464" data-path="static/img/guides/farcaster-miniapp/6.png" />

Every user of Farcaster has a Farcaster wallet with Monad Testnet support.

**Mini Apps can prompt the user to perform onchain actions**!

The template provides an example for the same in `components/Home/WalletActions.tsx` file.

```js lines title="components/Home/WalletActions.tsx" theme={null}
export function WalletActions() {
    ...

    async function sendTransactionHandler() {
        sendTransaction({
            to: "0x7f748f154B6D180D35fA12460C7E4C631e28A9d7",
            value: parseEther("1"),
        });
    }

    ...
}
```

<Warning>
  The Farcaster wallet supports multiple networks. It is recommended that you ensure that the right network is connected before prompting wallet actions.

  You can use viem's `switchChain` or equivalent to prompt a chain switch.

  ```js title="components/Home/WalletActions.tsx" theme={null}
  // Switching to Monad Testnet
  switchChain({ chainId: 10143 });
  ```

  The template has an example for the same in the `components/Home/WalletActions.tsx` file.
</Warning>

## Conclusion

In this guide, you explored Farcaster Mini Apps — the simplest way to create engaging, high-retention, and easily monetizable applications!

You also discovered the key capabilities of Mini Apps and how you can use the [Monad Farcaster Mini App Template](https://github.com/monad-developers/monad-miniapp-template) to build your own.

For more details, check out the official Mini App documentation [here](https://miniapps.farcaster.xyz/).

### Explore more Farcaster Mini App guides

<CardGroup cols={2}>
  <Card title="Sending Notifications" href="/templates/farcaster-miniapp/sending-notifications" />

  <Card title="Generating custom shareable images" href="/templates/farcaster-miniapp/generating-custom-og-images" />

  <Card title="Publishing Mini App" href="/templates/farcaster-miniapp/publishing-miniapp" />
</CardGroup>