Skip to content

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

@gizdusum

Description

@gizdusum

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions