Skip to content


Choose a tag to compare
@dpatil-magento dpatil-magento released this 28 Jan 18:42
· 1509 commits to develop since this release

Release 5.0.0

This changelog only contains release notes for PWA Studio 5.0.0 and above.
For older release notes, see PWA Studio releases.

Table of contents

What's new in 5.0.0

PWA Studio 5.0.0 contains new features, refactors, breaking changes, and various improvements.

Page Builder integration

Page Builder is a content creation tool developed by Magento.
It allows merchants to define store layouts using the Admin panel.

Page Builder integrating with PWA Studio means merchants may now use Page Builder to define the layout in the Magento backend and have that content rendered in a PWA Studio storefront.

This release makes the Venia RichContent component compatible with the default Page Builder content types.


Getting a new PWA Studio project up and running is now easier with the @magento/create-pwa command.
This command is a user-friendly version of the create-project sub-command in the pwa-buildpack CLI tool.

Use this command to set up an initial project structure using the Venia storefront as a template.
It provides an interactive questionnaire to help configure the different parts of your project.

For more information see: Scaffolding


This release introduces the concept of Peregrine Talons.

Peregrine Talons are a set of React Hooks tailored for a specific UI component.
They contain logic for calculating the values rendered by its companion UI component.

Separating the logic and the presentational pieces of a component lets developers swap out either piece when creating custom UI components.

For more information see: Peregrine Talons

New route handler

Routing in the project has been updated to use the React Router library instead of a custom router.

The following is a summary of these changes:

  • The new Routes component replaces renderRoutes()
  • The new MagentoRoute component replaces MagentoRouteHandler
  • The new useMagentoRoute() Talon replaces MagentoRouteHandler

State management refactors

This release refactors the way PWA Studio handles state management in Venia.
Instead of using Redux directly, Peregrine now provides a set of context providers and Hooks to interact with the different slices of state in the global data store.

For more information, read State management

REST to GraphQL migration

With the increase in GraphQL coverage in the latest Magento release (2.3.4), PWA Studio continues to refactor out REST usage in favor of GraphQL.

Various usage of REST have been converted to GraphQL.
These changes include the various cart interactions, sign-in/sign-out, and fetching country data.

For more information on GraphQL, see: GraphQL Developer Guide

Performance improvements

A lot of work has been done in this release to improve the performance provided by PWA Studio tools and libraries.

Service worker improvements

Service worker changes in this release provides smarter use of the cache and when to invalidate stale data.
Other improvements include more optimized bundles/images and route handling.

Optimized images

Handling images on the storefront has been improved in this release.
Storefronts are now able to load the optimal image for a given viewport.

New features such as pre-fetching and lazy loading also boosts page load performance.

Refactoring classes to functional components

This release refactors various classes into functional components.
This was done to align with the move towards using React Hooks throughout the project.


The breadcrumb feature has been added to Venia's product and category pages.
Use this feature to improve navigation in your storefronts.

Potential breaking changes

Since this is a major release, some of the changes previously listed may break projects dependent on PWA Studio and its tools and components.

These changes include:

  • Refactoring to produce Talons have modified the public API of some Venia components
  • Converting from REST to GraphQL calls
  • Optimizing images required updates that modify how images should be used
  • Converting classes to functional components to use React Hooks
  • Replacing MagentoRouteHandler with new component and Talon

Pull requests merged in this release

Venia (storefront and visual component library)

