React 19 - React Router v7

[odinr]

Azure Bord:

• Feature AB#59294
• User Story AB#66109

As a Fusion Framework App Developer
I want my route configuration to include rich metadata (description, path/search param schema) and be statically analyzable at build time
So that the CLI can generate documentation, OpenAPI specs, prerender lists, navigation trees, and links — without loading the app — chatbot agents can understand and use correct tooling to resolve params and search args — and so that every loader has access to the Fusion framework instance.

---

Acceptance Criteria

Core Functionality

1. App team defines routes using a typed DSL (Domain-Specific Language) (route(), index(), prefix(), layout(), etc.) that compiles to React Router v7 RouteObject[]
2. Each route supports optional metadata: description, params (path params), search (query params)
3. params and search schemas include: description, optional type (string, number, boolean), and enum (array of allowed values)
4. Route metadata is extracted during existing ffc app manifest and ffc portal manifest commands
5. Routes are added to AppBuildManifest and PortalManifestBuildSchema as optional routes field
6. The manifest contains only: path, description, params, search — no file paths, no component references
7. The <Router> component injects the Fusion framework instance into every loader via React Router's context
8. Loaders access framework via loader({ context }) → context.framework with full TypeScript support
9. No runtime cost: manifest is generated before bundling (static analysis only)
10. Full TypeScript support: RouteNode, ParamSchema, SearchSchema, ManifestEntry, LoaderContext
11. Works with React Router v7 (createBrowserRouter, lazy, handle, loader, action)

DSL API Design

12. route(path, component, options?) - Define a route with optional metadata
13. index(component, options?) - Define an index route
14. layout(component, children, options?) - Define a layout route
15. prefix(prefix, children) - Group routes with a common prefix
16. DSL supports nested routes via children array
17. DSL supports all React Router features: lazy, loader, action, errorElement, handle
18. DSL is backward compatible: existing RouteObject[] can be gradually migrated

Framework Injection

19. Framework instance is injected via React Router's context option in createBrowserRouter
20. Loader context type: { framework: Fusion, params: Record<string, string>, request: Request }
21. Framework is available in all loaders regardless of route depth
22. Framework injection works with nested routers (if any)
23. Type-safe loader function: loader: (args: LoaderArgs) => Promise<Response> where LoaderArgs includes context.framework

Build & Integration

24. Route extraction runs during build process (before bundling) as part of manifest generation
25. Route extraction does not require app execution or DOM environment
26. CLI validates route schemas and reports errors with file locations during manifest generation
27. Routes in manifest can be consumed by documentation tools, SSG tools, and other build-time tools
28. Routes field is optional - apps without routes still generate valid manifests
29. Link generation: Tools can generate links to routes using only the DSL/manifest (no runtime execution or file paths needed)
30. Chatbot/AI agent integration: Manifest routes can be used by AI agents to understand route structure and validate params/search args when generating links

Type Safety & Developer Experience

31. TypeScript infers route paths from DSL definitions
32. Type-safe route generation: generatePath and useParams work with typed routes
33. IntelliSense support for route metadata (autocomplete descriptions, params, search)
34. Compile-time validation of enum values matches route usage
35. Clear error messages when route definitions are invalid

Non-Functional Requirements

36. Zero runtime overhead: DSL is compile-time only
37. Bundle size impact: < 1KB for route DSL utilities
38. Build time impact: < 100ms for typical app (50-100 routes)
39. Backward compatible: existing apps continue to work without migration
40. Migration path: apps can gradually adopt DSL alongside existing routes

Edge Cases & Error Handling

41. Handles routes with dynamic segments (:param, *splat)
42. Handles optional route segments
43. Handles routes with query string parameters
44. Handles routes with no metadata (optional feature)
45. Handles invalid route definitions with clear error messages
46. Handles circular route dependencies
47. Handles routes defined in multiple files