base / base/docs

Docs are unclear about when Mini App import + farcaster manifest are still required

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

Description

I ran into a confusing onboarding path while trying to register an existing app on Base.dev and import it as a Mini App.

What made it hard to follow is that the docs currently point in two different directions:

- `docs/mini-apps/quickstart/migrate-to-standard-web-app.mdx` says that after April 9, 2026 the Base App treats apps as standard web apps, and that Farcaster manifests are no longer required for that path.
- `docs/mini-apps/quickstart/migrate-existing-apps.mdx` and the manifest docs still guide developers through adding `/.well-known/farcaster.json`, generating `accountAssociation`, and using the "Import Mini App" flow.

In practice, this left me unsure about:

- when `/.well-known/farcaster.json` is still actually required
- when Base.dev metadata is enough by itself
- whether the "Import Mini App" flow is optional, legacy, or still required for some apps
- which path should be followed for an app that is already live as a standard web app and already verified on Base.dev

I was able to get as far as verifying ownership and serving the manifest correctly, but the flow still felt ambiguous because the docs suggest both:

1. "no Farcaster manifest required" for standard web apps
2. "add a Farcaster manifest and import your mini app"

A simple decision tree or clarification at the top of these pages would help a lot.

Suggested improvement:

- add a short "Which flow should I use?" section to both pages
- explicitly label the manifest/import path as required only for Mini Apps that still need that flow
- explicitly label the standard web app path as the default path for new Base App registrations if that is the intended experience

Relevant docs pages:

- `docs/mini-apps/quickstart/migrate-to-standard-web-app.mdx`
- `docs/mini-apps/quickstart/migrate-existing-apps.mdx`
- `docs/mini-apps/core-concepts/manifest.mdx`

Happy to open a docs PR for this if helpful.

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.