Can a PWA Kit storefront move to a self-hosted headless backend without a rebuild?
A PWA Kit storefront can usually keep its UI layer and content, but its data layer, checkout calls and hosting must change, which makes the move a rewrite of the API integration. The two short-answer options are Medusa and Saleor. Both replace the Salesforce Commerce APIs with their own services, so every point where the storefront reads a product, builds a basket or submits an order has to be pointed at new endpoints and new data shapes. If a renewal or hosting constraint forces a decision soon, the first task is to map which parts of the current PWA Kit project call Salesforce directly and which parts only render what those calls return.
The reusable part is the presentation layer: React components, page templates, styling, layout, content and copy, accessibility fixes, and analytics event definitions, provided they do not depend on Salesforce-specific data shapes. The part to rewrite is everything that reads or writes commerce state. Product and variant lookups, pricing, basket and checkout calls, customer sessions and order submission all need new data-fetching code. Saleor exposes these through a GraphQL API, so queries are written against its schema, including channel-specific pricing and stock. Medusa organizes commerce logic into modules for carts, orders, product catalogs, pricing and inventory, so checkout steps map to different services. Ask your team to list the data-fetching modules and hooks in the project, because that list largely sets the size of the rewrite.
Hosting changes in two places. Managed Runtime is where the storefront runs today, so once it is no longer available the storefront needs your own hosting, with a build pipeline, environment configuration and a rollback path. The backend also becomes yours to run. A self-hosted Medusa deployment needs PostgreSQL, Redis and two Medusa instances, one in server mode and one in worker mode, with migrations applied by the predeploy script and a deployment check against /health. Saleor needs its API, Dashboard, PostgreSQL, Valkey or Redis, and Celery workers, and its Docker Compose setup asks for at least 5 GB of memory. Ask Salesforce for the exact Managed Runtime end date and data export terms in your contract, then run a proof of concept on one storefront route, such as the product detail page, before committing to a full rewrite.
What a headless replacement must cover
A PWA Kit storefront depends on Salesforce's APIs, session handling, checkout services and Managed Runtime hosting, and each of these has to be answered by something in the new stack. The cards below set out what Medusa and Saleor provide, what must be rebuilt, and what to confirm before committing to a design.
API contract replacement
PWA Kit components call Salesforce's shopper APIs for products, baskets and orders. Saleor exposes its whole surface through one GraphQL API, while Medusa exposes store and admin routes that your storefront calls directly. Map every endpoint the storefront uses to a Saleor query or mutation, or a Medusa store route, and list the gaps as custom work. Confirm the exact shapes in each vendor's current API reference before estimating front-end changes.
Catalog and price data
Salesforce stores products, price books and site-specific pricing in ways that do not map one to one. Saleor models this as channels, each with its own currency, pricing and stock across warehouses, so each Salesforce site usually becomes a channel. Medusa handles pricing and inventory through its own modules. Decide early how price books, locales and variant attributes translate, and test pricing output against live Salesforce values for a sample of products.
Session and cookie handling
PWA Kit relies on Salesforce session and basket cookies that the storefront server issues and refreshes. Medusa requires COOKIE_SECRET and JWT_SECRET values for its server and worker, so authentication and cart persistence must be designed around those secrets and the storefront's domain. Saleor authenticates API calls with tokens. Plan how guest carts merge into logged-in customer sessions, and test the behavior across the storefront, the admin and any worker processes.
Checkout and payments
Checkout logic that lives in PWA Kit hooks and Salesforce payment cartridges has to be rebuilt against the new backend. Saleor provides split payments, multi-gateway payment support, returns and a promotion engine with vouchers, cart rules and gift cards. Medusa provides cart, order and promotion modules. Verify each payment provider integration, tax calculation and promotion rule against your current checkout before cutover, because neither platform replaces custom cartridge logic automatically.
Storefront hosting and rendering
Managed Runtime runs the PWA Kit server-side rendering process for you. Once it is gone, the rendering server must be hosted in your own infrastructure or on another managed service. Medusa needs its server, worker, PostgreSQL and Redis running, and Saleor needs its API, Dashboard, PostgreSQL, Valkey or Redis and Celery workers. Confirm which parts of the storefront renderer you will host, how caching and scaling work, and who operates each component after launch.
Medusa and Saleor against the PWA Kit stack
This table compares Medusa and Saleor on the points that matter when a PWA Kit storefront is re-platformed: API style, licensing, channel pricing and stock, extension model and the services you run yourself. Read each row as a question to answer for your own storefront, since PWA Kit features without a direct open-source equivalent are listed at the bottom for confirmation.
| Area | Medusa | Saleor |
|---|---|---|
| API style | Modules exposed through store and admin APIs in a Node.js and TypeScript codebase, so storefront calls map to Medusa routes | Everything exposed through a GraphQL API, so storefront queries map to GraphQL operations against channels |
| Licensing | MIT core framework; Enterprise Edition features based on role-based access control need a commercial agreement with MedusaJS, Inc. | BSD-3-Clause licensed; confirm with Saleor which hosted or paid services sit outside the open-source code |
| Multi-channel pricing and stock | Pricing and inventory are modules; confirm how regional price lists and stock locations match your Salesforce site and price book design | Per-channel pricing, currencies, stock and products across multiple warehouses are built in, which maps closely to multi-site setups |
| Extension model | Custom modules, workflows and subscribers inside the Medusa codebase | Webhooks, apps, metadata and API extensions rather than in-process plugins, which keeps custom logic outside the core |
| Self-hosted components | PostgreSQL, Redis, S3 for files, and two Medusa instances: one server for the API and admin, one worker for background tasks | API, Dashboard, PostgreSQL, Valkey or Redis, and Celery workers, configured through environment variables |
| Footprint trade-off | Server and worker split adds a second process to deploy, monitor and scale | Dashboard, Celery and cache layers add services, and the Docker Compose setup asks for at least 5 GB of memory for Docker |
| Storefront hosting after Managed Runtime | Storefront is a separate application you host on your own infrastructure; confirm the hosting target and build pipeline | Storefront is a separate application you host on your own infrastructure; confirm the hosting target and build pipeline |
| PWA Kit features with no direct equivalent | Confirm Managed Runtime caching, SSR behavior and Salesforce-specific page and personalization hooks with your team before scoping | Confirm the same items; Saleor does not provide Salesforce personalization or Managed Runtime services, so plan replacements explicitly |
What from PWA Kit can be reused and what must be rewritten
Start by sorting the storefront code into a presentation layer and a data layer, because the presentation layer is the part most likely to carry over. Component design, styling, routing and content structure describe how pages look and how shoppers move between them, and none of that depends on a specific commerce backend. Product listing and detail templates, navigation, page layouts and the design tokens behind them can usually be kept, with changes limited to how they receive data. Ask the storefront team for an inventory of templates and components, and mark each one as presentational only or as tied to commerce data. Editorial content such as landing pages and banners may live in a separate content system, so confirm that it is independent of the commerce backend before planning its reuse.
The data layer is where most of the rewrite sits. Every call to the Commerce APIs for products, prices, inventory, categories and search has to be replaced, and the replacement depends on the target platform. Saleor exposes everything through a GraphQL API with per-channel pricing, currencies, stock and products, so the product list and product detail queries must be written against its schema, and the storefront's data-fetching code needs to be written again for that schema. Medusa's modules for product catalogs, pricing and inventory cover the same ground, but its endpoints and response shapes differ from the Commerce APIs. Confirm the exact endpoints and response fields against the version the team pins before writing any client code, and keep the data-fetching functions in one module so later changes stay contained.
Basket, authentication, promotions and checkout carry the most business risk and should be rebuilt and tested as one unit. Cart state, customer login, session handling and the promotion logic for vouchers and cart rules are tied to how the existing backend stores carts and identifies shoppers. Saleor's promotion engine includes sales, vouchers, cart rules and gift cards, and Medusa's cart and order modules cover carts and orders, but neither removes the need to map each existing promotion, payment and tax rule one by one. Saleor extends through webhooks, apps and metadata rather than in-process plugins, so each custom checkout hook needs a defined replacement. Keep a written test list covering payment gateways, shipping, tax and order export to downstream systems, and run it end to end before any traffic moves.
How to host the storefront after Managed Runtime
This sequence moves the PWA Kit storefront and its commerce backend from Managed Runtime to infrastructure your organization controls. The result is a verified staging environment where the storefront runs and calls a self-hosted Medusa or Saleor backend.
Confirm how the storefront renders
The team that owns the PWA Kit project confirms whether pages render on the server, in the browser or both, which Node.js version the build targets, and which services and environment variables the storefront calls at runtime. Managed Runtime may have handled some of this without visible configuration, so compare the current build settings with what the platform actually did. The output is a written runtime inventory that the hosting team can build against. Confirm these requirements with Salesforce's PWA Kit documentation and your own repository before choosing infrastructure.
Choose a container host you control
The platform owner selects where the storefront container will run, such as your own cloud account, an on-premises cluster or a managed container service that your organization administers. Confirm that the platform can run a long-lived Node.js process, pull images from your registry, reach a managed PostgreSQL and Redis or Valkey service over private networking, and keep secrets out of images. Also ask who handles patching, scaling and backups. The output is an approved target environment with a named operations owner.
Deploy the commerce backend services
The platform team deploys the commerce backend beside the storefront. For Medusa, run one instance in server mode for the API and admin dashboard and a second in worker mode for background tasks, both connected to PostgreSQL and Redis, with S3 for file storage in production. For Saleor, deploy the API, Dashboard and Celery workers with PostgreSQL and Valkey or Redis. The Saleor Docker Compose setup asks for at least 5 GB of memory for Docker, so confirm capacity on the chosen host first. The output is running services that share one database and one cache.
Run database migrations before startup
Apply schema changes before the new version starts serving traffic. Medusa runs its migrations through a predeploy script before each startup, so the deployment pipeline should call that script in the same job that builds the release. For Saleor, follow the migration and population steps in its Docker Compose setup and confirm the exact commands for the release you deploy. The output is a database at the expected schema version and startup logs with no migration errors, plus a written rollback plan for the next release.
Set environment variables and secrets
The platform team sets configuration as environment variables in the container platform's secret store, not in the image or the source repository. Each Medusa server and worker needs its database credentials plus COOKIE_SECRET and JWT_SECRET values. Saleor is configured through environment variables that follow 12-factor app principles, so apply the same secret handling to its API, Dashboard and workers. Keep backend secrets out of the storefront bundle and record which owner rotates each one. The output is a configuration record per service that a second engineer can review without seeing secret values.
Verify the deployment through health checks
Confirm each Medusa deployment through the /health endpoint before connecting the storefront. A healthy response from the server, along with a worker log showing background jobs running, shows the services are ready. For Saleor, confirm the API and Dashboard respond and that Celery workers pick up queued tasks. Then point a staging build of the PWA Kit storefront at the new API endpoint and run catalog, cart and checkout requests. The output is a signed-off staging result showing the storefront can run on your host and call the backend.
Evidence to keep for the cutover
An internal reviewer or auditor will want to see proof that the new headless storefront and backend behave as the PWA Kit storefront did before go-live. The items below are the records that show it, and each one should be kept with the release it describes.
API contract test results
Keep the output of every test run that checks the storefront against the new backend's API, including product, cart, checkout and customer calls. Record the backend version under test, since a Medusa or Saleor upgrade can change response shapes. Reviewers will ask which PWA Kit calls were mapped to which new endpoints and whether any were dropped on purpose. Keep failing runs too, with the decision taken on each failure.
Catalog and price reconciliation reports
Keep reports that compare product counts, variants, images, categories and price lists between the Salesforce export and the new catalog. Include a sample of SKUs checked by hand for each market and currency. Reviewers will ask how pricing rules, such as price books mapped to channels or regions, were verified rather than assumed. Store the scripts used to produce the reports so the comparison can be repeated.
Checkout test records
Keep scripted and manual checkout test results covering guest and logged-in buyers, promotions, tax, shipping methods, each payment gateway and failed payments. Record the test accounts and the environment used, without storing live card data in the test evidence. Reviewers will ask whether returns, refunds and order status updates reached the order management or ERP system. Keep the order IDs created during testing so they can be traced.
Session and secret handling configuration
Keep the documented configuration for cookies, session secrets, JWT signing values and database credentials, stored in a secrets manager and not in source control. For a self-hosted Medusa deployment, this includes the COOKIE_SECRET and JWT_SECRET values for both the server and worker instances. Reviewers will ask who can read and rotate each secret and when rotation last happened. Keep the access list and the rotation log with the configuration.
Health check logs
Keep the results of health endpoint checks and uptime monitoring for the backend, the storefront and their background workers, along with alert history. For Medusa, the /health endpoint is the check to record. Reviewers will ask whether the migration period had any gaps in availability and how incidents were handled. Keep logs for the parallel run and the first weeks after cutover, not only the go-live day.
Hosting access and change records
Keep records of who had access to the hosting account where the storefront runs, including the Managed Runtime or replacement host, the database and the object storage bucket. Include deployment history, the migration scripts run against production and approvals for each change. Reviewers will ask how access was removed for the former Salesforce and PWA Kit contractors and whether the Managed Runtime account was closed in an orderly way. Confirm the retention period for these records with your compliance team.
Questions before hiring help on a PWA Kit move
How much of a PWA Kit storefront can be reused on a headless Medusa or Saleor backend?
Usually the presentation layer and the storefront logic that is independent of the Salesforce APIs are the parts most worth reviewing for reuse, while anything that calls Salesforce Commerce APIs must be rewritten against the new backend's API. Medusa exposes its commerce modules through its own API, and Saleor exposes everything through GraphQL, so data-fetching hooks, cart and checkout calls, and session handling will change. Components, styling, routing and content templates often carry over with adjustments. The exact split depends on how tightly your PWA Kit code is coupled to SCAPI endpoints, so ask for a written inventory of reusable modules before agreeing on scope.
What drives the effort of a PWA Kit to headless migration?
Effort tracks how many data-fetching paths, checkout steps, promotions and customer flows depend on Salesforce-specific behavior. The main drivers are the number of sites and locales, the number of price books and currencies, custom checkout or payment logic, personalization that depends on Salesforce services, and the volume of catalog data that must be mapped to the new data model. Saleor's channels and Medusa's regions and pricing modules map to different parts of that model, so the mapping work is a significant share of the job. Ask any provider to break the estimate down by these items.
What does the work need from our own engineers?
Your engineers need to provide access to the current PWA Kit code, the Business Manager configuration that defines sites, price books and payment settings, and representatives who can confirm business rules for promotions, tax and fulfillment. They also need to decide who owns the storefront codebase after handover, because it will be maintained in your repository rather than on Managed Runtime. Plan for review time during design and cutover, and confirm in writing which decisions require your sign-off and how quickly they are expected.
Can an in-house team move the storefront without outside help?
An in-house team can do it if it already has React or TypeScript experience, has run a headless storefront, and can take on both the backend deployment and the storefront build. Medusa and Saleor both need a database, a cache or message layer, background workers and an environment-based configuration, and self-hosted Medusa also needs its server and worker deployed correctly. The usual gap is operations: monitoring, backups, upgrades and incident response for the commerce backend. If those skills are thin, a fixed-scope engagement that includes documentation and handover can reduce the risk of a stalled cutover.
How long does a PWA Kit migration take?
No duration has been established for this specific move, so the timeline should come from a written scope that lists sites, locales, integrations, and the storefront and backend work separately. Ask for milestones covering data mapping, storefront rebuild, integration testing, a parallel run and cutover. A useful check is whether the plan states what happens if a dependency, such as a payment gateway or ERP connection, is delayed.
What does replacing Managed Runtime cost, and what are the components?
Managed Runtime bundles hosting, build and deployment for the storefront, so replacing it means paying separately for each part. The components are compute for the storefront, a container or server platform, a CDN and caching layer, monitoring, a CI/CD pipeline, and the people who operate them. The commerce backend adds its own costs: a managed or self-hosted Medusa or Saleor deployment, PostgreSQL, Redis or Valkey, object storage for files, and Node.js or Python workers. Recurring costs are the infrastructure and maintenance, while build and cutover are one-time. Ask any quote to list each component, who pays for it and whether it recurs.
What licence terms apply to Medusa Enterprise features?
The Medusa core commerce framework is MIT licensed, but Enterprise Edition features based on role-based access control require a commercial agreement with MedusaJS, Inc. If your plan depends on those features, such as granular staff permissions in the admin, include that agreement as a line item and confirm its terms before design starts. Do not assume RBAC is free because the core is MIT. Your legal or procurement team should review the agreement, and any services scope should state which features are built on the MIT core and which depend on the commercial license.
Running the storefront and backend in your own infrastructure
The first decision in running a headless stack yourself is who owns each layer after go-live. A self-hosted Medusa deployment needs a PostgreSQL database, a Redis database, and two Medusa instances: one in server mode for the API and admin dashboard and one in worker mode for background tasks. Saleor needs the API, the Dashboard, PostgreSQL, Valkey or Redis, and Celery workers. Each of these components needs an owner for patching, scaling and incident response. The storefront itself, which in the PWA Kit model was hosted on Managed Runtime, becomes a separate deployable that your team or implementation partner must build, host and monitor. Confirm in writing which party carries each of these responsibilities before cutover, not after.
Upgrades are the recurring cost that most often gets underestimated. Track the Medusa and Saleor release pages on GitHub as the input to your upgrade calendar, and read each release for changes to database migrations, environment variables and API contracts. Medusa runs database migrations through a predeploy script before each startup, so a release that changes the schema will run against your production database at deploy time. Test that path in a staging environment with a restored copy of production data. For Saleor, check the Docker Compose configuration and environment variables against each release, since Saleor is configured through environment variables following 12-factor app principles. Your storefront has its own upgrade track for framework and SDK changes, which must be scheduled alongside backend releases.
Backups and monitoring need explicit targets. Back up PostgreSQL with point-in-time recovery if your hosting provider supports it, and back up the S3 bucket that holds product files and uploads, since database restores alone will not recover those assets. Test restores on a schedule, not only when a backup is written. For monitoring, use the /health endpoint on each Medusa instance and the equivalent checks you define for Saleor, and alert on worker queue depth and failed background jobs, because a stalled worker can leave orders and inventory updates pending without any visible storefront error. Ask your hosting provider for its backup retention, restore time objective, alerting integrations and who receives pages out of hours. Those answers, not the open-source project, define your operating commitments.
How DeployOpen plans a headless storefront move
DeployOpen plans, implements, customizes, integrates, hardens, documents and supports self-hosted open-source platforms inside the client's own cloud accounts, data centers or air-gapped networks. For a PWA Kit to headless stack move, that means agreeing in writing what the storefront, backend and integrations must do before any code is changed.
How we scope
- Inventory every PWA Kit route, component and Commerce API call the storefront depends on today
- Record which hosting, runtime and build dependencies tied to Managed Runtime must be replaced
- Agree the target backend, whether Medusa or Saleor, and the channels, regions and currencies in scope
- Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts
How we build
- Map each Commerce API response to the GraphQL or REST model of the chosen backend, with a written field-level mapping
- Rebuild storefront logic such as pricing display, cart and checkout flows against the new API, then test each path
- Stand up the backend in the client's infrastructure, including database, cache, workers and secrets handling
- Run security testing on the storefront, APIs and integrations before launch, and record the findings
How we hand over
- Deliver architecture notes, runbooks for deployment, backups and upgrades, and the configuration reference
- Document which parts of the old PWA Kit code were reused, rewritten or retired, with the reasons
- Provide compliance-readiness evidence where the client's assessors need it, without issuing any audit or certification
- Walk the client's engineering team through operation so the hosting and release process stays with them
How we support
- Ongoing support, upgrades and continuous security testing are available as retainers after handover
- Confirm with us the upgrade cadence for the chosen platform release before the retainer starts
- Ask for the support scope, response expectations and exclusions in the written quote
- Keep the old storefront running until the new one has passed agreed test and cutover checks
