🚀 Arlink Farcaster Mini App Starter

A production-ready starter template for building Farcaster Mini Apps with multi-chain wallet support (Ethereum & Solana). Deploy in seconds with Arlink's one-click deployment.

✨ Features

🎯 Farcaster SDK Integration - Native mini app support with proper metadata configuration
🔗 Multi-Chain Wallet Support - Connect to both Ethereum (Base) and Solana wallets
💚 Modern UI/UX - Beautiful, responsive design with Tailwind CSS
⚡ Lightning Fast - Built with Vite and React 18
🎨 Type-Safe - Full TypeScript support
🌐 One-Click Deploy - Deploy to permanent decentralized storage with Arlink

📁 Project Structure

miniapp/
├── src/
│   ├── components/
│   │   ├── Loader.tsx          # Loading screen component
│   │   └── WalletConnect.tsx   # Multi-chain wallet connection UI
│   ├── lib/
│   │   └── utils.ts            # Utility functions (clsx, cn helpers)
│   ├── styles/
│   │   └── globals.css         # Global styles and Tailwind imports
│   ├── App.tsx                 # Main application component
│   ├── main.tsx                # App entry point with providers
│   └── vite-env.d.ts           # Vite type definitions
├── public/                     # Static assets
│   ├── Arlink.svg             # App logo
│   └── 404.html               # SPA routing fallback
├── index.html                  # HTML entry point with Farcaster meta tags
├── package.json               # Dependencies and scripts
├── tailwind.config.js         # Tailwind CSS configuration
├── tsconfig.json              # TypeScript configuration
└── vite.config.ts             # Vite build configuration

Key Files

src/main.tsx - Sets up wallet providers (Wagmi for Ethereum, Solana Wallet Adapter)
src/App.tsx - Main app logic with connection state management
src/components/WalletConnect.tsx - Handles multi-chain wallet connections
index.html - Contains Farcaster Mini App metadata and SDK initialization

🔌 Farcaster SDK Integration

The Farcaster Mini App SDK is integrated in two key places:

1. Meta Tags Configuration (`index.html`)

The mini app is configured using Farcaster-specific meta tags:

<!-- Farcaster Mini App Meta Tags -->
<meta name="fc:miniapp" content='{
  "version":"1",
  "imageUrl":"YOUR_IMAGE_URL",
  "button":{
    "title":"Launch App",
    "action":{
      "type":"launch_miniapp",
      "name":"Your App Name",
      "url":"YOUR_DEPLOYED_URL",
      "splashImageUrl":"YOUR_SPLASH_IMAGE_URL",
      "splashBackgroundColor":"#064e3b"
    }
  }
}' />

2. SDK Initialization (`index.html`)

The SDK is loaded dynamically from ESM CDN:

(async () => {
  try {
    const { sdk } = await import("https://esm.sh/@farcaster/miniapp-sdk");
    await sdk.actions.ready();
    console.log("✅ Farcaster Mini App SDK initialized");
  } catch (error) {
    console.error("❌ Failed to initialize Farcaster Mini App SDK:", error);
  }
})();

This approach ensures the SDK initializes without blocking your app's bundle.

🌐 Wallet Integrations

Ethereum Wallet (Base Network)

Technology Stack:

Wagmi v2 - React hooks for Ethereum
Viem - TypeScript Ethereum library
@farcaster/miniapp-wagmi-connector - Farcaster-specific connector

Configuration (src/main.tsx):

import { WagmiProvider, createConfig, http } from 'wagmi';
import { base } from 'wagmi/chains';
import { farcasterMiniApp as miniAppConnector } from '@farcaster/miniapp-wagmi-connector';

const config = createConfig({
  chains: [base],
  transports: {
    [base.id]: http(),
  },
  connectors: [miniAppConnector()],
});

Usage (src/App.tsx):

import { useAccount } from 'wagmi';

const { isConnected, address } = useAccount();

Solana Wallet

Technology Stack:

@solana/wallet-adapter-react - React hooks for Solana
@farcaster/mini-app-solana - Farcaster Solana integration

Configuration (src/main.tsx):

import { FarcasterSolanaProvider } from '@farcaster/mini-app-solana';

const solanaEndpoint = 'https://api.mainnet-beta.solana.com';

<FarcasterSolanaProvider endpoint={solanaEndpoint}>
  <App />
</FarcasterSolanaProvider>

Usage (src/components/WalletConnect.tsx):

import { useWallet } from '@solana/wallet-adapter-react';

const { publicKey, connect, disconnect, wallets, select } = useWallet();

The Solana integration automatically detects the Farcaster wallet adapter and connects to it.

🚀 Getting Started

Prerequisites

Node.js 16+
pnpm (or npm/yarn)

Installation

# Clone the repository
git clone <your-repo-url>
cd miniapp

# Install dependencies
pnpm install

# Start development server
pnpm dev

The app will open at http://localhost:5173

Build for Production

pnpm build

The production build will be in the dist/ directory.

✅ To-Do: Customize Your Mini App

Before deploying your mini app, complete these steps:

1. Configure Meta Tags (`index.html`)

IMPORTANT: Edit these meta tags with your deployed URLs:

