Storefront Next: Architecture and the PWA Kit Migration

A CEO went on the record with a number that stopped me mid-scroll: an accelerator that took six developers six months to build on PWA Kit was ported to Storefront Next “in just over a week with six agents.” Read that twice. Either something extraordinary happened, or a lot of nuance got left out of one sentence.

Both, and I can say so with a straight face because that accelerator is one my team and I worked on. Full disclosure: the CEO doing the quoting also happens to sign my paycheck, so weigh my straight face accordingly.

I’m aware that makes the rest of this paragraph sound like I’m marketing my own work back to you. I am, a little, and I’d rather say so than have you notice first. But the number itself isn’t the marketing: six agents did compress a six-month build into about a week, I watched it happen, and pretending otherwise just to sound less like a launch quote would be its own kind of dishonest. What the quote skips is the finish line: a week got us to roughly 80% done, not the clean handover the sentence implies. I was genuinely astonished at how far the models got on their own. I was less astonished, once the token bill came in, that none of this was free.

This is also the post two of my older ones owe you. SiteGenesis vs SFRA vs PWA flagged Storefront Next as “new enough that this comparison doesn’t cover it in depth.” What Composable Storefront Means for SFCC Developers went further: “I haven’t built anything on it yet, so I won’t hand out a feature-by-feature verdict here.” I have now. Here’s the verdict.

What Storefront Next Is

Start with what doesn’t change, because it’s the part that makes any of this tractable. Storefront Next “keeps the same B2C Commerce backend model as PWA Kit (SCAPI, SLAS, and Managed Runtime),” per Salesforce’s own PWA Kit comparison guide. Same shopper APIs, same auth service, same hosting platform. If your integrations, price books, and custom SCAPI endpoints work today, they don’t need touching.

What changes is everything above that backend. The architecture guide lists the stack plainly: React 19, React Router 7 in framework mode, Vite, TypeScript, Tailwind CSS, shadcn/ui. If you’ve touched Remix, that “framework mode” phrase should feel familiar. The docs say so directly: “If you’re familiar with Remix, React Router 7 framework mode uses the same patterns.” A request lands at the eCDN (Salesforce’s edge content delivery network in front of the storefront), passes through Managed Runtime, and runs a middleware chain (app config, internationalisation, authentication, analytics) before reaching the route loader. From there, the loader fetches data, the server streams HTML as it becomes available, and the client hydrates on top of it once it arrives. PWA Kit veterans will recognise the shape of that pipeline; what’s different is which layer does the work.

The overview guide sums up the shift better than I can: PWA Kit is “a client-heavy, hook-driven architecture,” Storefront Next is “server-first.” That single sentence explains most of what follows.

Every Slack channel I’m in with “pwa-kit” or “storefront-next” in the name eventually produces someone calling this “PWA Kit 4.0.” It isn’t, and the distinction isn’t pedantry. A major-version bump implies an upgrade path: bump a dependency, fix what breaks, ship. There’s no such path here. Storefront Next doesn’t extend @salesforce/retail-react-app, so there’s no codemod that turns one project into the other. Salesforce’s own migration guide treats it the same way: the whole document reads as differences between two architectures, not a changelog between two versions of one. Budget for a rewrite, not an upgrade.

The Real Numbers

Numbers, not vibes: the accelerator landed at roughly 80% ported in about a week, not the finished product the headline implies. Separately, we also took a set of customer-facing demo environments to roughly 75% parity with their current design in a few days. Both ran through an agentic migration workflow with sub-agents my team and I shaped specifically for this kind of migration: not a human developer manually retyping components, and not a single prompt asking an agent to “port this app.”

The gap between 100% and where those numbers landed is the part worth dwelling on, because it wasn’t evenly spread across the codebase. Routing, data fetching, and auth ported fast. The diffs are mechanical enough that an agent with the right context gets them right on the first or second pass. Styling was the layer that ate the extra time. Point an agent at a page full of Chakra components and ask for the Tailwind/shadcn equivalent without first grounding it in your actual design tokens and component conventions, and you’ll burn tokens on output that looks plausible and is subtly wrong: spacing that’s almost right, a shadcn variant reached for where a custom class was needed, a component that renders fine in isolation but doesn’t compose the way the rest of the app expects. I’m not the only one who’s hit this wall: enough people doing agentic frontend work have run into the same failure mode that the general advice now is to keep an agent focused on logic and data, and give it explicit, upfront grounding before it touches styling at all. Once we built that grounding into our own workflow, styling stopped being the bottleneck. Skip it, and it will be yours too.

The Layers That Change

Salesforce documents the PWA Kit differences across seventeen reference pages. Most of the effort concentrates in four of them.

State Management

