Routing Differences with PWA Kit

PWA Kit uses React Router 5 with programmatic route arrays and manual splitting patterns. Storefront Next uses React Router 7 file-based routing with native nested layouts, typed loaders/actions, and automatic route-level splitting. Migrating generally means converting centralized route configuration into route files and moving route data logic into exports.

Key Differences

Aspect	PWA Kit	Storefront Next
Router Version	React Router 5	React Router 7 (framework mode)
Route Definition	Programmatic (array in `routes.jsx`)	File-based (files in `routes/`)
Code Splitting	Manual via `@loadable/component`	Automatic per route file
Data Fetching	Inside components (hooks)	Outside components (`loader`/`clientLoader`)
Loading States	Manual `isLoading` flags	Declarative via Suspense
Nested Layouts	Manual component composition	Built-in via `<Outlet />`
Resource Routes	Express routes in `ssr.js`	Action files (`action.*.tsx`)
Multisite URLs	`configureRoutes()` expansion	Declarative config in `config.server.ts` (`url.prefix`, `url.search`) with automatic detection middleware
Type Safety	JavaScript	TypeScript with typed loaders

Route Definition Comparison

PWA Kit:

1// Centralized route array
2export const routes = [
3  { path: "/product/:productId", component: ProductDetail },
4  { path: "/account", component: Account },
5  { path: "/account/orders", component: Orders },
6];

Storefront Next:

1src/routes/
2├── product.$productId.tsx    # /product/:productId
3├── account.tsx               # /account (layout)
4├── account._index.tsx        # /account (index)
5└── account.orders.tsx        # /account/orders

Navigation API Comparison

PWA Kit (React Router 5):

1import { useHistory, useParams } from "react-router-dom";
2
3const history = useHistory();
4history.push("/cart");
5history.replace("/new-path");

Storefront Next (React Router 7):

1import { useNavigate, useParams } from "react-router";
2
3const navigate = useNavigate();
4navigate("/cart");
5navigate("/new-path", { replace: true });

Key Similarities

Dynamic Parameters: Both use :param syntax (PWA Kit in path string, Storefront Next in file name with $).
Catch-All Routes: Both support wildcard routes (* in PWA Kit, $.tsx in Storefront Next).
Programmatic Navigation: Both provide hooks for imperative navigation.
Route Parameter Access: Both provide useParams() hook for accessing URL parameters.

Storefront Conversion Considerations

Route File Creation: Each route in routes.jsx becomes a separate file in src/routes/.
Naming Convention: Learn the flat routes naming pattern ($ for params, . for nesting).
Data Fetching: Move data fetching from component hooks to loader/clientLoader exports.
Layout Routes: Use layout routes with <Outlet /> instead of manual nesting.
Resource Routes: Convert Express API routes to action.*.tsx files.
Loading States: Replace isLoading checks with Suspense boundaries via createPage.