<!-- Line 14: Update fc:miniapp meta tag -->
<meta name="fc:miniapp" content='{
  "version":"1",
  "imageUrl":"YOUR_OG_IMAGE_URL",           <!-- ⚠️ Change this -->
  "button":{
    "title":"Launch App",
    "action":{
      "type":"launch_miniapp",
      "name":"Your App Name",                <!-- ⚠️ Change this -->
      "url":"YOUR_DEPLOYED_URL",             <!-- ⚠️ Change this -->
      "splashImageUrl":"YOUR_SPLASH_IMAGE",  <!-- ⚠️ Change this -->
      "splashBackgroundColor":"#064e3b"      <!-- ⚠️ Change this -->
    }
  }
}' />

<!-- Lines 20-29: Update Open Graph and Twitter meta tags -->
<meta property="og:title" content="Your App Name" />
<meta property="og:description" content="Your app description" />
<meta property="og:image" content="YOUR_OG_IMAGE_URL" />     <!-- ⚠️ Change this -->
<meta name="twitter:image" content="YOUR_OG_IMAGE_URL" />    <!-- ⚠️ Change this -->

Image URLs: Use permanent URLs (like ARWeave links from Arlink deployment) for all images.

📢 Publishing Your Mini App

You have two options to publish your Farcaster Mini App:

Option 1: Using farcaster.json (Recommended)

edit the farcaster.json file in your repository root :

{
  "accountAssociation": {
    "header": "your-header-value",
    "signature": "your-signature",
    "payload": "your-payload"
  },
  "miniApp": {
    "version": "1",
    "name": "Your App Name",
    "url": "https://your-deployed-url.com",
    "imageUrl": "https://your-image-url.com/preview.png",
    "splashImageUrl": "https://your-image-url.com/splash.png",
    "splashBackgroundColor": "#064e3b"
  }
}

Host this file at https://your-domain.com/.well-known/farcaster.json

Option 2: Direct Registration on Farcaster

Register your mini app directly through the Farcaster developer portal:

🔗 Register Mini App on Farcaster

You'll need to provide:

App name
Deployed URL
Preview image URL
Splash screen image URL
Splash background color

🌟 Deploy with Arlink

Deploy your mini app to permanent, decentralized storage in one click with Arlink:

Why Arlink?

✅ One-Click Deploy - Connect your GitHub repo and deploy
✅ Permanent Storage - Stored on Arweave forever
✅ Auto-Updates - Automatically redeploys when you push to main

Steps to Deploy:

Push your code to a GitHub repository
Visit arlink.ar.io/dashboard
Connect your GitHub account
Select your mini app repository
Click "Deploy Now"
Copy your Arlink URL and update the meta tags in index.html

Pro Tip: Arlink automatically redeploys when you push to main, so your mini app stays updated!

📚 Resources

🛠️ Tech Stack

Framework: React 18 + TypeScript
Build Tool: Vite
Styling: Tailwind CSS
Ethereum: Wagmi v2 + Viem
Solana: Wallet Adapter + Farcaster Integration
State Management: TanStack Query (React Query)
Farcaster SDK: @farcaster/miniapp-sdk

🐛 Troubleshooting

Wallet Not Connecting

Ensure you're testing within the Farcaster client (mini apps don't work in regular browsers)
Check browser console for error messages
Verify the Farcaster SDK initialized successfully

Meta Tags Not Working

Ensure JSON in meta tags is properly escaped (no line breaks)
Use online JSON validators to check syntax
Clear Farcaster cache and reload

Build Errors

# Clear cache and reinstall
rm -rf node_modules pnpm-lock.yaml
pnpm install
pnpm build

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Contributing

Contributions are welcome! Feel free to open issues or submit pull requests.

**Built with ❤️ by Arlink

Ready to launch your mini app? Deploy Now with Arlink →

Name		Name	Last commit message	Last commit date
Latest commit History 8 Commits
public		public
src		src
.eslintrc.cjs		.eslintrc.cjs
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
index.html		index.html
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
postcss.config.js		postcss.config.js
tailwind.config.js		tailwind.config.js
tsconfig.json		tsconfig.json
tsconfig.node.json		tsconfig.node.json
vite.config.ts		vite.config.ts

Folders and files

Latest commit

History

Repository files navigation

🚀 Arlink Farcaster Mini App Starter

✨ Features

📁 Project Structure

Key Files

🔌 Farcaster SDK Integration

1. Meta Tags Configuration (index.html)

2. SDK Initialization (index.html)

🌐 Wallet Integrations

Ethereum Wallet (Base Network)

Solana Wallet

🚀 Getting Started

Prerequisites

Installation

Build for Production

✅ To-Do: Customize Your Mini App

1. Configure Meta Tags (index.html)

📢 Publishing Your Mini App

Option 1: Using farcaster.json (Recommended)

Option 2: Direct Registration on Farcaster

🌟 Deploy with Arlink

Why Arlink?

Steps to Deploy:

📚 Resources

🛠️ Tech Stack

🐛 Troubleshooting

Wallet Not Connecting

Meta Tags Not Working

Build Errors

📝 License

🤝 Contributing

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

1. Meta Tags Configuration (`index.html`)

2. SDK Initialization (`index.html`)

1. Configure Meta Tags (`index.html`)

Packages