v4.0.0

Release 4.0.0

NOTE:
This changelog only contains release notes for PWA Studio 4.0.0 and above.
For older release notes, see [PWA Studio releases][].

Table of contents

• What's new in 4.0.0
• Pull requests merged in this release
• Updating from 3.0.0

What's new in 4.0.0

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

Summary of notable changes

The following is a list of the notable changes included in this release.

New Peregrine Hooks

This release introduces the following new hooks in Peregrine:

• Toast hooks and ToastContainer - Provide logic for managing toast messages and a container for displaying these messages.
• useWindowSize() - A hook that provides window size data and lets you respond to window resizing events.
• useRestApi() and useRestResponse() - Hooks that expose the API for sending REST calls and handling the response.
• useScrollLock() - Hook that gives the ability to lock the document element.
• usePagination() - A hook that provides pagination logic for components that need to navigate through paged data.
• useEventListener() - A hook that gives the ability to add a callback function when an event is triggered on an element.
• useCarousel() - A hook for interacting with the state for a carousel of images.

Component refactors

This release includes code refactors to existing components.
The main purpose for this refactor is to extract the logic from these components and convert them into re-useable Peregrine hooks, such as useCarousel() and useScrollLock().
Another reason for refactoring some of these components is to convert them into functional components.

The list of refactored components in this release include:

