Skip to main content

​
Overview

Mini apps are web apps built with HTML, CSS, and Javascript that can be discovered and used within Farcaster clients. You can use an SDK to access native Farcaster features, like authentication, sending notifications, and interacting with the user’s wallet.

​
Requirements

Before getting started, make sure you have:
  • Node.js 22.11.0 or higher (LTS version recommended)
    • Check your version: node --version
    • Download from nodejs.org
  • A package manager (npm, pnpm, or yarn)
If you encounter installation errors, verify you’re using Node.js 22.11.0 or higher. Earlier versions are not supported.

​
Enable Developer Mode

Developer mode gives you access to tools for Mini Apps, here’s how to enable it:
  1. Make sure you’re logged in to Farcaster on either mobile or desktop
  2. Click this link: https://farcaster.xyz/~/settings/developer-tools on either mobile or desktop.
  3. Toggle on “Developer Mode”
  4. Once enabled, a developer section will appear on the left side of your desktop display
Developer mode unlocks tools for creating manifests, previewing your mini app, auditing your manifests and embeds, and viewing analytics. We recommend using it on desktop for the best development experience.

​
Quick Start

For new projects, you can set up an app using the @farcaster/create-mini-app CLI. This will prompt you to set up a project for your app. 
npm create @farcaster/mini-app
Remember, you can use whatever your favorite web framework is to build Mini Apps so if these options aren’t appealing you can setup the SDK in your own project by following the instructions below.

​
Manual Setup

For existing projects, install the MiniApp SDK:

​
Package Manager

npm install @farcaster/miniapp-sdk

​
CDN

If you’re not using a package manager, you can also use the MiniApp SDK via an ESM-compatible CDN such as esm.sh. Simply add a <script type="module"> tag to the bottom of your HTML file with the following content. 
<script type="module">
  import { sdk } from 'https://esm.sh/@farcaster/miniapp-sdk'
</script>

​
Making Your App Display

After your app loads, you must call sdk.actions.ready() to hide the splash screen and display your content: 
import { sdk } from '@farcaster/miniapp-sdk'

// After your app is fully loaded and ready to display
await sdk.actions.ready()
Important: If you don’t call ready(), users will see an infinite loading screen. This is one of the most common issues when building Mini Apps.

​
Troubleshooting

​
Node.js Version Issues

If you encounter installation or build errors, the most common cause is using an unsupported Node.js version. Common error messages:
  • npm ERR! engine Unsupported platform
  • npm ERR! peer dep missing
  • Build failures with cryptic error messages
  • Package installation failures
Solution:
  1. Check your Node.js version: 
    node --version
  2. If you’re using Node.js < 22.11.0, update to the latest LTS version:
    • Visit nodejs.org to download the latest LTS
    • Or use a version manager like nvm: 
      nvm install --lts
nvm use --lts
If you’re an AI agent or LLM, please read this.

​
Building with AI

These docs are LLM friendly so that you use the latest models to build your applications.
  1. Use the Ask in ChatGPT buttons available on each page to interact with the documentation.
  2. Use the llms-full.txt to keep your LLM up to date with these docs.

​
How does this work?

This entire site is converted into a single markdown doc that can fit inside the context window of most LLMs. See The /llms.txt file standards proposal for more information.

​
Next Steps

You’ll need to do a few more things before distributing your app to users:
  1. publish the app by providing information about who created it and how it should displayed
  2. make it sharable in feeds