diff --git a/docs/docs.json b/docs/docs.json index 9d826071..2f02ff80 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -413,6 +413,117 @@ } ] }, + { + "tab": "Mini Apps", + "groups": [ + { + "group": "Introduction", + "pages": ["mini-apps/overview"] + }, + { + "group": "Quickstart", + "pages": [ + { + "group": "New Apps", + "pages": [ + "mini-apps/quickstart/build-a-mini-app/install", + "mini-apps/quickstart/build-a-mini-app/deploy", + "mini-apps/quickstart/build-a-mini-app/create-manifest", + "mini-apps/quickstart/build-a-mini-app/feature-tour" + ] + }, + { + "group": "Existing Apps", + "pages": [ + "mini-apps/quickstart/turn-your-app-into-a-mini-app/install", + "mini-apps/quickstart/turn-your-app-into-a-mini-app/add-minikit", + "mini-apps/quickstart/turn-your-app-into-a-mini-app/configure-environment", + "mini-apps/quickstart/turn-your-app-into-a-mini-app/manifest-cli", + "mini-apps/quickstart/turn-your-app-into-a-mini-app/create-farcaster-json", + "mini-apps/quickstart/turn-your-app-into-a-mini-app/add-frame-metadata", + "mini-apps/quickstart/turn-your-app-into-a-mini-app/test-and-deploy" + ] + }, + "mini-apps/quickstart/launch-guide" + ] + }, + { + "group": "Get Featured", + "pages": [ + "mini-apps/quality-and-publishing/overview", + "mini-apps/quality-and-publishing/quality-bar", + "mini-apps/quality-and-publishing/submission-guidelines" + ] + }, + { + "group": "Design & UX Standards", + "pages": [ + "mini-apps/design-ux/design-patterns-for-mini-apps", + "mini-apps/design-ux/onchainkit-usage", + "mini-apps/design-ux/ui-patterns", + "mini-apps/design-ux/language-and-tone" + ] + }, + { + "group": "Growth Playbook", + "pages": [ + "mini-apps/growth/optimized-onboarding", + "mini-apps/growth/build-viral-mini-apps", + "mini-apps/growth/base-build-analytics", + "mini-apps/growth/implementing-other-analytics", + "mini-apps/growth/event-schema" + ] + }, + { + "group": "Mini App Features", + "pages": [ + "mini-apps/features/overview", + "mini-apps/features/manifest", + "mini-apps/features/authentication", + "mini-apps/features/embeds-and-previews", + "mini-apps/features/search-and-discovery", + "mini-apps/features/sharing-and-social-graph", + "mini-apps/features/notifications", + "mini-apps/features/open-close-and-external-links", + "mini-apps/features/webhooks" + ] + }, + { + "group": "Troubleshooting", + "pages": [ + "mini-apps/troubleshooting/common-issues", + "mini-apps/troubleshooting/error-handling", + "mini-apps/troubleshooting/base-app-compatibility" + ] + }, + { + "group": "Technical Reference", + "pages": [ + { + "group": "MiniKit", + "pages": [ + "mini-apps/technical-reference/minikit/provider-and-initialization", + { + "group": "Hooks", + "pages": [ + "mini-apps/technical-reference/minikit/hooks/useMiniKit", + "mini-apps/technical-reference/minikit/hooks/useAddFrame", + "mini-apps/technical-reference/minikit/hooks/useNotification", + "mini-apps/technical-reference/minikit/hooks/useOpenUrl", + "mini-apps/technical-reference/minikit/hooks/useClose", + "mini-apps/technical-reference/minikit/hooks/usePrimaryButton", + "mini-apps/technical-reference/minikit/hooks/useViewProfile", + "mini-apps/technical-reference/minikit/hooks/useComposeCast", + "mini-apps/technical-reference/minikit/hooks/useViewCast", + "mini-apps/technical-reference/minikit/hooks/useAuthenticate" + ] + } + ] + } + ] + } + ] + }, { "tab": "OnchainKit", "groups": [ diff --git a/docs/mini-apps/design-ux/design-patterns-for-mini-apps.mdx b/docs/mini-apps/design-ux/design-patterns-for-mini-apps.mdx new file mode 100644 index 00000000..9835d7e0 --- /dev/null +++ b/docs/mini-apps/design-ux/design-patterns-for-mini-apps.mdx @@ -0,0 +1,16 @@ +--- +title: Design Patterns for Mini Apps +description: Principles and patterns to build social, repeat-use experiences +--- + +Importing core content from Thinking Social. + + +This page will summarize design principles and link to the detailed guide below. + + + + +TODO: Add condensed patterns and examples tailored to Mini Apps (identity, co‑creation, rituals). + + diff --git a/docs/mini-apps/design-ux/language-and-tone.mdx b/docs/mini-apps/design-ux/language-and-tone.mdx new file mode 100644 index 00000000..0feb1439 --- /dev/null +++ b/docs/mini-apps/design-ux/language-and-tone.mdx @@ -0,0 +1,8 @@ +--- +title: Language and Tone +description: Copy guidelines for concise, friendly Mini App experiences +--- + +TODO: Provide copy patterns for onboarding, errors, and social sharing within Mini Apps. + + diff --git a/docs/mini-apps/design-ux/onchainkit-usage.mdx b/docs/mini-apps/design-ux/onchainkit-usage.mdx new file mode 100644 index 00000000..f7b7f26f --- /dev/null +++ b/docs/mini-apps/design-ux/onchainkit-usage.mdx @@ -0,0 +1,8 @@ +--- +title: OnchainKit Usage in Mini Apps +description: How to leverage OnchainKit components and MiniKit together +--- + +TODO: Document recommended OnchainKit components for Mini Apps, integration tips, and examples. + + diff --git a/docs/mini-apps/design-ux/ui-patterns.mdx b/docs/mini-apps/design-ux/ui-patterns.mdx new file mode 100644 index 00000000..895131bf --- /dev/null +++ b/docs/mini-apps/design-ux/ui-patterns.mdx @@ -0,0 +1,8 @@ +--- +title: UI Patterns for Mini Apps +description: Compact, touch-first interfaces that fit Mini App contexts +--- + +TODO: Safe area insets, primary button usage, compact layouts, input ergonomics, and accessibility considerations. + + diff --git a/docs/mini-apps/features/Authentication.mdx b/docs/mini-apps/features/Authentication.mdx new file mode 100644 index 00000000..cefc0c03 --- /dev/null +++ b/docs/mini-apps/features/Authentication.mdx @@ -0,0 +1,42 @@ +--- +title: Authentication +description: Let users start fast and ask for a wallet only when needed +--- + +## Authentication guidance from Base App + + +Save authentication that requires an interaction for interactions that require it (e.g., buying something, viewing personalized pages). + + +Supported approaches: + + + +Base App supports SIWF in‑app, enabling social identity without leaving the app. Quick Auth can issue a JWT to persist session state. + + + +Base App provides an in‑app smart wallet. Use wallet auth for a persisted session when necessary, but avoid gating initial exploration behind connect. + + + +All hosts return context data (including user). Use it for analytics or lightweight session hints, but do not treat as primary auth. + + + +Best practices: + +- Gate wallet only at the point of onchain action +- Prefer SIWF/Quick Auth for low‑friction identity +- Use context for analytics; avoid using it as primary auth + +Further reading: + + + + + + + + diff --git a/docs/mini-apps/features/embeds-and-previews.mdx b/docs/mini-apps/features/embeds-and-previews.mdx new file mode 100644 index 00000000..00fedddd --- /dev/null +++ b/docs/mini-apps/features/embeds-and-previews.mdx @@ -0,0 +1,272 @@ +--- +title: Embeds & Previews +description: Turn every user action into organic growth with shareable, metadata-powered embeds that drive engagement and discovery. +--- + +> **What you'll learn** +> By the end of this guide, you'll be able to: +> - Understand how embeds and metadata work together to create rich social previews +> - Choose between static and dynamic embeds for different use cases +> - Debug and optimize embeds for maximum performance and engagement + +## Why Sharing Matters + +Sharing is one of the fastest and most cost-effective ways to grow your Mini App user base. + +When a user shares your app into a feed (such as Base App or Farcaster), the platform generates a **rich embed** — a visual preview complete with your branding, imagery, and call-to-action button that appears directly in social feeds. + +Every share: + +- **Increases reach** — friends and followers see your app instantly +- **Drives engagement** — visually compelling embeds get more clicks than plain links +- **Improves ranking** — shared apps are more likely to appear in "Trending" and category leaderboards +- **Creates viral loops** — great experiences encourage users to share with their networks + +## Metadata and Embeds + +### How Metadata Creates Embeds + +When someone shares your Mini App link, platforms like Base App don't just show a plain URL. Instead, they fetch **metadata** from your page and use it to generate a rich **embed** — a visual preview card with your image, title, and call-to-action button. + +The metadata acts as instructions that tell the platform exactly how to display your Mini App in feeds. + + + How embed data is rendered + + +**The complete metadata-to-embed process:** + + + + User clicks share or pastes your Mini App URL into a social feed (Base App, Farcaster). + + + + The platform makes a request to your URL and reads the `` tags in your HTML to understand how to display your app. + + + + Platform transforms your metadata into a rich visual embed with image, title, description, and interactive button. + + + + Your Mini App appears as an attractive, clickable card that users can launch directly from their feed. + + + +### Metadata Structure + +Your metadata consists of specific HTML meta tags that define each part of the embed: + +```html + +``` + +Each piece of metadata directly corresponds to a visual element in the embed: + +- `imageUrl` → The main visual that appears in the embed +- `button.title` → Text on the call-to-action button +- `action.name` → App name displayed in the embed +- `action.url` → Where users go when they click the embed + +### Embed Appearance in Feeds + + +Mini app feed + + +### Manifest vs Embed Metadata + +Your Mini App uses two types of metadata: + +#### Manifest file + +Purpose: App registration and discovery + +Located at `/.well-known/farcaster.json`, this file contains your app's basic information for Base App's directory. + + +Mini Apps require a complete manifest. Read the [manifest requirements](/mini-apps/features/manifest#example-manifest). + + +#### Embed metadata + +Purpose: Embed generation when shared + +Located in your HTML `` tags, this metadata creates the rich embeds when users share your app. + +```html + +``` + +This controls how your embeds appear in social feeds. + +### Best Practices for Metadata + +- Image optimization: Use 3:2 aspect ratio +- Clear value proposition in button and text +- Visual consistency with product UI +- Fast loading for metadata endpoints +- Validate across platforms pre‑launch + +## Sharing + +### Adding Share Functionality + +Prompt users to share during key accomplishment moments using MiniKit’s compose hook. + +```ts +import { useComposeCast } from '@coinbase/onchainkit/minikit'; + +export default function ComposeCastButton() { + const { composeCast } = useComposeCast(); + + const handleCompose = () => { + composeCast({ + text: 'Just minted an awesome NFT using @coinbase OnchainKit! ', + }); + }; + + const handleComposeWithEmbed = () => { + composeCast({ + text: 'Check out this amazing Mini App!', + embeds: ['https://your-mini-app-url.com'], + }); + }; + + return ( +
+ + +
+ ); +} +``` + + +Strategic sharing moments: + +- After completing a quiz +- After minting an NFT +- After beating a challenge +- After reaching a milestone + + +### From the Base App UI + +Users can also share directly from your app's detail view in the Base app through the built‑in share functionality. + + + Share button in Base app + + +## Embed Types + +### Static embeds + +Use a single, unchanging image and text for all shares. Best for consistency and speed. + +### Dynamic embeds + +Generate metadata per user or event for personalization and FOMO. Ensure fast response (< 5s) and caching strategy. + +## Implementation + +### With MiniKit (Next.js) + +```ts layout.tsx +export async function generateMetadata(): Promise { + const URL = process.env.NEXT_PUBLIC_URL; + return { + title: process.env.NEXT_PUBLIC_ONCHAINKIT_PROJECT_NAME, + description: "Your Mini App description here", + other: { + "fc:frame": JSON.stringify({ + version: "next", + imageUrl: process.env.NEXT_PUBLIC_APP_HERO_IMAGE, + button: { + title: `Launch ${process.env.NEXT_PUBLIC_ONCHAINKIT_PROJECT_NAME}`, + action: { + type: "launch_frame", + name: process.env.NEXT_PUBLIC_ONCHAINKIT_PROJECT_NAME, + url: URL, + splashImageUrl: process.env.NEXT_PUBLIC_SPLASH_IMAGE, + splashBackgroundColor: process.env.NEXT_PUBLIC_SPLASH_BACKGROUND_COLOR, + }, + }, + }), + }, + }; +} +``` + +### Without MiniKit + +```html + +``` + +## Debugging + +### Tools + + + Test your metadata and preview embeds + + +### Common issues + + + +Check image dimensions, required `fc:frame`, JSON validity, and URL accessibility. + + +Review cache headers, repost to refresh, wait ~10–15 minutes for caches. + + +Optimize image generation, pre‑generate, use serverless, compress assets. + + + + +Set `Cache-Control` carefully: long enough for performance (300–600s), short enough for quick updates. + + +## Next Steps + + + + + + + + +Continue with: + +- [Search and Discovery](/mini-apps/features/search-and-discovery) +- [Manifest](/mini-apps/features/manifest) + + + diff --git a/docs/mini-apps/features/manifest.mdx b/docs/mini-apps/features/manifest.mdx new file mode 100644 index 00000000..b043c45d --- /dev/null +++ b/docs/mini-apps/features/manifest.mdx @@ -0,0 +1,231 @@ +--- +title: Manifest +description: Define and configure your Mini App’s manifest to power search, discovery, and rich embeds in the Base App. +--- + +> **What you’ll learn** +> By the end of this guide, you’ll be able to: +> - Define a complete `farcaster.json` manifest that meets Base App requirements. +> - Map each manifest property to its role in search, discovery, and embeds. +> - Validate images, text, and URLs against required constraints. +> - Link your manifest to your domain using `accountAssociation`. +> - Control indexing for staging and production with `noindex`. + +## Overview + +Your `/.well-known/farcaster.json` file is the manifest for your Mini App. It contains all the metadata Base App uses to: + +- Display your app in search results, trending sections, and category listings +- Generate rich, clickable embeds when your app is shared +- Show your app in users’ saved apps for quick access + +If the manifest is missing, incomplete, or invalid, your app won’t appear in Base App discovery features. + +## Location + +Serve your manifest over HTTPS at: + +``` +https://your-domain.com/.well-known/farcaster.json +``` + + +Serve with `Content-Type: application/json` and ensure the file is publicly accessible (no auth). + + + +## How Base App uses Manifest + +- **Search indexing**: Your app appears in search after it has been shared at least once. Indexing typically completes in ~10 minutes. +- **Category placement**: `primaryCategory` determines where your app appears in category browsing. `tags` improve cross-surface visibility and filtering. +- **Embeds**: Open Graph fields (`ogTitle`, `ogDescription`, `ogImageUrl`) and `heroImageUrl` power compelling feed previews that drive clicks. +- **Saved apps**: `name` and `iconUrl` appear when users save your Mini App for quick access. + + +If your Mini App does not show in search, follow the debugging guide [here](/mini-apps/troubleshooting/common-issues#1-app-discovery--indexing-issues). + + + +## Example manifest + +```json +{ + "accountAssociation": { + "header": "eyJmaWQiOjkxNTIsInR5cGUiOiJjdXN0b2R5Iiwia2V5IjoiMHgwMmVmNzkwRGQ3OTkzQTM1ZkQ4NDdDMDUzRURkQUU5NDBEMDU1NTk2In0", + "payload": "eyJkb21haW4iOiJhcHAuZXhhbXBsZS5jb20ifQ", + "signature": "MHgxMGQwZGU4ZGYwZDUwZTdmMGIxN2YxMTU2NDI1MjRmZTY0MTUyZGU4ZGU1MWU0MThiYjU4ZjVmZmQxYjRjNDBiNGVlZTRhNDcwNmVmNjhlMzQ0ZGQ5MDBkYmQyMmNlMmVlZGY5ZGQ0N2JlNWRmNzMwYzUxNjE4OWVjZDJjY2Y0MDFj" + }, + "frame": { + "version": "1", + "name": "Example Mini App", + "homeUrl": "https://ex.co", + "iconUrl": "https://ex.co/i.png", + "splashImageUrl": "https://ex.co/l.png", + "splashBackgroundColor": "#000000", + "webhookUrl": "https://ex.co/api/webhook", + "subtitle": "Fast, fun, social", + "description": "A fast, fun way to challenge friends in real time.", + "screenshotUrls": [ + "https://ex.co/s1.png", + "https://ex.co/s2.png", + "https://ex.co/s3.png" + ], + "primaryCategory": "social", + "tags": ["example", "miniapp", "baseapp"], + "heroImageUrl": "https://ex.co/og.png", + "tagline": "Play instantly", + "ogTitle": "Example Mini App", + "ogDescription": "Challenge friends in real time.", + "ogImageUrl": "https://ex.co/og.png", + "noindex": true + } +} +``` + + +For a visual mapping of how fields render, see the [Mini App specification reference](/mini-apps/features/search-and-discovery#how-metadata-works). + + + + +## Field reference + +### Top-level fields + +| Property | Type | Required | Description | +|---------------------|--------|----------|---------------------------------------------------| +| `accountAssociation`| object | Yes | Proves domain ownership for your Mini App. | +| `frame` | object | Yes | Contains all metadata used by Base App. | + + +### `accountAssociation` fields + +| Property | Type | Required | Description | +|-------------|--------|----------|----------------------------------------------| +| `header` | string | Yes | Encoded header for the association payload. | +| `payload` | string | Yes | Encoded payload containing your domain. | +| `signature` | string | Yes | Signature over the payload. | + + +### `frame` fields + +#### Identity & Launch + +Defines your Mini App’s core identity and the URL users land on when they open it. + +| Property | Type | Required | Description | Constraints | +|-----------------|--------|----------|---------------------------|-------------| +| `version` | string | Yes | Manifest version. | Must be `"1"`. | +| `name` | string | Yes | Mini App name. | Max 32 chars. | +| `homeUrl` | string | Yes | Default launch URL. | HTTPS URL, max 1024 chars. | +| `iconUrl` | string | Yes | Icon image URL. | HTTPS URL, PNG 1024×1024; transparent background discouraged. | + +--- + + +#### Loading Experience + +Controls the splash screen visuals and colors shown while your Mini App loads. + +| Property | Type | Required | Description | Constraints | +|-------------------------|--------|----------|----------------------------|-------------| +| `splashImageUrl` | string | Yes | Loading image. | HTTPS URL, recommended 200×200px. | +| `splashBackgroundColor` | string | Yes | Loading background color. | Hex code (e.g., `#000000`). | + +--- + +#### Discovery & Search + +Determines how your Mini App is indexed, categorized, and surfaced across Base App discovery features. + +| Property | Type | Required | Description | Constraints | +|--------------------|----------|----------|----------------------------------------------------|-------------| +| `primaryCategory` | string | Yes | Controls where your app appears in category browsing. | One of: `games`, `social`, `finance`, `utility`, `productivity`, `health-fitness`, `news-media`, `music`, `shopping`, `education`, `developer-tools`, `entertainment`, `art-creativity`. | +| `tags` | string[] | Yes | Search/filter tags. | Up to 5; ≤ 20 chars each; lowercase; no spaces/emojis/special chars. | +| `noindex` | boolean | No | Exclude from search results. | `true` = exclude, default = include. | +| `requiredChains` | string[] | No | CAIP-2 chain IDs. | Supported: `eip155:8453` (Base mainnet), `eip155:84532` (Base Sepolia). | + +--- + +#### Display Information + +Provides the descriptive text, screenshots, and promotional images shown on your Mini App’s profile. + +| Property | Type | Required | Description | Constraints | +|------------------|----------|----------|-------------------------------------|-------------| +| `subtitle` | string | No | Short description under name. | Max 30 chars; avoid emojis/special chars. | +| `description` | string | No | Promo text for app page. | Max 170 chars; avoid emojis/special chars. | +| `tagline` | string | No | Marketing tagline. | Max 30 chars. | +| `heroImageUrl` | string | No | Large promo image. | 1200×630px (1.91:1), PNG/JPG. | +| `screenshotUrls` | string[] | No | Visual previews. | Max 3; portrait 1284×2778px recommended. | + +--- + +#### Embeds & Social Sharing + +Configures how your Mini App appears when shared in feeds or on social platforms. + +| Property | Type | Required | Description | Constraints | +|---------------------------|--------|----------|---------------------------|-------------| +| `ogTitle` | string | No | Open Graph title. | Max 30 chars. | +| `ogDescription` | string | No | Open Graph description. | Max 100 chars. | +| `ogImageUrl` | string | No | Open Graph image. | 1200×630px (1.91:1), PNG/JPG. | +| `imageUrl` (deprecated) | string | No | Legacy default feed image.| Prefer `ogImageUrl`. | +| `buttonTitle` (deprecated)| string | No | Legacy feed button text. | Prefer embed button config in OG. | + +--- + +#### Advanced Capabilities + +Specifies technical integrations, event handling, and special permissions your Mini App requires. + +| Property | Type | Required | Description | Constraints | +|------------------------|----------|----------|-----------------------------|-------------| +| `webhookUrl` | string | No | POST events endpoint. | HTTPS URL, max 1024 chars. Required if using notifications. | + + + +Choose your `primaryCategory` carefully — it determines where your app appears in Base App’s category browsing and rankings. + + + +## Validation checklist + +- Manifest is served over HTTPS at `/.well-known/farcaster.json` +- All required fields are present +- Image sizes match the constraints (icon, OG, hero, screenshots) +- Text fields respect character and formatting limits +- `"noindex": true` is used only for staging/development + + + +Test your manifest with a simple `curl` to confirm accessibility and headers: `curl -sI https://your-domain.com/.well-known/farcaster.json`. + + + +## Development vs. production + +- Set `"noindex": true` for development or staging environments to prevent search indexing. +- Remove or set `"noindex": false` for production so users can discover your app. + + +Your app appears in search after the first share is detected. Indexing usually completes in ~10 minutes. + + + +## Common issues + +- Missing required fields → app won’t index in search +- Image format/size mismatches → broken or distorted embeds +- Invalid `primaryCategory` → app won’t appear in category browsing +- Overlong strings → truncation or rejection at indexing +- Manifest not publicly accessible → discovery fails + + +## Next steps + +- Review discovery mechanics and ranking in [Mini App Search and Discovery](/mini-apps/features/search-and-discovery) +- Learn how embeds are generated and tested in [Sharing Your Mini App](/mini-apps/features/embeds-and-previews) + + + diff --git a/docs/mini-apps/features/notifications.mdx b/docs/mini-apps/features/notifications.mdx new file mode 100644 index 00000000..2c84fac0 --- /dev/null +++ b/docs/mini-apps/features/notifications.mdx @@ -0,0 +1,8 @@ +--- +title: Notifications (coming soon) +description: Send relevant, rate‑limited notifications to users who saved your Mini App +--- + +TODO: Add guidance for `useAddFrame` + `useNotification`, proxy route, and rate limiting. + + diff --git a/docs/mini-apps/features/open-close-and-external-links.mdx b/docs/mini-apps/features/open-close-and-external-links.mdx new file mode 100644 index 00000000..3206b3cd --- /dev/null +++ b/docs/mini-apps/features/open-close-and-external-links.mdx @@ -0,0 +1,27 @@ +--- +title: Open/Close & External Links +description: Handle closing the frame and opening external URLs safely +--- + +What you’ll build + +- Buttons to close the frame and open external URLs + +Do it + +1) Add `useClose` and wire to a button +2) Add `useOpenUrl` and wire to external links + +Verify + +- Close button dismisses the frame +- External links open correctly in and out of frame contexts + +Deep dive + + + + + + + diff --git a/docs/mini-apps/features/overview.mdx b/docs/mini-apps/features/overview.mdx new file mode 100644 index 00000000..82099017 --- /dev/null +++ b/docs/mini-apps/features/overview.mdx @@ -0,0 +1,24 @@ +--- +title: Catalog +description: Browse and implement bite‑size features for your Mini App +--- + +Pick a feature to implement. Each guide starts with value, then shows copy‑paste steps and a quick verification. + + + + + + + + + + + + + + +Looking for supported surfaces? See Base App (TBA) Compatibility in Troubleshooting. + + + diff --git a/docs/mini-apps/features/search-and-discovery.mdx b/docs/mini-apps/features/search-and-discovery.mdx new file mode 100644 index 00000000..424889a6 --- /dev/null +++ b/docs/mini-apps/features/search-and-discovery.mdx @@ -0,0 +1,89 @@ +--- +title: Search and Discovery +description: Learn how users discover and access Mini Apps in the Base ecosystem, including discovery surfaces, ranking systems, and optimization strategies for maximum visibility. +--- + +> **What you’ll learn** +> By the end of this guide, you’ll be able to: +> - Get your Mini App indexed in Base App search and understand how indexing works. +> - Choose the right categories and implement strategies to rank higher in “Trending Today.” +> - Apply best practices to increase discoverability across Base App surfaces. + +## Search + +### How Search Works +Users discover Mini Apps through direct search queries in Base App. + + +search bar in base app + + +Your Mini App will only appear in search results after it has been indexed. To ensure indexing, share your Mini App at least once in Base App. Indexing typically takes ~10 minutes after the first share. + +### Managing Search Indexing + +Development Environment: add `"noindex": true` to prevent dev/staging from appearing in search. Remove or set false for production. + +**Removing from Search:** +To remove your Mini App from search results, invalidate your manifest (removes from all discovery). + + +If your Mini App does not show in search please follow the debugging guide [here](/mini-apps/troubleshooting/common-issues#1-app-discovery--indexing-issues) + + +## Discovery Surfaces + +### Trending Today +The "Trending Today" section showcases the most popular Mini Apps being actively used and shared. + + +Mini App showing trending view + + +Signals include social sharing frequency and current user engagement metrics. + +### Saved Apps +Personal launcher and quick access hub + + +saved apps + + +Appears here: +- User's saved Mini Apps +- Recently used applications + +Prompt users to save via the Add Frame flow at key value moments. + +### App Categories +Browsable directory organized by interest + + +app categories + + + +Choose your primaryCategory carefully as it determines where your app appears in Base App's category browsing. + + + +app categories + + + The Base app uses aggregated data (7-day rolling window) to generate dynamic category rankings and identify trending applications. + +## Build for Discovery: Checklist + +- [ ] Implement proper manifest files with correct categorization +- [ ] Choose relevant categories (primaryCategory) +- [ ] Create shareable moments that naturally encourage shares +- [ ] Design compelling embeds with clear CTAs +- [ ] Encourage saves for easy return access + +Further reading: + +- [Sharing & Embeds](/mini-apps/features/embeds-and-previews) +- [Manifest](/mini-apps/features/manifest) + + + diff --git a/docs/mini-apps/features/sharing-and-social-graph.mdx b/docs/mini-apps/features/sharing-and-social-graph.mdx new file mode 100644 index 00000000..40fc30ec --- /dev/null +++ b/docs/mini-apps/features/sharing-and-social-graph.mdx @@ -0,0 +1,60 @@ +--- +title: Sharing & Social Graph +description: Enable native share flows and social navigation +--- + +## Adding Share Functionality + +Prompt users to share during key accomplishment moments using MiniKit’s compose hook. + +```ts +import { useComposeCast } from '@coinbase/onchainkit/minikit'; + +export default function ComposeCastButton() { + const { composeCast } = useComposeCast(); + + const handleCompose = () => { + composeCast({ text: 'Just minted an awesome NFT using @coinbase OnchainKit!' }); + }; + + const handleComposeWithEmbed = () => { + composeCast({ + text: 'Check out this amazing Mini App!', + embeds: ['https://your-mini-app-url.com'], + }); + }; + + return ( +
+ + +
+ ); +} +``` + + +Strategic sharing moments include: post‑achievement, post‑mint, after beating a challenge, or reaching milestones. + + +## View Casts and Profiles + +Link users into casts and profiles directly from your app via MiniKit hooks. + + + + + + +## Best Practices + +- Encourage meaningful, contextual shares +- Avoid spammy prompts; tie sharing to value +- Make shared previews visually consistent with your UI + +Further reading: + +- [Embeds & Previews](/mini-apps/features/embeds-and-previews) + + + diff --git a/docs/mini-apps/features/webhooks.mdx b/docs/mini-apps/features/webhooks.mdx new file mode 100644 index 00000000..56005d58 --- /dev/null +++ b/docs/mini-apps/features/webhooks.mdx @@ -0,0 +1,8 @@ +--- +title: Webhooks +description: React to Mini App events using verified webhooks +--- + +TODO: Document webhook setup, verification, and example handlers (e.g., FRAME_ADDED). + + diff --git a/docs/mini-apps/growth/base-build-analytics.mdx b/docs/mini-apps/growth/base-build-analytics.mdx new file mode 100644 index 00000000..774cc063 --- /dev/null +++ b/docs/mini-apps/growth/base-build-analytics.mdx @@ -0,0 +1,8 @@ +--- +title: Base Build Analytics +description: Measure activation, retention, sharing, and saves for Mini Apps +--- + +TODO: Define core metrics, suggested events, and dashboards for Mini Apps. + + diff --git a/docs/mini-apps/growth/build-viral-mini-apps.mdx b/docs/mini-apps/growth/build-viral-mini-apps.mdx new file mode 100644 index 00000000..029a40d1 --- /dev/null +++ b/docs/mini-apps/growth/build-viral-mini-apps.mdx @@ -0,0 +1,11 @@ +--- +title: Build Viral Mini Apps +description: Designing mini apps that people actually come back to +--- + +Importing the full Thinking Social content here is recommended. For now, see: + + + + + diff --git a/docs/mini-apps/growth/event-schema.mdx b/docs/mini-apps/growth/event-schema.mdx new file mode 100644 index 00000000..e4dd4dea --- /dev/null +++ b/docs/mini-apps/growth/event-schema.mdx @@ -0,0 +1,8 @@ +--- +title: Event Schema +description: A suggested event model for Mini Apps to enable consistent analytics +--- + +TODO: Propose event names, properties, and semantics (save, share, notify, session, auth). + + diff --git a/docs/mini-apps/growth/implementing-other-analytics.mdx b/docs/mini-apps/growth/implementing-other-analytics.mdx new file mode 100644 index 00000000..a977b8a1 --- /dev/null +++ b/docs/mini-apps/growth/implementing-other-analytics.mdx @@ -0,0 +1,8 @@ +--- +title: Implementing Other Analytics +description: Instrument Mini Apps with your preferred analytics stack +--- + +TODO: Provide examples for common stacks and privacy considerations. + + diff --git a/docs/mini-apps/growth/optimized-onboarding.mdx b/docs/mini-apps/growth/optimized-onboarding.mdx new file mode 100644 index 00000000..ef123584 --- /dev/null +++ b/docs/mini-apps/growth/optimized-onboarding.mdx @@ -0,0 +1,8 @@ +--- +title: Optimized Onboarding +description: Reduce friction with wallet‑optional flows and clear value moments +--- + +TODO: Patterns for deferring wallet, progressive prompts, and measuring activation. + + diff --git a/docs/mini-apps/overview.mdx b/docs/mini-apps/overview.mdx new file mode 100644 index 00000000..eaa59686 --- /dev/null +++ b/docs/mini-apps/overview.mdx @@ -0,0 +1,183 @@ +--- +title: "Why Mini Apps" +description: "Discover how Mini Apps eliminate friction and leverage social distribution to create instantly engaging, viral experiences that traditional apps can't match." +--- + +The next evolution of digital experiences extends beyond app stores into social feeds and direct messages. Mini Apps are lightweight, social-native apps that launch instantly when you tap them: no downloads, no friction, just immediate engagement. While the Base App provides the discoverability through social distribution and featured listings, Mini Apps deliver the frictionless experience that makes instant trial and viral sharing possible. + + +Existing web applications can be converted into Mini Apps. Learn how to [integrate your existing app](/mini-apps/quickstart/turn-your-app-into-a-mini-app/install) with our helpful guide. + + +## Beyond the App Store Model + +Traditional apps face costly user acquisition because they're buried among millions of competitors in app stores, require separate iOS and Android development with ongoing maintenance across platforms, and create commitment friction through installation requirements. Mini Apps eliminate these barriers entirely by running as lightweight web applications that work instantly across all devices, deploy with zero installation friction, and spread organically through social feeds where users naturally discover content—turning every interaction into potential viral distribution that no app store algorithm can match. + + + + - Limited to app store discovery + - Require downloads and installations + - Expensive user acquisition campaigns + - Users start with empty social graphs + + + + - Distributed through social feeds + - Launch instantly with one tap + - Viral distribution through social sharing + - Built-in friend networks and social context + + + +## What Makes Mini Apps Different + +### For Users: Frictionless Discovery and Engagement + +Mini Apps eliminate the gap between discovery and engagement. Instead of downloading apps you might never use again, you can instantly try interactive experiences shared by friends. With leaderboards, challenges, and multiplayer features, these apps transform from individual experiences into social activities you do with your friends—competing, collaborating, and sharing achievements together. + +### For Builders: Built-in Social Infrastructure + +As a developer, you build on top of existing social infrastructure instead of recreating it from scratch. + +**What you get out of the box:** +- User identity and authentication +- Social connections and friend graphs +- Viral distribution mechanisms +- Immediate access to engaged communities + + +When someone shares a Mini App, they're sharing the entire interactive experience, not just a link. + + + +## The Builder's Advantage + +Mini Apps solve three major product development challenges: + + +Image of social feed with Mini Apps + + + + **Traditional Apps:** Builders pay for ads and fight algorithms for visibility + + **Mini Apps Solution:** User activity appears organically in their social feed (followers, friends, connections), naturally inviting others through social proof via sharing. + + + + +Image of social feed with Mini Apps + + + + + **Traditional Apps:** Expensive campaigns with low conversion rates. + + **Mini Apps Solution:** Every interaction becomes viral distribution. Users broadcast engagement to their entire network, creating compound growth loops that traditional apps can't achieve. + + + + +Image of social feed with Mini Apps + + + + **Traditional Apps:** Users start alone and build social graphs slowly. + + **Mini Apps Solution:** Launch directly into existing friend groups, see live activity from friends, and join conversations already in progress. + + + + + +## The Network Effect Advantage + + +Image of builder flywheel + + +As more people interact with these apps, they create valuable user activity and market opportunities that attract talented builders to Base, who see the engaged audience and build even better, more innovative experiences to capture that demand.This self-reinforcing cycle means every successful app strengthens the entire network, creating exponential growth that benefits every builder on Base. + + + +## What You Can Build + +The most successful Mini Apps solve everyday problems with built-in social mechanics: + + + + - Multiplayer games with real-time competition + - Trivia nights with friend groups + - Interactive stories and collaborative experiences + + + + - Group buying for better discounts + - Product recommendations from trusted friends + - Collaborative wish lists and gift planning + + + + + - Event planning with built-in RSVP tracking + - Group dining decisions with real-time voting + - Expense splitting with transparent calculations + - Travel planning with collaborative itineraries + + + + - Collaborative art and design projects + - Study groups with progress tracking + - Skill-sharing marketplaces + - Book clubs and discussion forums + + + + +**The winning pattern:** Take activities people already do individually or struggle to coordinate with others, then make them social, transparent, and immediate. + + +## From Idea to Live Application + +The development path is streamlined and permissionless: + + + + Use [MiniKit](/mini-apps/quickstart/build-a-mini-app/install) or the [Farcaster SDK](https://miniapps.farcaster.xyz/docs/getting-started) to create your application. + + + + Deploy your Mini App without waiting for approval processes or store reviews. + + + + Post your Mini App to Base App and it gets automatically indexed for discovery. No special permissions or approval processes required to show up in the Base App. + + Your app becomes instantly discoverable in: + - Base App search results + - The broader Farcaster ecosystem + - User social feeds through organic sharing + + + + + Monitor actual usage patterns and iterate based on real user feedback rather than building in isolation. + + + +## Start Building Today + +Mini Apps represent a fundamental shift toward social-native digital experiences. The advantage goes to builders who understand that in a social-first world, distribution and engagement are built into the platform itself. + + + + Get started with MiniKit and build your first Mini App in minutes. + + + + Already have a web app? Turn it into a Mini App with our integration guide. + + + + diff --git a/docs/mini-apps/quality-and-publishing/overview.mdx b/docs/mini-apps/quality-and-publishing/overview.mdx new file mode 100644 index 00000000..d33574a6 --- /dev/null +++ b/docs/mini-apps/quality-and-publishing/overview.mdx @@ -0,0 +1,8 @@ +--- +title: Overview +description: How to meet the bar and submit your Mini App for featuring +--- + +TODO: Write end‑to‑end guidance for becoming Featured: prerequisites, examples, review process, and timelines. Link to Quality Bar and Submission Guidelines. + + diff --git a/docs/mini-apps/quality-and-publishing/quality-bar.mdx b/docs/mini-apps/quality-and-publishing/quality-bar.mdx new file mode 100644 index 00000000..264aeab5 --- /dev/null +++ b/docs/mini-apps/quality-and-publishing/quality-bar.mdx @@ -0,0 +1,8 @@ +--- +title: Quality Bar +description: The standards your Mini App should meet before being featured +--- + +TODO: Draft the full Quality Bar article with performance, stability, UX, and instrumentation requirements. Link concrete acceptance criteria and example checks. + + diff --git a/docs/mini-apps/quality-and-publishing/submission-guidelines.mdx b/docs/mini-apps/quality-and-publishing/submission-guidelines.mdx new file mode 100644 index 00000000..cc9cd5ea --- /dev/null +++ b/docs/mini-apps/quality-and-publishing/submission-guidelines.mdx @@ -0,0 +1,8 @@ +--- +title: Submission Guidelines +description: Assets and information required to submit your Mini App for featuring +--- + +TODO: Define required assets (icons, hero, screenshots), URLs, manifest checks, and contact path for submission. + + diff --git a/docs/mini-apps/quickstart/build-a-mini-app/create-manifest.mdx b/docs/mini-apps/quickstart/build-a-mini-app/create-manifest.mdx new file mode 100644 index 00000000..da167a57 --- /dev/null +++ b/docs/mini-apps/quickstart/build-a-mini-app/create-manifest.mdx @@ -0,0 +1,54 @@ +--- +title: Manifest Creation +description: Generate your Farcaster account association and expose the /.well-known/farcaster.json endpoint +--- + +With a stable URL, create and configure your manifest so users can save and discover your Mini App. + +## Generate account association via CLI + +```bash Terminal +npx create-onchain --manifest +``` + + +Use your Farcaster custody wallet to sign. You can import it using your recovery phrase from Farcaster (Settings → Advanced). + + +After signing, the CLI updates local `.env` variables: + +- FARCASTER_HEADER +- FARCASTER_PAYLOAD +- FARCASTER_SIGNATURE + +Update your deployment environment with these values. + + +While testing, set `noindex: true` in your manifest to avoid indexing. + + +## Expose `/.well-known/farcaster.json` + +In Next.js, add a route handler at `app/.well-known/farcaster.json/route.ts` that returns your accountAssociation and frame properties. Ensure all asset URLs are HTTPS and publicly accessible. + + +Open `https://yourdomain.com/.well-known/farcaster.json` in a browser to verify JSON output. + + +## Add frame metadata for embeds + +Define `fc:frame` metadata so your app renders a rich embed with a launch button when shared. + + +All image and API URLs must be publicly accessible via HTTPS. + + + +Implement minimal metadata and validation steps + + + +Why it matters and what "good" looks like + + + diff --git a/docs/mini-apps/quickstart/build-a-mini-app/deploy.mdx b/docs/mini-apps/quickstart/build-a-mini-app/deploy.mdx new file mode 100644 index 00000000..003f5874 --- /dev/null +++ b/docs/mini-apps/quickstart/build-a-mini-app/deploy.mdx @@ -0,0 +1,73 @@ +--- +title: Deploy +description: Get a stable HTTPS URL for testing your Mini App in Farcaster +--- + +To test as a Mini App, you need a live HTTPS URL. + +## Deploy to Vercel (recommended) + + + + +```bash +npm install -g vercel +``` + + + + + +```bash +vercel +``` + + + + +Use `vercel env add` or the dashboard to add: + +- NEXT_PUBLIC_CDP_CLIENT_API_KEY +- NEXT_PUBLIC_URL (deployed app URL) +- NEXT_PUBLIC_IMAGE_URL (optional) +- NEXT_PUBLIC_SPLASH_IMAGE_URL (optional) +- NEXT_PUBLIC_SPLASH_BACKGROUND_COLOR (optional) + + + + +Then verify your URL works in a browser and proceed to manifest creation. + +## Alternative: ngrok (for local testing) + + + + + +The paid plan is recommended. The free approval screen and rotating URLs can break the manifest. + + +1. Start your dev server: + +```bash Terminal +npm run dev +``` + +2. Create a tunnel: + +```bash Terminal +npm install -g ngrok +ngrok http 3000 +``` + +3. Copy the HTTPS URL (e.g. `https://your-tunnel.ngrok.io`) +4. Use that URL during manifest creation + + + + + +Generate account association and set frame metadata + + + diff --git a/docs/mini-apps/quickstart/build-a-mini-app/feature-tour.mdx b/docs/mini-apps/quickstart/build-a-mini-app/feature-tour.mdx new file mode 100644 index 00000000..fb543bc5 --- /dev/null +++ b/docs/mini-apps/quickstart/build-a-mini-app/feature-tour.mdx @@ -0,0 +1,32 @@ +--- +title: Feature Tour +description: What the scaffold includes out of the box and where to extend it +--- + +The template wires up core MiniKit pieces so you can ship v0 fast. + +## Providers and initialization + +- `MiniKitProvider` wraps your app, configures wagmi and react-query, and applies safe area insets. +- `useMiniKit` handles initialization and provides `setFrameReady()`. + +## Buttons and actions + +- Save Frame: uses `useAddFrame()` to let users save your Mini App and returns a `url` and `token` for notifications. +- External links: `useOpenUrl()` opens URLs within or outside a frame context. +- Close: `useClose()` dismisses the frame. + +## Next steps + +Add features based on your goals. Start here: + + + + Value, acceptance criteria, and where to implement + + + Bite‑size guides with copy‑paste snippets + + + + diff --git a/docs/mini-apps/quickstart/build-a-mini-app/install.mdx b/docs/mini-apps/quickstart/build-a-mini-app/install.mdx new file mode 100644 index 00000000..b31b7091 --- /dev/null +++ b/docs/mini-apps/quickstart/build-a-mini-app/install.mdx @@ -0,0 +1,52 @@ +--- +title: Install +description: Scaffold a new MiniKit project, install dependencies, and run it locally +--- + +This guide gets you from zero to a running Mini App using the MiniKit template. + +## Prerequisites + +1. Farcaster account (for testing and manifest signing) +2. Optional: Coinbase Developer Platform account for a Client API key + +## Create your project + + + + +```bash +npx create-onchain --mini +``` + +You’ll be prompted for a CDP Client API key. You can generate one in the Coinbase Developer Platform. + + +These docs are LLM‑friendly—reference llms.txt in your editor to streamline builds and prompts: +https://docs.base.org/base-app/build-with-minikit/llms.txt + + + + + +You’ll configure the manifest after you have a stable URL in the Deploy step. + + + + +```bash Terminal +cd your-project-name +npm install +npm run dev +``` + + + + +Next: Deploy your app to get a live URL for testing in Farcaster. + + +Deploy with Vercel (recommended) or use ngrok for local tunneling + + + diff --git a/docs/mini-apps/quickstart/launch-guide.mdx b/docs/mini-apps/quickstart/launch-guide.mdx new file mode 100644 index 00000000..043eb24f --- /dev/null +++ b/docs/mini-apps/quickstart/launch-guide.mdx @@ -0,0 +1,74 @@ +--- +title: Launch Guide +description: High-level checklist and rationale for what to implement next, with links to bite‑size feature guides +--- + +This guide introduces the key concepts that make Mini Apps succeed. Each section leads with the value, then points you to a focused feature guide. No code here—follow the links to implement. + +## Authentication + +Authenticate when it unlocks value, not before. Fast, optional sign‑in keeps momentum and lets users act the moment onchain interactions are needed. + + + +## Wallets + +Enable onchain actions without getting in the way. Prompt progressively and avoid gates that block exploration. + + + +## Manifest + +Your manifest powers saving, discovery, and rich embeds. A strong manifest includes complete fields, valid assets, and `noindex: true` during testing. + + + +## Embeds & Previews + +Distribution starts in the feed: compelling previews with a clear image and launch button turn impressions into launches. + + + +## Search & Discovery + +Be found across surfaces: set a primary category, share once to trigger indexing, and keep assets valid to appear in search and categories. + + + +## Sharing & Social Graph + +Design for social lift: native share flows and social navigation turn single‑player moments into threads and returns. + + + +## Notifications (coming soon) + +Re‑engage saved users with relevant, rate‑limited notifications at the right moments. + + + +## UX Best Practices + +Build for compact, touch‑first contexts: respect safe areas, keep interfaces concise, and emphasize clear primary actions. + + + + + + +## Performance & load polish + +Perceived speed drives retention: target fast first paint, avoid layout shift, and minimize blocking work. + + + +## Quality Bar Check + +Meet the standard for wide distribution: stable, instrumented, discoverable, shareable, and polished. + + + + + + + diff --git a/docs/mini-apps/quickstart/turn-your-app-into-a-mini-app/add-frame-metadata.mdx b/docs/mini-apps/quickstart/turn-your-app-into-a-mini-app/add-frame-metadata.mdx new file mode 100644 index 00000000..c10d4ef6 --- /dev/null +++ b/docs/mini-apps/quickstart/turn-your-app-into-a-mini-app/add-frame-metadata.mdx @@ -0,0 +1,49 @@ +--- +title: Add Frame Metadata +description: Define fc:frame metadata to render rich embeds with launch buttons +--- + +Add `fc:frame` metadata so shared links render an embed with a launch button. + + +Place the meta tag in `` and ensure all referenced assets use HTTPS. + + +### Next.js (generateMetadata) + +```ts app/layout.tsx +export async function generateMetadata(): Promise { + const URL = process.env.NEXT_PUBLIC_URL as string; + return { + title: process.env.NEXT_PUBLIC_ONCHAINKIT_PROJECT_NAME, + description: 'Generated by `create-onchain --mini`', + other: { + 'fc:frame': JSON.stringify({ + version: 'next', + imageUrl: process.env.NEXT_PUBLIC_APP_HERO_IMAGE, + button: { + title: `Launch ${process.env.NEXT_PUBLIC_ONCHAINKIT_PROJECT_NAME}`, + action: { + type: 'launch_frame', + name: process.env.NEXT_PUBLIC_ONCHAINKIT_PROJECT_NAME, + url: URL, + splashImageUrl: process.env.NEXT_PUBLIC_SPLASH_IMAGE, + splashBackgroundColor: process.env.NEXT_PUBLIC_SPLASH_BACKGROUND_COLOR, + }, + }, + }), + }, + }; +} +``` + + + + Validate configuration and ship + + + Minimal metadata and validation steps + + + + diff --git a/docs/mini-apps/quickstart/turn-your-app-into-a-mini-app/add-minikit.mdx b/docs/mini-apps/quickstart/turn-your-app-into-a-mini-app/add-minikit.mdx new file mode 100644 index 00000000..05fb13c9 --- /dev/null +++ b/docs/mini-apps/quickstart/turn-your-app-into-a-mini-app/add-minikit.mdx @@ -0,0 +1,76 @@ +--- +title: Add MiniKit +description: Wrap your app with MiniKitProvider and initialize the frame +--- + +Add the provider and initialize MiniKit in your main page. + +## Add MiniKitProvider + +Create `providers/MiniKitProvider.tsx` and wrap `app/layout.tsx`. + +```jsx providers/MiniKitProvider.tsx +'use client'; +import { MiniKitProvider } from '@coinbase/onchainkit/minikit'; +import { ReactNode } from 'react'; +import { base } from 'wagmi/chains'; + +export function MiniKitContextProvider({ children }: { children: ReactNode }) { + return ( + + {children} + + ); +} +``` + +Wrap your root layout: + +```jsx app/layout.tsx +import { MiniKitContextProvider } from '@/providers/MiniKitProvider'; + +export default function RootLayout({ children }: { children: React.ReactNode }) { + return ( + + + {children} + + + ); +} +``` + +## Initialize MiniKit in your page + +Use `useMiniKit()` to call `setFrameReady()` when your app is ready. + +```jsx app/page.tsx +'use client'; +import { useEffect } from 'react'; +import { useMiniKit } from '@coinbase/onchainkit/minikit'; + +export default function HomePage() { + const { setFrameReady, isFrameReady } = useMiniKit(); + + useEffect(() => { + if (!isFrameReady) setFrameReady(); + }, [isFrameReady, setFrameReady]); + + return
Your app content goes here
; +} +``` + + +The provider configures wagmi and react‑query and uses the Farcaster connector when available. + + + + + Add required and optional env vars + + + Generate account association and frame metadata + + + + diff --git a/docs/mini-apps/quickstart/turn-your-app-into-a-mini-app/configure-environment.mdx b/docs/mini-apps/quickstart/turn-your-app-into-a-mini-app/configure-environment.mdx new file mode 100644 index 00000000..93b13e66 --- /dev/null +++ b/docs/mini-apps/quickstart/turn-your-app-into-a-mini-app/configure-environment.mdx @@ -0,0 +1,121 @@ +--- +title: Configure Environment +description: Add required and optional environment variables for MiniKit +--- + +Add required variables to your local and deployment environments. + + + +These variables are essential for your MiniKit app to function: + + + The name of your Mini App as it appears to users + + + + The deployed URL of your application (must be HTTPS) + + + + Your Coinbase Developer Platform API key + + + + Generated during manifest creation for account association + + + + Generated during manifest creation for account association + + + + Generated during manifest creation for account association + + + + +These variables enhance your app's appearance and metadata: + + + URL to your app's icon (recommended: 48x48px PNG) + + + + Brief subtitle shown in app listings + + + + Detailed description of your app's functionality + + + + URL to splash screen image shown during app loading + + + + Hex color code for splash screen background (e.g., "#000000") + + + + Primary category for app discovery (e.g., "social", "gaming", "utility") + + + + Hero image URL displayed in cast previews + + + + Short, compelling tagline for your app + + + + Open Graph title for social sharing + + + + Open Graph description for social sharing + + + + Open Graph image URL for social media previews + + + + +### Copy-paste .env example + +```bash +# Required +NEXT_PUBLIC_ONCHAINKIT_PROJECT_NAME=YourAppName +NEXT_PUBLIC_URL=https://your-app.vercel.app +NEXT_PUBLIC_ONCHAINKIT_API_KEY=your_cdp_client_api_key + +# Generated by `npx create-onchain --manifest` +FARCASTER_HEADER=base64_header +FARCASTER_PAYLOAD=base64_payload +FARCASTER_SIGNATURE=hex_signature + +# Optional (appearance and metadata) +NEXT_PUBLIC_APP_ICON=https://your-app.vercel.app/icon.png +NEXT_PUBLIC_APP_SUBTITLE=Short subtitle +NEXT_PUBLIC_APP_DESCRIPTION=Describe what your app does +NEXT_PUBLIC_APP_SPLASH_IMAGE=https://your-app.vercel.app/splash.png +NEXT_PUBLIC_SPLASH_BACKGROUND_COLOR=#000000 +NEXT_PUBLIC_APP_PRIMARY_CATEGORY=social +NEXT_PUBLIC_APP_HERO_IMAGE=https://your-app.vercel.app/og.png +NEXT_PUBLIC_APP_TAGLINE=Play instantly +NEXT_PUBLIC_APP_OG_TITLE=Your App +NEXT_PUBLIC_APP_OG_DESCRIPTION=Fast, fun, social +NEXT_PUBLIC_APP_OG_IMAGE=https://your-app.vercel.app/og.png +``` + + +Ensure all referenced assets are publicly accessible via HTTPS. + + + +Use the CLI to create account association values + + + diff --git a/docs/mini-apps/quickstart/turn-your-app-into-a-mini-app/create-farcaster-json.mdx b/docs/mini-apps/quickstart/turn-your-app-into-a-mini-app/create-farcaster-json.mdx new file mode 100644 index 00000000..48dac8a9 --- /dev/null +++ b/docs/mini-apps/quickstart/turn-your-app-into-a-mini-app/create-farcaster-json.mdx @@ -0,0 +1,56 @@ +--- +title: Create farcaster.json +description: Expose the required /.well-known/farcaster.json endpoint +--- + +Create a Next.js route at `app/.well-known/farcaster.json/route.ts` that returns your accountAssociation and frame metadata. + + +Visit `https://yourdomain.com/.well-known/farcaster.json` to verify JSON output. + + + +Define fc:frame metadata for rich embeds + + +```ts app/.well-known/farcaster.json/route.ts +function withValidProperties(properties: Record) { + return Object.fromEntries( + Object.entries(properties).filter(([_, value]) => (Array.isArray(value) ? value.length > 0 : !!value)) + ); +} + +export async function GET() { + const URL = process.env.NEXT_PUBLIC_URL as string; + return Response.json({ + accountAssociation: { + header: process.env.FARCASTER_HEADER, + payload: process.env.FARCASTER_PAYLOAD, + signature: process.env.FARCASTER_SIGNATURE, + }, + frame: withValidProperties({ + version: '1', + name: process.env.NEXT_PUBLIC_ONCHAINKIT_PROJECT_NAME, + subtitle: process.env.NEXT_PUBLIC_APP_SUBTITLE, + description: process.env.NEXT_PUBLIC_APP_DESCRIPTION, + screenshotUrls: [], + iconUrl: process.env.NEXT_PUBLIC_APP_ICON, + splashImageUrl: process.env.NEXT_PUBLIC_APP_SPLASH_IMAGE, + splashBackgroundColor: process.env.NEXT_PUBLIC_SPLASH_BACKGROUND_COLOR, + homeUrl: URL, + webhookUrl: `${URL}/api/webhook`, + primaryCategory: process.env.NEXT_PUBLIC_APP_PRIMARY_CATEGORY, + tags: [], + heroImageUrl: process.env.NEXT_PUBLIC_APP_HERO_IMAGE, + tagline: process.env.NEXT_PUBLIC_APP_TAGLINE, + ogTitle: process.env.NEXT_PUBLIC_APP_OG_TITLE, + ogDescription: process.env.NEXT_PUBLIC_APP_OG_DESCRIPTION, + ogImageUrl: process.env.NEXT_PUBLIC_APP_OG_IMAGE, + // use only while testing + noindex: true, + }), + }); +} +``` + + diff --git a/docs/mini-apps/quickstart/turn-your-app-into-a-mini-app/install.mdx b/docs/mini-apps/quickstart/turn-your-app-into-a-mini-app/install.mdx new file mode 100644 index 00000000..2ddb9b51 --- /dev/null +++ b/docs/mini-apps/quickstart/turn-your-app-into-a-mini-app/install.mdx @@ -0,0 +1,39 @@ +--- +title: Install +description: Add MiniKit to an existing Next.js app +--- + +Install MiniKit (part of OnchainKit) into your existing Next.js App Router project. + +## Prerequisites + + + +Your project uses the `app/` directory (App Router). + + +Your app is deployed and publicly accessible over HTTPS (e.g., Vercel). + + +You have access to your Farcaster custody wallet for manifest signing. + + +Sign in to Coinbase Developer Platform to get a Client API key. + + + +## Install dependencies + +```bash +npm install @coinbase/onchainkit +``` + + +Verify `@coinbase/onchainkit` appears in your `package.json`. + + + +Wrap your app with MiniKitProvider and initialize the context + + + diff --git a/docs/mini-apps/quickstart/turn-your-app-into-a-mini-app/manifest-cli.mdx b/docs/mini-apps/quickstart/turn-your-app-into-a-mini-app/manifest-cli.mdx new file mode 100644 index 00000000..101f2f78 --- /dev/null +++ b/docs/mini-apps/quickstart/turn-your-app-into-a-mini-app/manifest-cli.mdx @@ -0,0 +1,24 @@ +--- +title: Manifest (CLI) +description: Generate account association credentials with the CLI +--- + +Generate your Farcaster account association credentials. + +```bash Terminal +npx create-onchain --manifest +``` + +Follow the prompts to connect your Farcaster custody wallet, add your deployed URL, and sign. The CLI writes `FARCASTER_HEADER`, `FARCASTER_PAYLOAD`, and `FARCASTER_SIGNATURE` to your `.env`. + +Update the same variables in your deployment platform. + + +While testing, set `noindex: true` in your manifest to avoid indexing. + + + +Serve the /.well-known/farcaster.json endpoint + + + diff --git a/docs/mini-apps/quickstart/turn-your-app-into-a-mini-app/test-and-deploy.mdx b/docs/mini-apps/quickstart/turn-your-app-into-a-mini-app/test-and-deploy.mdx new file mode 100644 index 00000000..d411d310 --- /dev/null +++ b/docs/mini-apps/quickstart/turn-your-app-into-a-mini-app/test-and-deploy.mdx @@ -0,0 +1,35 @@ +--- +title: Test & Deploy +description: Validate your manifest and embed configuration, then share +--- + +Before sharing your Mini App, validate everything works. + +## Pre‑deployment checklist + +- App is deployed at a public HTTPS domain +- Environment variables are set on your deployment platform +- `/.well-known/farcaster.json` returns valid JSON +- `fc:frame` metadata renders a launch button when shared + +## Validation tools + +- Manifest Tool: `https://farcaster.xyz/~/developers/mini-apps/manifest` +- Embed Tool: `https://farcaster.xyz/~/developers/mini-apps/embed` + +## Share and test + +1. Create a cast with your app’s URL +2. Verify preview and launch button +3. Test launch and frame readiness + + + + What to implement next for a best‑in‑class v0 + + + Common problems and fixes + + + + diff --git a/docs/mini-apps/technical-reference/minikit/hooks/useAddFrame.mdx b/docs/mini-apps/technical-reference/minikit/hooks/useAddFrame.mdx new file mode 100644 index 00000000..821f763a --- /dev/null +++ b/docs/mini-apps/technical-reference/minikit/hooks/useAddFrame.mdx @@ -0,0 +1,8 @@ +--- +title: Hook — useAddFrame +description: Let users save your Mini App and return notification credentials +--- + +TODO: Document usage, return shape (url, token), and persistence guidance. + + diff --git a/docs/mini-apps/technical-reference/minikit/hooks/useAuthenticate.mdx b/docs/mini-apps/technical-reference/minikit/hooks/useAuthenticate.mdx new file mode 100644 index 00000000..951bf5be --- /dev/null +++ b/docs/mini-apps/technical-reference/minikit/hooks/useAuthenticate.mdx @@ -0,0 +1,8 @@ +--- +title: Hook — useAuthenticate +description: Implement Farcaster sign‑in and verification flows +--- + +TODO: Document input params (domain, siweUri), return value, and example flows. + + diff --git a/docs/mini-apps/technical-reference/minikit/hooks/useClose.mdx b/docs/mini-apps/technical-reference/minikit/hooks/useClose.mdx new file mode 100644 index 00000000..0d1017d5 --- /dev/null +++ b/docs/mini-apps/technical-reference/minikit/hooks/useClose.mdx @@ -0,0 +1,8 @@ +--- +title: Hook — useClose +description: Programmatically close the Mini App frame +--- + +TODO: Document usage and gestures/ready options interactions. + + diff --git a/docs/mini-apps/technical-reference/minikit/hooks/useComposeCast.mdx b/docs/mini-apps/technical-reference/minikit/hooks/useComposeCast.mdx new file mode 100644 index 00000000..edb84ce8 --- /dev/null +++ b/docs/mini-apps/technical-reference/minikit/hooks/useComposeCast.mdx @@ -0,0 +1,8 @@ +--- +title: Hook — useComposeCast +description: Open the composer with prefilled text and embeds +--- + +TODO: Document params (text, embeds[]) and behavior. + + diff --git a/docs/mini-apps/technical-reference/minikit/hooks/useMiniKit.mdx b/docs/mini-apps/technical-reference/minikit/hooks/useMiniKit.mdx new file mode 100644 index 00000000..79bb2d4e --- /dev/null +++ b/docs/mini-apps/technical-reference/minikit/hooks/useMiniKit.mdx @@ -0,0 +1,8 @@ +--- +title: Hook — useMiniKit +description: Access frame context and control readiness +--- + +TODO: Document return values (context, isReady), `setFrameReady()`, and examples. + + diff --git a/docs/mini-apps/technical-reference/minikit/hooks/useNotification.mdx b/docs/mini-apps/technical-reference/minikit/hooks/useNotification.mdx new file mode 100644 index 00000000..d3db5fe5 --- /dev/null +++ b/docs/mini-apps/technical-reference/minikit/hooks/useNotification.mdx @@ -0,0 +1,8 @@ +--- +title: Hook — useNotification +description: Send notifications via a backend proxy to users who saved your Mini App +--- + +TODO: Document required proxy route, payload, rate limiting, and examples. + + diff --git a/docs/mini-apps/technical-reference/minikit/hooks/useOpenUrl.mdx b/docs/mini-apps/technical-reference/minikit/hooks/useOpenUrl.mdx new file mode 100644 index 00000000..f3e68bfe --- /dev/null +++ b/docs/mini-apps/technical-reference/minikit/hooks/useOpenUrl.mdx @@ -0,0 +1,8 @@ +--- +title: Hook — useOpenUrl +description: Open external links from within or outside a frame context +--- + +TODO: Document behavior inside/outside frame and example usage. + + diff --git a/docs/mini-apps/technical-reference/minikit/hooks/usePrimaryButton.mdx b/docs/mini-apps/technical-reference/minikit/hooks/usePrimaryButton.mdx new file mode 100644 index 00000000..cfeee1a6 --- /dev/null +++ b/docs/mini-apps/technical-reference/minikit/hooks/usePrimaryButton.mdx @@ -0,0 +1,8 @@ +--- +title: Hook — usePrimaryButton +description: Configure and handle the persistent primary button +--- + +TODO: Document options, handler signature, and layout considerations. + + diff --git a/docs/mini-apps/technical-reference/minikit/hooks/useViewCast.mdx b/docs/mini-apps/technical-reference/minikit/hooks/useViewCast.mdx new file mode 100644 index 00000000..731ce3c3 --- /dev/null +++ b/docs/mini-apps/technical-reference/minikit/hooks/useViewCast.mdx @@ -0,0 +1,8 @@ +--- +title: Hook — useViewCast +description: View a cast by its hash from your Mini App +--- + +TODO: Document param (hash) and usage examples. + + diff --git a/docs/mini-apps/technical-reference/minikit/hooks/useViewProfile.mdx b/docs/mini-apps/technical-reference/minikit/hooks/useViewProfile.mdx new file mode 100644 index 00000000..353a1536 --- /dev/null +++ b/docs/mini-apps/technical-reference/minikit/hooks/useViewProfile.mdx @@ -0,0 +1,8 @@ +--- +title: Hook — useViewProfile +description: Navigate to Farcaster profiles from your Mini App +--- + +TODO: Document defaulting to client FID and passing a specific FID. + + diff --git a/docs/mini-apps/technical-reference/minikit/provider-and-initialization.mdx b/docs/mini-apps/technical-reference/minikit/provider-and-initialization.mdx new file mode 100644 index 00000000..a6ddcf70 --- /dev/null +++ b/docs/mini-apps/technical-reference/minikit/provider-and-initialization.mdx @@ -0,0 +1,8 @@ +--- +title: MiniKit — Provider & Initialization +description: Configure MiniKitProvider and initialize frame context +--- + +TODO: Consolidate provider props, safe area behavior, wagmi/react‑query setup, and `useMiniKit` initialization details. + + diff --git a/docs/mini-apps/troubleshooting/base-app-compatibility.mdx b/docs/mini-apps/troubleshooting/base-app-compatibility.mdx new file mode 100644 index 00000000..7da325b6 --- /dev/null +++ b/docs/mini-apps/troubleshooting/base-app-compatibility.mdx @@ -0,0 +1,40 @@ +--- +title: Base App Compatibility +description: Which Mini App features are supported in Base App (TBA) today +--- + +Base App is working towards full compatibility with the Farcaster Mini App SDK. During beta, some features are not yet supported. + +## Currently Unsupported (examples) + +- Environment detection: `sdk.isInMiniApp()` (ETA 8/6) +- Haptic feedback methods: `sdk.haptics.*` (ETA 8/13) +- Token actions: `sdk.actions.swapToken()` (ETA 8/6) +- Notifications: not yet supported +- Mini App actions: `.addMiniApp()`, `.requestCameraAndMicrophoneAccess()` (ETA 8/13) + +## Wallet Interactions + +- `sdk.actions.getEthereumProvider()` — Base App exposes an EIP‑1193 provider; use MiniKit/Wagmi or window provider detection. + +## Navigation & Links + +- Avoid direct Farcaster/warpcast intent URLs; use SDK actions like `composeCast()` +- For external links, prefer `openUrl()` over raw anchors + +## Supported Chains + +Base, Mainnet, Optimism, Arbitrum, Polygon, Zora, BNB, Avalanche C‑Chain + +## Development Notes + +- Use `openUrl()` for external navigation +- Use `composeCast()` instead of composer URLs +- Provide alternatives for haptic feedback +- Avoid relying on location context for core flows +- To detect Base App, check `context.client.clientFid` (Base App: `309857`) + +We are actively expanding compatibility and will update this page as support increases. + + + diff --git a/docs/mini-apps/troubleshooting/common-issues.mdx b/docs/mini-apps/troubleshooting/common-issues.mdx new file mode 100644 index 00000000..1b57d555 --- /dev/null +++ b/docs/mini-apps/troubleshooting/common-issues.mdx @@ -0,0 +1,118 @@ +--- +title: Common Issues & Debugging +description: Frequent issues encountered during Mini App development and their solutions +--- + +## Prerequisites & Setup Verification + +Ensure your Mini App has the foundational requirements in place. + +### Required Files and Structure + +```html +your-domain.com/ +├── .well-known/ +│ └── farcaster.json # Required manifest file +├── your-app/ +│ ├── index.html # Your app entry point +│ └── ... # Your app files +``` + +### Environment Setup Checklist + +- Domain is accessible via HTTPS +- Manifest file exists at `/.well-known/farcaster.json` +- All image URLs are publicly accessible + +### Basic Validation Steps + +1. Test manifest accessibility: visit `https://yourdomain.com/.well-known/farcaster.json` +2. Validate JSON syntax with JSONLint +3. Ensure your app loads without console errors + +## Quick Diagnostic Workflow + +- Not appearing in search? → App Discovery & Indexing Issues +- Not rendering as an embed? → Embed Rendering Issues +- Wallet connection problems? → Wallet Connection Problems +- Need mobile testing tools? → Mobile Testing & Debugging +- Changes not appearing? → Manifest Configuration Problems +- App closes on gestures? → Gesture Conflicts and App Dismissal Issues + +## Detailed Problem Solutions + +### 1. App Discovery & Indexing Issues + +Problem: Your Mini App doesn't appear in search results or app catalogs. + +Root cause: Missing or incomplete manifest configuration. + +Solution: Ensure your manifest includes all required fields (see Manifest feature guide). + +Critical requirements: + +- `primaryCategory` is required for searchability and category pages +- `accountAssociation` is required for verification + +App Indexing Requirements: + +1. Complete your manifest setup +2. Share your Mini App URL in a post +3. Indexing can take up to 10 minutes +4. Verify appearance in app catalogs + +Caching Issues — Changes Not Appearing: + +Farcaster clients may cache manifest data for up to 24 hours. Re‑share to trigger a refresh and allow ~10 minutes. + +### 2. Manifest Configuration Problems + +Image Display Issues: + +1. Test image accessibility in incognito +2. Verify image format (PNG, JPG, WebP supported) +3. Check dimensions +4. Ensure HTTPS URLs only + +### 3. Embed Rendering Issues + +Problem: Your Mini App URL doesn't render as a rich embed when shared. + +Root cause: Incorrect or missing `fc:frame` metadata. + +Solution: Use `name="fc:frame"` meta tag in `` and validate using the Embed Tool. + +### 4. Wallet Connection Problems + +Prefer MiniKit with OnchainKit Wallet or Wagmi hooks. MiniKit includes wagmi providers; avoid double configuration. + +### 5. Gesture Conflicts and App Dismissal Issues + +Disable native gestures when calling ready if you use swipe/drag interactions: + +```ts +await sdk.actions.ready({ disableNativeGestures: true }); +``` + +### 6. Mobile Testing & Debugging + +Use Eruda for mobile debugging; remove before production deployment. + +## Advanced Troubleshooting + +AI‑Assisted Debugging: Use the CBW MiniApp Validator prompt to scan for unsupported patterns. + +## Success Verification + +Basic functionality and discovery/sharing checklists: confirm load, images, wallet, manifest endpoint, embed rendering, and search presence. + +## Getting Additional Help + +- Mini App Debug Tool +- Mini App Embed Tool +- JSONLint +- Eruda +- Base Discord — #minikit channel + + + diff --git a/docs/mini-apps/troubleshooting/error-handling.mdx b/docs/mini-apps/troubleshooting/error-handling.mdx new file mode 100644 index 00000000..afe0e450 --- /dev/null +++ b/docs/mini-apps/troubleshooting/error-handling.mdx @@ -0,0 +1,8 @@ +--- +title: Error Handling +description: Patterns for surfacing and resolving common runtime errors in Mini Apps +--- + +TODO: Provide guidance on handling errors from hooks, network issues, and manifest/metadata failures. + +