Problem
Running next dev for a microfrontend application fails with a validation error:
Error [MicrofrontendsError]: Invalid microfrontends config:
- Property 'fallback' is required in field applications/manage-frontend/development
- Unable to infer if applications/manage-frontend is the default app or a child app.
See https://openapi.vercel.sh/microfrontends.json for the schema.
The microfrontends.json has application entries but is missing the development.fallback URL:
{
"applications": {
"manage-frontend": {
"routing": [{ "paths": ["/manage/:path*"] }]
}
}
}
Solution
Add a development object with a fallback URL for every application in microfrontends.json. The fallback URL should point to the deployed preview or production URL of that microfrontend:
{
"$schema": "https://openapi.vercel.sh/microfrontends.json",
"applications": {
"web": {
"development": {
"fallback": "https://my-app.vercel.app"
}
},
"manage-frontend": {
"routing": [{ "paths": ["/manage/:path*"] }],
"development": {
"fallback": "https://manage-frontend.vercel.app"
}
}
}
}
Both default apps (no routing rules) and child apps (with routing) require a development.fallback URL.
Why It Works
During local development, only one microfrontend runs at a time on localhost. When a request arrives for a route handled by a different microfrontend, the dev server needs to know where to proxy that request. The fallback URL provides this target -- typically the deployed Vercel preview or production URL of the other microfrontend. Without it, the dev server cannot route cross-microfrontend requests and cannot determine the application hierarchy (default vs child).
The fallback is only used during next dev. In production, Vercel's infrastructure handles routing between microfrontends automatically based on the routing configuration.
Context
- Vercel Microfrontends with
@vercel/microfrontendspackage - Next.js 14+ with
withMicrofrontends()innext.config.ts - The fallback URL must be a deployed, accessible URL (not
localhost) - Deploy at least once before setting up local dev so you have a fallback URL to use
- Schema reference:
https://openapi.vercel.sh/microfrontends.json