WebF Routing Setup

Note: WebF development is nearly identical to web development - you use the same tools (Vite, npm, Vitest), same frameworks (React, Vue, Svelte), and same deployment services (Vercel, Netlify). This skill covers one of the 3 key differences: routing with native screen transitions instead of SPA routing. The other two differences are async rendering and API compatibility.

WebF does NOT use traditional Single-Page Application (SPA) routing. Instead, it uses hybrid routing where each route renders on a separate, native Flutter screen with platform-native transitions.

The Fundamental Difference

In Browsers (SPA Routing)

Traditional web routing uses the History API or hash-based routing:

// Browser SPA routing (react-router-dom, vue-router)
// ❌ This pattern does NOT work in WebF
import { BrowserRouter, Routes, Route } from 'react-router-dom';

// Single page with client-side routing
// All routes render in the same screen
// Transitions are CSS-based

The entire app runs in one screen, and route changes are simulated with JavaScript and CSS.

In WebF (Hybrid Routing)

Each route is a separate Flutter screen with native transitions:

// WebF hybrid routing
// ✅ This pattern WORKS in WebF
import { Routes, Route, WebFRouter } from '@openwebf/react-router';

// Each route renders on a separate Flutter screen
// Transitions use native platform animations
// Hardware back button works correctly

Think of it like native mobile navigation - each route is a new screen in a navigation stack, not a section of a single web page.

Why Hybrid Routing?

WebF's approach provides true native app behavior:

1. Native Transitions - Platform-specific animations (Cupertino for iOS, Material for Android)
2. Proper Lifecycle - Each route has its own lifecycle, similar to native apps
3. Hardware Back Button - Android back button works correctly
4. Memory Management - Unused routes can be unloaded
5. Deep Linking - Integration with platform deep linking
6. Synchronized Navigation - Flutter Navigator and WebF routing stay in sync

React Setup

Installation

npm install @openwebf/react-router

CRITICAL: Do NOT use react-router-dom - it will not work correctly in WebF.

Basic Route Configuration

import { Route, Routes } from '@openwebf/react-router';
import { HomePage } from './pages/home';
import { ProfilePage } from './pages/profile';
import { SettingsPage } from './pages/settings';

function App() {
  return (
    <Routes>
      {/* Each Route must have a title prop */}
      <Route path="/" element={<HomePage />} title="Home" />
      <Route path="/profile" element={<ProfilePage />} title="Profile" />
      <Route path="/settings" element={<SettingsPage />} title="Settings" />
    </Routes>
  );
}

export default App;

Important: The title prop appears in the native navigation bar for that screen.

Programmatic Navigation

Use the WebFRouter object for navigation:

import { WebFRouter } from '@openwebf/react-router';

function HomePage() {
  // Navigate forward (push new screen)
  const goToProfile = () => {
    WebFRouter.pushState({ userId: 123 }, '/profile');
  };

  // Replace current screen (no back button)
  const replaceWithSettings = () => {
    WebFRouter.replaceState({}, '/settings');
  };

  // Navigate back
  const goBack = () => {
    WebFRouter.back();
  };

  // Navigate forward
  const goForward = () => {
    WebFRouter.forward();
  };

  return (
    <div>
      <h1>Home Page</h1>
      <button onClick={goToProfile}>View Profile</button>
      <button onClick={replaceWithSettings}>Go to Settings</button>
      <button onClick={goBack}>Back</button>
      <button onClick={goForward}>Forward</button>
    </div>
  );
}

Passing Data Between Routes

Use the state parameter to pass data:

import { WebFRouter, useLocation } from '@openwebf/react-router';

// Sender component
function ProductList() {
  const viewProduct = (product) => {
    // Pass product data to detail screen
    WebFRouter.pushState({
      productId: product.id,
      productName: product.name,
      productPrice: product.price
    }, '/product/detail');
  };

  return (
    <div>
      <button onClick={() => viewProduct({ id: 1, name: 'Widget', price: 19.99 })}>
        View Product
      </button>
    </div>
  );
}

// Receiver component
function ProductDetail() {
  const location = useLocation();
  const { productId, productName, productPrice } = location.state || {};

  if (!productId) {
    return <div>No product data</div>;
  }

  return (
    <div>
      <h1>{productName}</h1>
      <p>Price: ${productPrice}</p>
      <p>ID: {productId}</p>
    </div>
  );
}

Using Route Parameters

WebF supports dynamic route parameters:

import { Route, Routes, useParams } from '@openwebf/react-router';

function App() {
  return (
    <Routes>
      <Rou

...