/webf-routing-setup

name: webf-routing-setup
description: Setup hybrid routing with native screen transitions in WebF - configure navigation using WebF routing instead of SPA routing. Use when setting up navigation, implementing multi-screen apps, or when react-router-dom/vue-router doesn't work as expected.

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>
      <Route path="/" element={<HomePage />} title="Home" />
      <Route path="/user/:userId" element={<UserProfile />} title="User Profile" />
      <Route path="/post/:postId/comment/:commentId" element={<CommentDetail />} title="Comment" />
    </Routes>
  );
}

function UserProfile() {
  const { userId } = useParams();

  return (
    <div>
      <h1>User Profile</h1>
      <p>User ID: {userId}</p>
    </div>
  );
}

function CommentDetail() {
  const { postId, commentId } = useParams();

  return (
    <div>
      <h1>Comment Detail</h1>
      <p>Post ID: {postId}</p>
      <p>Comment ID: {commentId}</p>
    </div>
  );
}

Declarative Navigation with Links

Use `WebFRouterLink` for clicka