Publishing your app

Publishing Mini Apps involves providing information like who developed the app, how it should be displayed, and what its capabilities are.

Since Farcaster is a decentralized network with multiple clients, publishing is done by hosting a manifest file at /.well-known/farcaster.json on the domain your app is hosted on rather than submitting information directly to a single entity.

discover mini apps

Published Mini Apps can be discovered in App Stores.

Steps

Choose a domain

A Mini App is associated with a single domain (i.e. rewards.warpcast.com). This domain serves as the identifier for your app and can't be changed later so you should choose a stable domain.

There's no limit on the number of apps you can create. You can create a separate domain specifically for development purposes if needed.

Host a manifest file

Host a manifest file on your chosen domain at /.well-known/farcaster.json.

For now we'll create an empty file:

touch public/.well-known/farcaster.json

Define your application configuration

A Mini App has metadata that is used by Farcaster clients to host your app. This data is specified in the frame property of the manifest and has the following properties:

Property	Type	Required	Description	Constraints
version	string	Yes	Manifest version.	Must be '1'.
name	string	Yes	Mini App name.	Max length 32 characters
homeUrl	string	Yes	Default launch URL	Max length 1024 characters.
iconUrl	string	Yes	Icon image URL	Max length 1024 characters. Image must be 1024x1024px PNG, no alpha.
imageUrl	string	No	[DEPRECATED] Default image to show if shared in a feed.	Max length 1024 characters. Image must be 3:2 aspect ratio.
buttonTitle	string	No	[DEPRECATED] Default button title to show if shared in a feed.	Max length 32 characters.
splashImageUrl	string	No	URL of image to show on loading screen.	Max length 32 characters. Must be 200x200px.
splashBackgroundColor	string	No	Hex color code to use on loading screen.	Hex color code.
webhookUrl	string	No	URL to which clients will POST events.	Max length 1024 characters. Must be set if the Mini App application uses notifications.
subtitle	string	No	Short description under app name	Max 30 characters, no emojis or special characters
description	string	No	Promotional message for Mini App Page	Max 170 characters, no emojis or special characters
screenshotUrls	array	No	Visual previews of the app	Portrait, 1284 x 2778, max 3 screenshots
primaryCategory	string	No	Primary category of app	One of: `games`, `social`, `finance`, `utility`, `productivity`, `health-fitness`, `news-media`, `music`, `shopping`, `education`, `developer-tools`, `entertainment`, `art-creativity`
tags	array	No	Descriptive tags for filtering/search	Up to 5 tags, max 20 characters each. Lowercase, no spaces, no special characters, no emojis.
heroImageUrl	string	No	Promotional display image	1200 x 630px (1.91:1)
tagline	string	No	Marketing tagline	Max 30 characters
ogTitle	string	No	Open Graph title	Max 30 characters
ogDescription	string	No	Open Graph description	Max 100 characters
ogImageUrl	string	No	Open Graph promotional image	1200 x 630px (1.91:1) PNG
noindex	boolean	No	Whether to exclude the Mini App from search results	true - to exclude from search results, false - to include in search results (default)

Here's an example farcaster.json file:

{
  "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",
  }
}

Hybrid & SSR-friendly detection

Some apps serve both as a Farcaster Mini App and a website from the same domain. When you want to fetch specific resources during server-side rendering (SSR) or conditionally lazy-load the SDK on the client, add a lightweight flag that only Mini-App launch URLs include

Two suggested patterns

Pattern	How it looks	Why use it
Dedicated path	`/your/path/.../miniapp`	Easiest to match on the server
Well-known query param	`https://example.com/page?miniApp=true`	Works when a single page serves both modes

Example

// app/layout.tsx
'use client'
import { useEffect } from 'react'
 
export default function RootLayout({ children }: { children: React.ReactNode }) {
  useEffect(() => {
    const url = new URL(window.location.href)
    const isMini =
      url.pathname.startsWith('/mini') ||
      url.searchParams.get('miniApp') === 'true'
 
    if (isMini) {
      import('@farcaster/frame-sdk').then(({ sdk }) => {
        // Mini-App–specific bootstrap here
        // e.g. sdk.actions.ready()
      })
    }
  }, [])
 
  return children
}

On the server you can do the same check to skip expensive Mini App work during SSR.

Verifying ownership

A Mini App is owned by a single Farcaster account. This lets users know who they are interacting with and developers get credit for their work.

verified author

Verification is done by placing a cryptographically signed message in the accountAssociation property of your farcaster.json.

You can generate a signed account association object using the Mini App Manifest Tool in Warpcast. Take the output from that tool and update your farcaster.json file.

Here's an example farcaster.json file for the domain yoink.party with the account association:

{
  "accountAssociation": {
    "header": "eyJmaWQiOjkxNTIsInR5cGUiOiJjdXN0b2R5Iiwia2V5IjoiMHgwMmVmNzkwRGQ3OTkzQTM1ZkQ4NDdDMDUzRURkQUU5NDBEMDU1NTk2In0",
    "payload": "eyJkb21haW4iOiJyZXdhcmRzLndhcnBjYXN0LmNvbSJ9",
    "signature": "MHgxMGQwZGU4ZGYwZDUwZTdmMGIxN2YxMTU2NDI1MjRmZTY0MTUyZGU4ZGU1MWU0MThiYjU4ZjVmZmQxYjRjNDBiNGVlZTRhNDcwNmVmNjhlMzQ0ZGQ5MDBkYmQyMmNlMmVlZGY5ZGQ0N2JlNWRmNzMwYzUxNjE4OWVjZDJjY2Y0MDFj"
  },
  "frame": {
    "version": "1",
    "name": "Rewards",
    "iconUrl": "https://rewards.warpcast.com/app.png",
    "splashImageUrl": "https://rewards.warpcast.com/logo.png",
    "splashBackgroundColor": "#000000",
    "homeUrl": "https://rewards.warpcast.com",
    "webhookUrl": "https://client.warpcast.com/v1/creator-rewards-notifs-webhook",
    "subtitle": "Top Warpcast creators",
    "description": "Climb the leaderboard and earn rewards by being active on Warpcast.",
    "screenshotUrls": [
      "https://rewards.warpcast.com/screenshot1.png",
      "https://rewards.warpcast.com/screenshot2.png",
      "https://rewards.warpcast.com/screenshot3.png"
    ],
    "primaryCategory": "social",
    "tags": [
      "rewards",
      "leaderboard",
      "warpcast",
      "earn"
    ],
    "heroImageUrl": "https://rewards.warpcast.com/og.png",
    "tagline": "Top Warpcast creators",
    "ogTitle": "Rewards",
    "ogDescription": "Climb the leaderboard and earn rewards by being active on Warpcast.",
    "ogImageUrl": "https://rewards.warpcast.com/og.png"
  }
}