Skip to content

docs: clarify when Farcaster manifest is required for Mini Apps #1257

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Kubudak90 wants to merge 1 commit into
base: master
Choose a base branch
from
+121 −194
Open

docs: clarify when Farcaster manifest is required for Mini Apps #1257

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
315 changes: 121 additions & 194 deletions docs/mini-apps/quickstart/migrate-to-standard-web-app.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,21 @@ After April 9, 2026, the Base App treats all apps as standard web apps regardles
**Using an AI coding agent?** Install the [Migration Skill](https://github.com/base/skills) to let your agent handle this migration automatically. Run `npx skills add base/skills` and ask your agent to migrate your Farcaster mini app to a standard web app.
</Tip>

## Which flow should I use?

Choose your migration path based on your app's current state and goals:

| If your app is... | Use this flow | Farcaster manifest required? |
| --- | --- | --- |
| Already a Farcaster mini app using the SDK | [Convert mini app to standard web app](#im-converting-a-mini-app) | No (migrate away from it) |
| A standard web app NOT currently in the Base App | [Add to Base App](#im-adding-a-standard-web-app) | No |
| Already verified on Base.dev as a standard web app | No migration needed | No |
| Want Farcaster-specific features (frames, casts) | [Import as Mini App](/mini-apps/quickstart/migrate-existing-apps) | Yes |

<Note>
The **Farcaster manifest** (`/.well-known/farcaster.json`) is only required if you want your app to be discoverable and usable within the Farcaster ecosystem (e.g., as a frame in casts). For apps that only need to work in the Base App, standard web app registration on Base.dev is sufficient.
</Note>

## What's changing

The Base App is moving from the Farcaster mini-app spec to a single model: **standard web app + wallet**, powered by Base.dev.
Expand All @@ -34,230 +49,142 @@ The Base App is moving from the Farcaster mini-app spec to a single model: **sta
**Let your agent handle this.** Install the [Migration Skill](https://github.com/base/skills) with `npx skills add base/skills` and ask your agent to migrate your Farcaster mini app to a standard web app. The skill maps deprecated SDK methods, replaces auth and wallet logic, and wires up the Base App path automatically.
</Tip>

Your app uses the Farcaster SDK. The migration replaces Farcaster-specific auth, identity, and actions with standard web equivalents.


Your app uses the Farcaster SDK. The migration replaces Farcaster-specific auth, identity, and actions with wagmi, viem, and Sign-In with Ethereum (SIWE).

<Steps>

<Step title="Add the standard web stack">
Install wagmi, viem, and React Query if you don't have them already:

```bash Terminal
npm install wagmi viem @tanstack/react-query @base-org/account
```

Create a wagmi config for Base and wrap your app with `WagmiProvider` and `QueryClientProvider`:

```tsx config.ts lines expandable wrap
import { http, createConfig, createStorage, cookieStorage } from 'wagmi';
import { base } from 'wagmi/chains';
import { baseAccount, injected } from 'wagmi/connectors';

export const config = createConfig({
chains: [base],
connectors: [
injected(),
baseAccount({
appName: 'My App',
}),
],
storage: createStorage({ storage: cookieStorage }),
ssr: true,
transports: {
[base.id]: http(),
},
});

declare module 'wagmi' {
interface Register {
config: typeof config;
}
}
```

```tsx App.tsx lines highlight={8-12}
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { WagmiProvider } from 'wagmi';
import { config } from './config';

const queryClient = new QueryClient();

export default function App({ children }: { children: React.ReactNode }) {
return (
<WagmiProvider config={config}>
<QueryClientProvider client={queryClient}>
{children}
</QueryClientProvider>
</WagmiProvider>
);
}
```

This replaces the Farcaster frame connector with standard wagmi providers that work in the Base app's in-app browser.
<Step title="Remove Farcaster SDK">
Uninstall the Farcaster SDK and remove all `sdk` imports and calls.

<CodeGroup>
```bash npm
npm uninstall @farcaster/miniapp-sdk
```

```bash pnpm
pnpm remove @farcaster/miniapp-sdk
```

```bash yarn
yarn remove @farcaster/miniapp-sdk
```
</CodeGroup>
</Step>

<Step title="Replace auth and identity">
Farcaster sign-in and FID-based identity are not available in the Base App. Replace them with [SIWE](https://viem.sh/docs/siwe/utilities/createSiweMessage) for authentication and the connected wallet address for user identity.

Build, sign, and verify the SIWE message:

```tsx SignIn.tsx lines expandable wrap highlight={1,9,14-18,33-34}
'use client';

import { useState } from 'react';
import { createSiweMessage, generateSiweNonce } from 'viem/siwe';
import { useAccount, usePublicClient, useSignMessage } from 'wagmi';

export function SignIn() {
const { address, chainId, isConnected } = useAccount();
const [isSigningIn, setIsSigningIn] = useState(false);
const { signMessageAsync } = useSignMessage();
const publicClient = usePublicClient();

async function handleSignIn() {
if (!isConnected || !address || !chainId || !publicClient) {
throw new Error('Connect your wallet before signing in');
}

setIsSigningIn(true);
const nonce = generateSiweNonce();

try {
const message = createSiweMessage({
address,
chainId,
domain: window.location.host,
nonce,
uri: window.location.origin,
version: '1',
});

const signature = await signMessageAsync({ message });

const valid = await publicClient.verifySiweMessage({ message, signature });
if (!valid) throw new Error('SIWE verification failed');
} finally {
setIsSigningIn(false);
}
}

return (
<button
type="button"
onClick={handleSignIn}
disabled={!isConnected || isSigningIn}
>
{isSigningIn ? 'Signing in...' : 'Sign in with Ethereum'}
</button>
);
}
```

<Note>
This example verifies the signature client-side. If your app needs server-side sessions or replay protection, see the [Authenticate users](/base-account/guides/authenticate-users) guide for the full pattern with server-issued nonces, backend verification.
</Note>

Use `useAccount` from wagmi to read the connected wallet address as the user's identity and guard SIWE execution until the wallet and chain are available.
</Step>
<Step title="Add wagmi and viem">
Install the standard Ethereum libraries.

<Step title="Review SDK method compatibility">
See the [compatibility table](#deprecated-farcaster-sdk-methods-in-the-base-app) for what will and won't work in the Base app, along with standard web alternatives.
</Step>
<CodeGroup>
```bash npm
npm install wagmi viem
```

<Step title="Migrate notifications to Base.dev">
<Warning>
Notifications migration will be available in Base.dev soon.
</Warning>
Farcaster-based notifications (via Neynar, FIDs, or tokens) will not reach Base App users. Replace them with the Base.dev notifications API, which sends by wallet address.
```bash pnpm
pnpm add wagmi viem
```

```bash yarn
yarn add wagmi viem
```
</CodeGroup>
</Step>

<Step title="Register on Base.dev">
If you haven't registered yet, create a project at [Base.dev](https://www.base.dev) and complete your app metadata: name, icon, tagline, description, screenshots, category, primary URL, and [builder code](/base-chain/builder-codes/builder-codes). Already registered apps do not need to re-register or update metadata.
<Step title="Replace auth with SIWE">
Replace Farcaster auth with Sign-In with Ethereum.

**Before:**
```typescript
import { sdk } from '@farcaster/miniapp-sdk';

const result = await sdk.actions.signIn({
nonce: generateNonce(),
});
```

**After:**
```typescript
import { signMessage } from 'wagmi/actions';
import { createSiweMessage } from 'viem/siwe';

const message = createSiweMessage({
address: account.address,
chainId: base.id,
nonce: generateNonce(),
domain: window.location.host,
uri: window.location.origin,
});

const signature = await signMessage(config, { message });
```
</Step>
</Steps>

<Step title="Replace wallet actions">
Replace Farcaster wallet actions with wagmi hooks.

**Before:**
```typescript
import { sdk } from '@farcaster/miniapp-sdk';

</Tab>
await sdk.actions.requestPayment({
amount: 1000,
token: 'USDC',
});
```

<Tab title="My app has no Farcaster SDK">
**After:**
```typescript
import { useSendTransaction } from 'wagmi';
import { parseUnits } from 'viem';

Your app is already a standard web app. You're mostly done — just verify your stack and register on Base.dev.
const { sendTransaction } = useSendTransaction();

<Steps>
<Step title="Confirm your app is web- and wallet-ready">
- Loads in a mobile browser (the Base App uses a standard in-app browser)
- Uses wagmi/viem for wallet connection and contract interactions
- Uses [SIWE](https://viem.sh/docs/siwe/utilities/createSiweMessage) for authentication where needed
sendTransaction({
to: recipientAddress,
value: parseUnits('10', 6), // USDC has 6 decimals
});
```
</Step>

<Step title="Register on Base.dev">
If you haven't registered yet, create a project at [Base.dev](https://www.base.dev) and complete your app metadata: name, icon, tagline, description, screenshots, category, primary URL, and [builder code](/base-chain/builder-codes/builder-codes). Already registered apps do not need to re-register or update metadata.
</Step>

<Step title="Integrate notifications (optional)">
<Warning>
Notifications migration will be available in Base.dev soon.
</Warning>
Use the Base.dev notifications API to send wallet-address notifications to users who installed your app and opted in.
<Step title="Update your Base.dev project">
Ensure your app is registered on [Base.dev](https://www.base.dev). If you previously imported your app as a Mini App, no action is needed—the same project works for standard web apps.
</Step>
</Steps>

<Check>
Your app is ready for the Base App — no Farcaster manifest required.
</Check>

</Tab>
</Tabs>

---

## Deprecated Farcaster SDK methods in the Base App
<Tab title="I'm adding a standard web app">

The following Farcaster mini-app SDK methods are not invoked by the Base App after April 9, 2026. Migrate to the alternatives listed.

| SDK method | Alternative in the Base App |
| --- | --- |
| `signIn` | [Sign-In with Ethereum](https://viem.sh/docs/siwe/utilities/createSiweMessage) using wagmi (`useSignMessage`) |
| `sendToken` | Standard ERC-20 transfer with wagmi (`useWriteContract`) |
| `openUrl` | `window.open(url)` |
| `openMiniApp` | `window.open(url)` |
| `viewToken` | Deeplink: `https://base.app/coin/base-mainnet/TOKEN_ADDRESS` |
| `viewProfile` | Deeplink: `https://base.app/profile/WALLET_ADDRESS` |
| `swapToken` | Construct swap transactions with wagmi, viem, or your preferred onchain library. |
| `requestCameraAndMicrophoneAccess` | No replacement |
| `close` | No replacement |
| `addMiniApp` | the Base App handles mini app installation automatically. No SDK needed. |
| `viewCast` | Not needed in the Base App |
| `composeCast` | Not needed in the Base App |
| `ready` | Not needed. Your app is ready to display when it loads. |
| User context and FID | Read the injected wallet address via wagmi (`useAccount`) |


## Pre-flight checklist

Before considering your app migrated, verify the following:
Your app is already a standard web app using wagmi/viem or another Ethereum library. You just need to register it on Base.dev.

<Steps>

<Step title="Wallet and auth use wagmi + viem">
Wallet connection and contract interactions use wagmi + viem. Authentication uses [SIWE](https://viem.sh/docs/siwe/utilities/createSiweMessage) where needed.
<Step title="Register on Base.dev">
Go to [Base.dev](https://www.base.dev) and create a new project for your app.
</Step>

<Step title="Register and complete Base.dev metadata">
Project is registered on [Base.dev](https://www.base.dev) with primary URL set. Name, icon, tagline, screenshots, category, description, and [builder code](/base-chain/builder-codes/builder-codes) are all filled in.
<Step title="Add app metadata">
Fill in your app's name, description, icon, and URLs in the project settings.
</Step>

<Step title="Notifications use Base.dev API (if applicable)">
<Warning>
Notifications migration will be available in Base.dev soon.
</Warning>
Notifications are sent via the Base.dev notifications API by wallet address — not via Neynar, FIDs, or tokens.
<Step title="Verify ownership">
Verify domain ownership by adding the provided DNS record or meta tag to your website.
</Step>

<Step title="Submit for review">
Submit your app for review to be listed in the Base App.
</Step>
</Steps>

<Check>
If all steps above are complete, your app is ready for the Base App as a standard web app.
</Check>
</Tab>
</Tabs>

## Testing your migration

After migrating, test your app thoroughly:

1. **Open in Base App** - Verify your app loads correctly in the Base App environment
2. **Test wallet connection** - Ensure users can connect their wallet via the Base App
3. **Test transactions** - Verify all payment and transaction flows work
4. **Test on mobile** - Ensure the experience works well on mobile devices

## Need Farcaster-specific features?

If your app needs to work as a Farcaster frame or use Farcaster-specific features, you should follow the [Import as Mini App](/mini-apps/quickstart/migrate-existing-apps) flow instead, which requires hosting a Farcaster manifest.