PWA Kit is “stateless on the server side,” per the state management guide, and leans on TanStack Query plus React Context on the client, with tokens sitting in localStorage. Storefront Next moves persistence into httpOnly cookies read server-side through middleware; per the storage and sessions guide, server-side storage is “request cookies only (stateless),” so the cookie carries what used to live in the browser’s local storage rather than a server-held session. The docs are honest that React Context alone doesn’t cover every case: under “conversion considerations,” they suggest moving to Zustand if complex client state outgrows Context, rather than pretending Context scales indefinitely.

Styling

Chakra’s useMultiStyleConfig and prop-based variants (<Button variant="solid" colorScheme="blue">) give way to Tailwind utility classes composed with cva() (class-variance-authority, which maps a component’s variant props to Tailwind class strings) and cn() (a small helper that merges those class strings without conflicts):

// PWA Kit — Chakra
<Button variant="solid" colorScheme="blue" size="md">Primary</Button>

// Storefront Next — Tailwind + shadcn/ui
<Button variant="default" size="default">Primary</Button>

The props look similar enough to lull you into thinking this is a find-and-replace job. It isn’t. The variant names, the underlying class composition, and the runtime cost (Chakra ships a CSS-in-JS runtime; Tailwind compiles away to nothing) are all different systems wearing similar-looking APIs.

Build Tooling

Webpack 5 and Jest are out; Vite 7 and Vitest are in, per the build tools comparison. TypeScript stops being an optional Babel pass-through and becomes first-class with strict mode on by default. If your CI pipeline, linting, or bundle-analysis tooling assumes Webpack’s plugin ecosystem, budget time for that separately from the application code migration. It’s not covered by porting components.

Routing

File-based routes replace the programmatic array PWA Kit uses:

// PWA Kit — React Router 5, programmatic
export const routes = [
  { path: "/product/:productId", component: ProductDetail },
];

Storefront Next replaces it with a file whose name and location encode the route:

src/routes/
├── _app.product.$productId.tsx    # /product/:productId

The same shift touches navigation calls throughout the app: useHistory() and history.push() give way to useNavigate() and navigate(). Small on its own, but it touches every navigation call site in the app, which is exactly the kind of change that’s tedious for a human and quick for an agent that can grep the whole codebase in one pass.

Extensibility

PWA Kit v3 introduced template extensibility: declare @salesforce/retail-react-app as a base template, declare an overrides directory in package.json, and Webpack silently swaps in your file wherever the base template imports that same path. It works, but the docs are upfront about the footgun built into it: “the more files that you override, the more effort is required to keep up with changes in the base template.” Miss an export in your override and the build fails with something like export 'CAT_MENU_DEFAULT_ROOT_CATEGORY' ... was not found. I’ve lost more than one afternoon to exactly that.

Storefront Next replaces file-shadowing with the Commerce Apps framework and its UI Targets system. Instead of overriding a whole file, the core app declares named slots, for example <UITarget targetId="sfcc.pdp.reviews.rating" />, and a Vite plugin swaps in your component at build time. There’s no import path to hijack and no re-export contract to maintain: you register a component against a target ID, and the platform handles placement.

// PWA Kit v3 — override the whole file
// overrides/app/pages/home/index.jsx
export default function Home() { /* ... */ }

// Storefront Next — register a component against a named target
// storefront-next/src/extensions/my-app/target-config.json
{
  "components": [
    {
      "targetId": "sfcc.pdp.reviews.rating",
      "path": "extensions/my-app/components/star-rating.tsx",
      "order": 0
    }
  ]
}

“Commerce Apps replace overrides” oversimplifies things, though. Overrides were a frontend-only mechanism; Commerce Apps also cover the backend, replacing shared hooks like dw.order.calculateTax with domain-scoped extension points like sfcc.app.tax.calculate, so two integrations stop fighting over the same hook. As of this writing, only Tax has a platform-defined backend contract live. Ratings & Reviews, Loyalty, Search, Address Verification, and Analytics shipped in the same April 2026 wave as fullstack domains, where the platform provides the UI targets but each ISV (the third-party vendor building the integration) still builds its own custom SCAPI backend. Shipping, Fraud, and SFRA support are slated for the next wave. That next wave is roadmap, not shipped. Salesforce’s own docs flag every future wave as subject to change, so plan around what’s live today, not what’s promised.

Side by Side

The Path Most of You Care About

Here’s the thing the “migrate from PWA Kit” framing quietly assumes: that you’re already on PWA Kit. Most SFCC shops aren’t: they’re on SFRA, and until recently, PWA Kit wasn’t even a required stop on the way to a modern frontend. It still isn’t. Salesforce’s current storefront decision guide no longer lists PWA Kit as an option at all. The choices are Storefront Next as the “Recommended option,” SFRA, a hybrid SFRA-to-Storefront-Next path, or building your own. PWA Kit didn’t get demoted — it got dropped from the table entirely.