Description Change type PR
Added meta descriptions to root pages Feature #2035
Added email validation to ForgotPasswordForm Feature #1997
Improved performance by lazy loading AuthModal Feature #1955
Improved performance by lazy loading Category filters Feature #1971
Improved Image fit with Fastly Feature #1976
Added product page breadcrumbs Feature #1960
Added category page breadcrumbs Feature #1949
Improved product page caching Feature #1935
Added PageBuilder components Feature #1872
Implemented the apollo-link-retry Link Feature #1799
Created component for showing categories with no products Feature #1496
Updated template HTML to include noscript fallback Update #2034
Removed id from getCustomer response object Update #2028
Added Email validation in signin form Update #1981
Added support for Carousel appearance for Product content type Update #1951
Updated static to venia-static Update #1932
Upgraded Apollo View layer to Hooks Update #1827
Improved efficiency of the getNavigationMenu query Update #1867
Added field labels for inputs Update #1845
Update mixin references to Talon Update #1820
Deleted unused home component Update #1798
Implemented route-based code splitting Update #1765
Updated Swatch Treatments Update #1512
Added support for initial selections on the Edit Item screen Update #1592
Replaced connected components with context Hooks Update #1664
Removed sticky attribute from the pagination Update #1735
Replaced rem to pixels in the height and width attribute for the pagination image Update #1738
Refactored checkout workflow to set shipping address/get shipping methods with GraphQL Refactor #2018
Refactored code to use updateItem mutations Refactor #2017
Refactored code to use GraphQL for adding items to cart Refactor #1987
Replaced REST endpoing for cart item removal with a removeItemFromCart mutation Refactor #2015
Refactor code to revoke customer token using GraphQL mutation on sign out Refactor #2012
Refactor code to use GraphQL mutation to create/fetch cartId. Refactor #1988
Removed test.only from test file Refactor #1989
Refactor components to fetch Countries from GraphQL instead of REST Refactor #1993
Replaced sign-in REST with GraphQL Refactor #1904
Standardized GraphQL files with 4-space indentation Refactor #1914
Replaced the create-account REST endpoint with the createCustomer GraphQL mutation Refactor #1898
Removed redux.compose() where not needed Refactor #1916
Refactored VeniaAdapter to improve initial page load Refactor #1816
Refactor Gallery component Refactor #1791
Fixed a bug that caused an incorrect default swatch image ratio on the product details page Bugfix #2055
Fixed Search Result counts mismatch Bugfix #2037
Fixed bug that incorrectly toggled the cart drawer inside the update item action Bugfix #2038
Fixed bug that caused an error when adding, editing, then saving a configurable item Bugfix #2040
Fixed Footer position bug which broke z-index styling on Edge Bugfix #2014
Fixed storybook Bugfix #1945
Fixed invalud default initial value for checkout form Bugfix #1983
Fixed bug where Product price does not change when changing configurable options Bugfix #1964
Fixed bug that caused an incorrect number of products being loaded for product content type Bugfix #1973
Fixed bug where data was being persisted on logout Bugfix #1962
Added ability to debounce search input Bugfix #1952
Fixed Hook dependencies for app toast error handling Bugfix #1929
Fixed Button being exported twice Bugfix #1912
Fixed regular expression Bugfix #1880
Fixed a bug that overwrote the animation-fill-mode Bugfix #1839
Fixed Talon import in pagination Bugfix #1826
Fixed SearchBar lazy loading Bugfix #1764
Removed back arrow for first level in main menu Bugfix #1337
Fixed a transparent background bug for .png images Bugfix #1690

Peregrine library

Description Change type PR
Implemented Product Images pre-fetching Feature #1938
Created Search root component Talon Feature #1953
Add ability to lazy load images Feature #1871
Created FilterModal Talon Feature #1884
Created Product Options Talons Feature #1819
Created Footer Talon Feature #1860
Created app Talon Feature #1828
Created ProductFullDetail Talon Feature #1814
Created Navigation Talon Feature #1810
Created ProductImagecarousel and Thumbnail Talons Feature #1817
Created Pagination Talon Feature #1812
Created CreateAccount and CreateAccountPage Talons Feature #1778
Created image Talons Feature #1803
Created MiniCart Talons Feature #1807
Created Forgot Password Talon Feature #1788
Created SearchBar Talons Feature #1786
Created Checkout Talons Feature #1775
Created useCategoryTree Talon Feature #1754
Created categoryTile/categoryList Talon Feature #1755
Created authBar and userChip Talons Feature #1751
Created authModal Talon Feature #1752
Created signIn mixin Feature #1745
Created myAccount mixin Feature #1727
Made pagination page buffer configurable Update #2032
Improved Image API Update #1956
Renamed mixins to Talons Update #1757
Removed selector code Update #1703
Combined the checkoutReceipt actions/state/etc with the checkout state slice Update #1686
Merged the directory state and actions into the checkout state slice Update #1694
Refactored getCartDetails to GraphQL Refactor #2029
Refactored getUserDetails to use GraphQL Refactor #2004
Refactored code to eliminate use of MagentoRouteHandler Refactor #1966
Replaced withRouter with react router Hooks Refactor #1937
Refactored code to use the opposite operator Refactor #1851
Refactored header components and added Talons Refactor #1793
Refactored Venia to extract modular components into Peregrine Refactor #1605
Fixed a Page Builder bug that affected alignment Inheritance for Button Group Bugfix #2085
Fixed a Page Builder bug that appended .html to links redirected to CMS pages Bugfix #2054
Fixed a bug that made the Page Builder's product content type behavior inconsistent with Luma Bugfix #2056
Fixed route cache bug Bugfix #1841

Build tools

Description Change type PR
Implemented robust HTML update checking using Node HTML Parser Feature #2086
Optimized Webpack for Service Worker Feature #1992
Improved error handling for env and stage errors Feature #1943
Implemented HTML caching and Service Worker communication API Feature #1905
Added Image Optimizing Origin as an environment variable Feature #1849
Added commit hash to generated bundles Feature #1881
Improved Service Worker HTML handling Feature #1874
Enabled client side caching Feature #1806
Created scaffolding tools for new projects Feature #1500
Updated Braintree environment variable to be self documenting Update #2008
Updated the backend value in create-pwa package Update #1975
Removed duplicate code Update #1838
Improve buildpack test coverage Update #1598
Replaced the async webpack plugin Update #1628
Refactored Service Worker and ServiceWorkerPlugin Refactor #1832
Removed unused parameters Refactor #1837
Restored working debug error page Bugfix #2011
Fixed handling of service worker actions in Dev mode Bugfix #2002
Fixed hot reloading Bugfix #1972
Suppressed GraphQL Certificate Errors Bugfix #1969
Fixed invalid veniaResource reference in upward.js comments Bugfix #1910
Added a missing break statement Bugfix #1887
Resolved the heuristic fragment matcher warning Bugfix #1707
Fixed a bug in the post-install script Bugfix #1734