• List, List Items, and List Item in Peregrine
• Category in RootComponent
• Header, Checkout, MiniCart, Image, and ProductFullDetail in Venia
• Various left drawer components (See PR [#1552][] for the full list of affected components)

Summary of breaking changes

This release includes changes that may break projects dependent on PWA Studio and its tools and components.

src to lib

The src directories in Peregrine and Venia have been renamed to lib.
This enforces the idea that these packages are meant to be consumed as libraries, but
it also means that you may have to update your import paths in your project.

Venia split

The Venia project is now split into separate venia-ui and venia-concept packages.
This paves the way for better extensibility and customizability when it comes to storefront creation.

The venia-ui package contains the templates and components used to create the Venia storefront.
This package is meant to be used as a component library for custom storefront projects.

The venia-concept package contains the project scripts and configurations used to build and run the actual Venia storefront project.

This change may also require you to update import paths in your project.

See PR [#1499][]

New build tools

This release contains new tools for building, bundling, and configuring storefront projects.

buildpack CLI command - A command line toolkit with subcommands for:

• Generating SSL certificates
• Creating a .env file
• Loading and validating a project's .env file.

See PR [#1498][]

configureWebpack() - A function that provides an opinionated configuration for Webpack.
This replaces a large portion of the webpack.config.js file in the Venia project in favor of a configurable utility that can be used in other storefront projects.

babel-preset-peregrine - A new package that defines a preset for Babel.
This preset is required for storefronts using Peregrine and Venia-UI components.
See PR [#1404][].

Pull requests merged in this release

Venia (storefront and visual component library)

Description	Change type	PR
Added a feature that allows CSS in node_modules to circumvent CSS modules	Feature	[#1242][]
Added a layered navigation modal component for filters	Feature	[#797][]
Added ability to source media URL from GraphQL	Feature	[#1267][]
Added height to makeUrl() and enforced crop in middleware if provided	Feature	[#1361][]
Improved scroll locking	Feature	[#1449][]
Update Billing Address Form to show additional fields	Update	[#1286][]
Removed errant debugger statement in tests	Update	[#1353][]
Updated feathericons to 2.0.x	Update	[#1416][]
Updated webpack-bundle-analyzer dependency	Update	[#1466][]
Added insecure flag to GraphQL schema validation	Update	[#1313][]
Refactored the create account form	Refactor	[#835][]
Refactored templates to allow branded first renders	Refactor	[#1275][]
Added a name property for the search trigger button to improve accessibility	Refactor	[#1395][]
Refactored MiniCart components into functions from classes	Refactor	[#1266][]
Refactored Product Details component to use hooks	Refactor	[#1240][]
Refactored the Header component into a function	Refactor	[#1241][]
Refactored create-account route to use appShell to get provided requisite properties	Refactor	[#1430][]
Refactored Checkout components to use hooks, fix bugs, and split code into functional components	Refactor	[#1309][]
Refactored Category RootComponent into functional components and use hooks	Refactor	[#1211][]
Refactored driver usage to improve Venia portability	Refactor	[#1217][]
Refactored slide filter UX to make it behave like the nav menu	Refactor	[#1471][]
Refactored the edit steps out of redux and into local checkout state	Refactor	[#1338][]
Removed root-relative imports from Venia code	Refactor	[#1497][]
Moved the majority of Venia components into a separate UI library	Refactor	[#1499][]
Refactored left drawer components to use hooks, improve performance, and clean up the UI	Refactor	[#1552][]
Refactored image tags to utilize srcset and sizes for optimized images	Refactor	[#1584][]
Fixed the order ID being displayed incorrectly	Bugfix	[#1249][]
Removed duplicate search icon during load	Bugfix	[#1274][]
Fixed a bug that prevented the loading of JS resources from root	Bugfix	[#1257][]
Fixed a bug that reloaded the cart twice when the last item is removed	Bugfix	[#1230][]
Fixed a bug that created an infinite loop when a product is out of stock	Bugfix	[#1229][]
Fixed a bug that allowed the submi...

v3.0.0

Release 3.0.0

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

Table of contents

• What's new in 3.0.0
• Updating from 2.1.0

What's new in 3.0.0

PWA Studio 3.0.0 contains improvements, new features, and some breaking changes.

Summary of major changes

• Peregrine hooks:
  Custom React Hooks that contain data and state management logic has been added to the Peregrine library.
  These hooks allow developers to easily create functional components that focus on presentational logic.
  These also allow for a more modular use of PWA logic and easier "restyling" of Venia (or any PWA storefront built using PWA Studio).

Summary of breaking changes

• PR #1169 includes the following breaking changes:

  • Removed some public user actions
  • Prop type removed in the CreateAccount component
  • Deleted the ErrorDisplay component
  • Deleted the Input component

• PR [#1078][] includes the following breaking changes:

  • SearchBar component converted into a React hook that uses custom Peregrine hooks

Peregrine changes

Change type	Description	PR
Feature	New custom React hooks	[#1078][]
Update	Upgrade react-router-dom to 5.0.0	[#1063][]

UPWARD changes

Change type	Description	PR
Feature	New resolver added: UrlResolver	#1058, #1175

Venia changes

Change type	Description	PR
Feature	New SwatchTooltip component	[#956][]
Feature	Focus search input on search icon button click	[#1019][]
Update	Improve the usability of the "Remove item" feature in the MiniCart	[#882][]
Tests	Add component unit tests	[#1027][]
Bugfix	Make Create Account and Sign In input style consistent	#1169
Bugfix	Populate Create Account fields with correct values after guest checkout	#1153
Bugfix	Fix expired guest cart errors	#1150
Bugfix	Fix header logo width style	#1070
Bugfix	Disable adding to cart until product options are selected	#1097
Bugfix	Disable update cart button until product options are selected	#1125
Bugfix	Update div tag with Fragment	#1103
Bugfix	Fix configurable media loading issue	#1094
Bugfix	Use placeholder in carousel while loading next image	[#1085][]
Bugfix	Add / to graphql validation endpoint	[#1045][]
Bugfix	Fix makeUrl for Fastly	[#1039][]
Bugfix	Hide menu item from navigation if it is disabled in the Magento admin	[#1022][]
Bugfix	Prevent adding to cart during rapid multi-clicking	[#910][]

Buildpack changes

Change type	Description	PR
Update	Update workbox-webpack-plugin to v4	#1102

Misc project changes

Change type	Description	PR
Update	Update eslint configuration version	#1088
Infrastructure	CI/CD and DevOps fixes and improvements	#1132, #1155, #1087, [#1043][]
Infrastructure	GitHub template updates	[#1077][], [#1048][]

Documentation changes

Change type	Description	PR
Documentation	Explainer comments added to the venia-upward.yml file	#1174
Documentation	New reference docs for Peregrine hooks	#1253
Documentation	New Client side caching topic	#1152
Documentation	Hello UPWARD tutorial	[#1080][]
Update	Add explanation to Magento compatibility table	[#1059][]
Feature	Documentation linting tool added	#1140, #1177
Bugfix	Editorial and minor content fixes	#1171, #1167, #1158, #1139, #1109, [#1020][], [#1000][]

Updating from 2.1.0

The method for updating to 3.0.0 from 2.1.0 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 3.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 3.0.0, update the project's package.json file and change the dependency version for PWA Studio.

Release 2.1.0

What's new in 2.1.0

Release 2.1.0 is a compatibility release for the core Magento 2.3.1 release.

Notable changes include:

• Updated GraphQL queries
• Magento GraphQL query validation tool

Updated GraphQL queries

The Magento 2.3.1 release contains GraphQL schema changes that are not compatible with PWA Studio 2.0.0 presentational components.
This release adds a mapping layer to the wrapper components to maintain backwards compatibility for the presentational components.

This update also includes a change to the .env.dist file in the Venia project.
This change sets the MAGENTO_BACKEND_URL variable to that of a Magento 2.3.1 instance.

If you have previously set up Venia and copied the .env.dist file into your project's .env file, you must update the MAGENTO_BACKEND_URL variable to keep your project compatible.

Pull Request: #990

Query validation tool

PWA Studio 2.1.0 creates a new graphql-cli plugin called validate-magento-pwa-queries to replace the validate-queries.js script in the Venia package.

This tool lets developers know when a breaking change occurs with GraphQL to address incompatibility or breaking changes.
It provides clear error messages regarding where and how to resolve issues.

Pull Request: #1004

Other updates

• Unit tests created to increase test coverage
• Documentation typo fixes
• Devdocs script created for auto-generating reference docs from source
• Misc code cleanup
• Bugfix for shopping cart error when continuing to shop after checkout
• Bugfix for the full screen checkout drawer
• Bugfix for pagination persisting during Query loading state
• Bugfix for Search autocomplete rendering loading component on clear

v2.0.0

🎉 PWA Studio 2.0.0 is live on NPM. Welcome!

What's new

This is a brief development summary for this release.

For a list of relevant Pull Requests related to the 2.0 release, see this GitHub query result.

Server platform and language independence

• UPWARD spec introduced for cross platform server behavior configuration.
  An UPWARD file describes a stack-agnostic server that is used for server side rendering, asset delivery, and proxying.
• A PWA package can now define its network requirements in an UPWARD file.
• A PWA can now be deployed on any tech stack as long as the server is UPWARD compliant.
• UPWARD servers implemented in NodeJS and PHP
• UPWARD spec published and open for community contribution.

Related documentation updates

• UPWARD spec overview(#382)
• UPWARD-js server(#382)

Improved developer experience

• Implemented consistent patterns for workflow, such as action/reducer organization and container/presentational separation, in the Venia reference storefront source code.
• Venia components are now portable and can be used in any React application.
• New centralized driver and adapter concepts for all PWA-Studio component input/output.
• Configurable low level UI elements, such as lists and forms, available for developers without the need for drivers or adapters.
• Improved error handling to help detection and recoverability.

Related documentation updates

• Modular Venia components (#796)
• Venia directory structure(#487 #752)

Venia app-like experience

• Pagination feature added to Venia reference storefront for app-like navigation.
• Inline checkout implemented in the Venia reference storefront.
• Basic account creation and management implemented in Venia.
• Loading state implemented to improved the app-like experience.

Related documentation updates

• Venia Checkout implementation (#673)

Improved shopper experience

• Braintree checkout integration in the Venia reference storefront.
• Search with intelligent previews implemented in the Venia reference storefront.

Related documentation updates

• Braintree integration(#793)

PWA compliance

• Web App Manifest file created for the Venia reference storefront.
  This file provides the metadata for adding the Venia storefront to a mobile home screen.
• Service worker optimizations.

Performance enhancements

• Smart caching implemented to improve service worker catalog caching
• Bandwidth usage optimizations achieved using:
  • Dynamic image compression/resize
  • Advanced minification
  • Bundle splitting
• Improved app performance on devices, including smoother renders and faster Time To First Meaningful Paint.

GraphQL usage

• GraphQL usage increased to match coverage updates in Magento 2.3.0.

Magento Cloud compatibility

• A new Magento module (Magento_UpwardConnector) is available to route frontend requests through an UPWARD-PHP server.
• Solution Implementers(SI) can replace existing Magento cloud storefronts with a new PWA storefront using the UPWARD connector module.
• Documentation created for deploying storefront to Magento Cloud
• Assistance offered by Magento Enterprise Cloud deployment team

Related documentation updates

• README for the Magento_UpwardConnector module, which contains Cloud deployment instructions.

Other documentation updates

New topics

• Theme vs Storefront (#509)
• Install Venia sample data (#474)
• Peregrine Routing (#453)

Updated topics

• Certificate and Valet+ troubleshooting (#637)
• Tools and Libraries (#621)

Known issues

• After submitting a successful order, the application throws up an error notification, and the user has to actively click out of the error notification. (#916)
• Create account page displayed with null values for email, first and last name when creating an account during a guest checkout. (#830)
• (Mobile specific) When there are more categories, users cannot scroll to Sign in button. It blocks user from signing to the account. (#824)

Other notable updates

• Switched from NPM to Yarn for package management
• Setup Venia storefront video developed and available in Magento U

v2.0.0 Release Candidate 2: UPWARD

UPWARD has landed!

PWA Studio is now powered by the UPWARD specification in its middle tier implementation. It no longer relies on Magento's web server to generate application shells. This is a big change! Read more about it in the specification documents.

Changelog

James Zetlen 2018-10-04 Add UPWARD specification, guide, tests, reference implementation (#248)

• doc(upward): UPWARD spec and paper

• feat(upward): test suite and reference impl

• feat(dev): finalize UpwardPlugin for dev mode

• refactor: encapsulate domain gen

• feat(stage): add HTTPS to staging server

James Zetlen 2018-10-04 Update queries for latest 2.3 schema and add validator script (#318)

• fix: update query for small_image schema change

• feat(venia): Script to lint queries against schema

v2.0.0 Release Candidate 1

This is a prerelease in preparation for a larger architectural change in RC2. Here is a rough changelog:

Jonathan Stein 2018-10-03 Account creation (issue #250) (#293) * create generic input component

• create login component, action and reducer catch

• Hook login form to utilize and store token

• Add navigation animation and user icon

• add auth to REST requests

• Add user icon

• add auth header login_token to graphql queries

• Change animation, add user to store

• Move user logic into separate action/reducer

• Add token to auth headers when token is available (rest)

• Style sign in form, fix user reducer

• Rename log in -> sign in. Wire up sign in form.

• Style error messages in sign in form

• write test for signIn and input, small style and prop fixes

• Add redux actions to create account and transfer guest cart to user's account

• add form, navheader and create account components, update styles

• Transferring cart to a newly created customer account created an
  issue where a guest cart could not be made. getCartDetails now checks if
  a user is signed in.

• add debounce email check

• add error display and checkbox components, wire up account creation with redux

• add automatic login

• Close createaccount if user is signed in

• let checkbox highlight on focus, add firstname and lastname required fields

• Tests for createAccount form

• use browser persistence instead of interacting directly with local storage

• add autocomplete to input

• set default username and replace Form component with Informed's Form

• start switch to Text component from Informed

• switch to dot lookup in navigation states

• Set initial value of CreateAccount (inform)

• modify user actions/reducers to be in release 2.0 format

• write tests for async User actions

Jimmy Sanford 2018-10-01 Update hardcoded client path in root template (#315) Now that client assets are output to web/js, the currently
hardcoded path in root.phtml needs to be updated.

James Zetlen 2018-10-01 fix: reducer removes guestCartId when it fails (#314)

James Zetlen 2018-09-28 fix(dev): merge 'assets' and 'output' paths (#220) - Remove the concept of the "assets" directory entirely, and set the
"output" directory to be just "web/".

• Remove the old logo asset from /web/ (pre-Venia rebrand!)
• Gitignore entire "web" directory
• Set JS files to output to 'web/js' subdirectory by adding directory
  prefix to output.filename and output.chunkFilename
• Modify tests, documentation, and type expectations to remove
  paths.assets

• Check if captureStackTrace exists before calling

• Add test to ensure captureStackTrace isn't called when it does not exist

Unit tests should use MemoryRouter, not BrowserRouter, and do
shallow rendering rather than full mounting.

• feat(dev): Make PWADevServer host/SSL optional (#175)

PWADevServer attempts to create a unique domain name, create local
SSL certificates, and tell the OS to trust those certificates, for
every new project. It also tries to confirm they exist on every run!

This causes many problems for users under some common conditions:

• No administrative access to local machine
• No OpenSSL installed, or wrong OpenSSL installed
• OS cannot be scripted to trust certificates
• Developer uses Firefox, which uses its own cert store

Additionally, some bugs in the implementation have caused some
developers' projects to enter an unusable state.

• Adds provideUniqueHost flag to PWADevServer configuration.
  PWADevServer will no longer try to create or retrieve a custom domain
  name unless provideUniqueHost is in its configuration in
  webpack.config.js as either a custom string or true.
• Adds provideSSLCert flag to PWADevServer configuration. PWADevServer
  will no longer try to create or retrieve a trusted SSL certificate
  unless provideSSLCert: true is in its configuration in
  webpack.config.js.
• Modifies custom domain name creation strategy to ensure uniqueness
  based on a hash of the full local path, rather than using the local
  flat file database.

We created these features for the needs of the developer working on
several PWAs at once on their local machine, so that they don't have to
set up manual SSL every time, and they have no conflicts with Service
Workers. This could be considered "bonus functionality", as it's not
critical to the setup of a minimum viable PWA. It was meant to establish
our focus on developer experience, and articulate the parts of developer
setup that PWA Studio can "own".

However, we soon learned that we could not maintain all scenarios for
automated setup and continue to make progress with shopper-facing
features. We still really want to support and automate all of these
scenarios, but for now, our implementations are a hindrance and we are
turning them off by default.

Paul 2018-09-26 Default pragma (#229) chore: Switch back to default pragma

• Switched import { Component, createElement } from 'react';) to import React from 'react', { Component };
• Switched import { Fragment, createElement } from 'react';) to import React from 'react', { Fragment };
• Switched import { createElement } from 'react';) to import React from 'react';
• Added eslint-plugin-react and updated eslint configuration
  accordingly

Jimmy Sanford 2018-09-25 Merge develop branch (#298) * Reorganize redux, add address form

• refactor(redux): Reorganize actions and reducers (#212)
• feature(checkout): Add address form to checkout flow (#226)
• test(redux): Add tests for redux actions (#239)

v1.1.0 -- Legacy "Theme" Release

This is intended to be the final "minor" release on the existing PWA Studio architecture. Those who are working on projects currently based on master can continue to open pull requests against master if they are hotfix-sized changes, meaning that they fix bugs or performance issues, and do not change any public APIs or expected behaviors.

Significant Changes

There is no established prior release to which to compare, so this changelog reflects a diff of the last month of merged changes.

• chore(cicd): Removed Greenkeeper to increase test coverage before automating package updates
• chore(community): Added Community Contributors
• chore(cicd): Switched Lerna to "fixed" mode so all packages share a version
• feat(dev): Added root-level NPM scripts to ease common development modes
• chore(dependencies): Refactored developer dependencies to root as much as possible
• fix(compat): Changed Babel settings to address later browsers
• cleanup(peregrine): Removed unused Peregrine Simulators
• fix(peregrine): Handled absence of Error.captureStackTrace
• refactor(buildpack): Refactored PWADevServer to make SSL and hostnames optional and generate hostnames differently
• fix(buildpack): Fixed duplicated dependencies bug in MagentoRootComponentsPlugin
• fix(buildpack): Added better error reporting for SSL cert generation problems
• docs(peregrine): Added documentation for Peregrine utilities and components
• docs(buildpack): Added documentation for Buildpack utilities, specifically PWADevServer
• docs: Added Basic Concepts documentation for CSS Modules
• docs(venia): Updated Venia setup docs
• feat(venia): Added browser-routed Link elements to navigate between pages
• chore(venia): Adjusted Webpack config for clearer reporting

Acknowledgments

Thanks to all our community contributors, core engineers, documenters, and managers for helping us to formalize our process and take the next big step.