The hybrid path is worth far more attention from an SFRA shop than a full storefront rewrite, and it’s already adjacent to territory this blog has covered. It’s built on two pieces you may already half-recognise:

• Hybrid Auth keeps an SFRA/SiteGenesis dwsid cookie and a SLAS JWT in sync at the same time, using a SLAS client configured with the sfcc.session_bridge scope. That’s the same session-bridging idea behind the OCAPI session bridge, extended to cover Storefront Next.
• eCDN route-splitting sends top-of-funnel traffic (home, category, product detail) to Storefront Next, while checkout stays on your existing SFRA templates until you’re ready to move it. If you’ve already set up staging or production eCDN routing, this is the same mechanism pointed at a new destination rather than a new concept to learn.

Note

Version check: Hybrid Auth support is documented as available as of B2C Commerce 25.6 for Storefront Next, SLAS clients, and SFRA/SiteGenesis templates. A related piece, the dw.order.mergeBasket hook for merging baskets on login, landed a release later, in 25.10. Don’t assume both shipped together if you’re checking version currency before scoping a hybrid project.

Migrating three top-of-funnel page types behind a route-splitting rule is a different project than replacing an entire application, both in risk and in how much you can roll back. That’s the version of this decision most of you are actually facing, PWA Kit or not.

What the Marketing Leaves Out

None of this makes the “just over a week” claim a lie: I was there, and the week is real. It makes it a headline missing its footnote. A week gets you the mechanical layers: routing, data fetching, the parts an agent can transform with a grep and a pattern match. It doesn’t tell you that “just over a week” landed at roughly 80% done, that almost all of the missing 20% was styling, or that six developers’ worth of institutional knowledge about the accelerator’s edge cases doesn’t transfer to an agent just because the agent has read the code. Even the number itself isn’t fixed: the same story made the rounds on LinkedIn with a different shape: one architect plus six agents in five days, instead of six agents in just over a week. Nobody’s lying. The story just gets rounder every time someone else retells it, which is exactly why you should measure your own migration instead of borrowing someone else’s number.

It also doesn’t mention the bill. Getting there ran several agents in parallel on frontier-tier models for days at a stretch: Fable and Opus 4.8 on the planning and architecture calls, Opus 4.8 and Sonnet 5 doing the bulk of the actual migration work. Set against six developer-months, that’s not a rounding error, but it isn’t free either. I’ve got a separate post working through what an agent fleet like that actually costs, and how to keep the spend honest.

The honest version of the pitch is: agentic migration compresses the mechanical rewrite, and it does so by roughly the order of magnitude the quote implies. It doesn’t compress the parts that were never mechanical to begin with: design fidelity, edge cases nobody wrote down, and the judgement calls a senior developer makes without noticing they’re making them. Budget for those, and for the model bill, and the week-long number becomes credible instead of suspicious.

One Genuine Bright Spot

Not everything here is a caveat. Storefront Next ships an end-to-end test suite built on CodeceptJS and Playwright, with axe-core accessibility scanning against WCAG 2.1 AA baked in across desktop and mobile viewports. CodeceptJS AI adds self-healing locators: tests that repair themselves when a selector breaks instead of failing outright. PWA Kit never shipped anything comparable out of the box. If you’re weighing the migration cost against what you get, put this on the credit side of the ledger without qualification.

So, Should You Migrate

If you’re on PWA Kit today and it’s doing its job, there’s no fire drill here, and Salesforce’s own numbers back that up: PWA Kit’s support policy guarantees security patches for a minimum of 24 months after the GA of whichever major version you’re on. There’s no published kill-switch date, just that rolling floor. The nearer forcing function is the Node.js runtime underneath it, not PWA Kit itself: Node 18 hit end-of-life in April 2025, and Node 20 follows in April 2026, so a stalled platform migration hits the runtime wall well before it hits any PWA Kit deadline. Combine that with Storefront Next being new enough, and Hybrid Auth young enough (25.6, a year and a half of production mileage at most), that “wait for the next storefront refresh” is a defensible position. If you’re starting greenfield, skip PWA Kit; Salesforce already has, and building on a stack it no longer recommends is a strange way to start a new project.

If you’re on SFRA, the calculus is different and, in my experience, more interesting: the hybrid path lets you put a modern frontend in front of shoppers on the pages that matter most for conversion, without touching checkout or betting the whole storefront on day one. That’s the project I’d actually recommend starting first.

Whichever path you’re on, don’t hand an agent your styling system without grounding it first. That one lesson cost my team and me more time than everything else in this migration combined. And it’s the cheapest lesson in this whole post to take on faith instead of learning the hard way.

Consider both footnotes closed.