Description Change type PR
Created draft for first tutorial for PWA Studio Fundamentals Documentation #2022
Created draft for new tutorial series to help beginners Documentation #2024
Created Tutorial to create storefront component Documentation #1982
Created content rendering topic Documentation #2003
Published venia ui component docs Documentation #1946
Added JSDocs for Venia UI Components Documentation #1853
Created Peregrine Talons overview Documentation #1876
Created List components jsdocs Documentation #1795
Created Carousel component jsdocs Documentation #1794
Created state management doc Documentation #1785
Updated doc dependencies Update #2033
Added MBI to search and updated site switcher Update #2001
Updated upward-spec doc Update #1977
Added site switcher to the header Update #1970
Updated devdocs dependencies Update #1957
Updated cloud deploy docs Update #1926
Added instructions to circumvent self-signed ssl-certificate errors Update #1923
Fixed tools and library graphic Update #1889
Updated Venia setup doc Update #1809
Updated README file Update #1717
Update contribution guide Update #1651
Refactored site content navigation Refactor #1933
Refactored doc scripts to remove unused imports and ignore some parameters Refactor #1835
Fixed typo on cloud deployment topic Bugfix #2007
Fixed typo on cloud deployment topic Bugfix #1974
Removed duplicate words from sentences Bugfix #1893
Changed word to lowercase Bugfix #1834
Fixed pwa-devdocs folder path Bugfix #1643
Fixed UPWARD yml path Bugfix #1644


Description Change type PR
Created initial content for a Venia styleguide Feature #1984
Improved Jest error detection and reporter output Feature #1948
Simplified image middleware with express-sharp update Feature #1830
Updated handlebars version from 4.1.2 to 4.5.3 Update #2048
Added typography section to styleguide Update #2013
Updated eslint dependency Update #2000
Added tests for registerImagePreFetchHandler in service worker Update #1994
Added tests for Service Worker Update #1965
Added CODEOWNERS for Page Builder Update #1961
Updated csv-parse version from 4.3.4 to 4.4.6 Update #1896
Updated test URL for Jest tests Update #1836
Update dependency for npm-run Update #1674
Refactored Service Worker route handling Refactor #1859
Added .gitignore entries to the files comming from @magento/pwa Bugfix #1939
Fixed Prettier use Bugfix #1941
Fixed compatibility of string compare Bugfix #1878
Fixed npx bundlesize path resolution issue Bugfix #1854
Fixed react-feather bundle Bugfix #1852
Fixed a bug that prevented a dev server from running in a Docker environment Bugfix #1558

Upgrading from a previous version

The method for updating to 5.0.0 from a previous version depends on how PWA Studio is incorporated into your project.
The following are common use cases we have identified and how to update the project code.

PWA Studio fork

Many PWA Studio users have forked the PWA Studio Git repository.
Even though their codebase may have diverged a great deal from the current codebase, there is still a Git relationship.

Upgrade method: Update using Git

Pull and Merge the changes from the upstream repository using Git.
Most of the conflicts will be in components that we have fully refactored.

We recommend merging the library code we changed and updating component calls with any new prop signatures introduced in this version.

Manual code copies

Some PWA Studio users have copied parts of the code into their own projects.
This is similar to the Git workflow, but without the merging tools Git provides.

Upgrade method: Manual copy updates

Updating this code involves manually copying updates for the code they use.
New code may also need to be copied over if the updated code depends on it.

This method can be a chore, and we hope that some of the features in 5.0.0 will help these users migrate to a package management approach.

NPM packages

Some users have imported the PWA Studio libraries using NPM.
This is the easiest way to work with the released versions of PWA Studio.

Upgrade method: Update package.json

To upgrade to 5.0.0, update the project's package.json file and change the dependency version for PWA Studio.

Known issues

The following is a list of known issues for this release.

Console error when clicking links

When Magento's Admin UI and PWA Studio storefront are open in the same browser, a console error is thrown.
This happens if your backend shares the same hostname as your storefront.
As a workaround, access the admin from a private browser session so the service worker does not affect requests to the storefront.

Images not loading in development

If you set the MAGENTO_BACKEND_URL environment variable to the secure (https) base url of a local instance, or an instance with a known-bad SSL certificate, images will not load correctly.
As a workaround, manually set the NODE_TLS_REJECT_UNAUTHORIZED environment variable to 0 when running the development server.

Pull Request #2005 addresses this issue and will be part of a future release.

Magento 2.3.2 compatibility

The changes and features introduced in this release use GraphQL endpoints found only in Magento versions 2.3.3 and above.
If your Magento backend uses 2.3.2 and below, you will need additional development to make PWA Studio libraries compatible.