Salesforce Docs Portal

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:

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

Storefront Next:

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

Navigation API Comparison

PWA Kit (React Router 5):

import { useHistory, useParams } from "react-router-dom";

const history = useHistory();
history.push("/cart");
history.replace("/new-path");

Storefront Next (React Router 7):

import { useNavigate, useParams } from "react-router";

const navigate = useNavigate();
navigate("/cart");
navigate("/new-path", { replace: true });

Key Similarities

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

Storefront Conversion Considerations

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

References