base / base/docs

[Docs] Mini App wallet provider migration guide needed: Base App in-app browser (post-April 2026)

Open
#1,420 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
JavaScript
Stars
337
Forks
792
Avg merge
17h 23m
Merged PRs (30d)
49

Description

## Problem

Base App's April 2026 update changed how mini-apps are launched: they now open in a **standard in-app WebView** instead of a Farcaster mini-app host. This is a breaking change for any mini-app that uses `@farcaster/miniapp-sdk` for wallet access.

The current docs don't cover:
1. How to detect Base App in-app browser vs. true Farcaster embed (Warpcast)
2. How to fall back to injected EIP-1193 provider (`window.ethereum` / `coinbaseWalletExtension`) in Base App
3. The `sdk.actions.ready()` / `sdk.wallet.getEthereumProvider()` hang issue specific to Base WebView

This causes mini-apps to silently hang on transactions — no error, no timeout, just an indefinite loading state.

## Suggested Addition

A **"Wallet Provider Migration for Base App 2026"** section in the mini-app docs covering:

### Detection pattern
```js
// Base App (post-April 2026) does NOT act as Farcaster mini-app host.
// sdk.isInMiniApp() returns false — use injected EIP-1193 instead.
async function getProvider(sdk) {
const isEmbed = await Promise.race([
sdk.isInMiniApp(),
new Promise(resolve => setTimeout(() => resolve(false), 1000))
]);

if (isEmbed) {
return sdk.wallet.getEthereumProvider(); // Warpcast / true Farcaster host
}

// Base App or regular browser: use injected wallet
return window.coinbaseWalletExtension
?? window.ethereum
?? null;
}
```

### ready() timeout pattern
```js
// In Base App, ready() never resolves — wrap with timeout:
await Promise.race([
sdk.actions.ready(),
new Promise((_, reject) => setTimeout(() => reject(), 5000))
]).catch(() => { /* continue, Base App doesn't need ready() ack */ });
```

## Working Reference Implementation

This exact pattern was implemented and verified on Base mainnet in a real mini-app:
- **Commit:** https://github.com/schoolkamsergj/base-invaders/commit/64fb7b2b5b9f4e142d5d85642353fd4e62512cca
- **Live app:** https://base-invaders-nine.vercel.app
- **What was fixed:** daily check-in and leaderboard transactions hanging indefinitely in Base App, working correctly in Warpcast

## Impact

Any mini-app using `@farcaster/miniapp-sdk` for wallet transactions that:
- Was built before April 2026
- Relies on `getEthereumProvider()` from the SDK
- Is listed in Base App discovery

...will silently break for **all Base App users** without this migration.

## Related SDK Issue

Filed upstream: farcasterxyz/miniapps#608

---

*Happy to contribute a PR with the docs addition if that would help.*

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.