UPWARD is an acronym for Unified Progressive Web App Response Definition. Depending on the context, UPWARD can refer to the definition file or server implementation.
An UPWARD definition file describes how a server delivers and supports an application. The file provide details about server behavior using platform-independent, declarative language. This lets an application run on top of any UPWARD-compliant server written in any language because the application is only concerned about the HTTP endpoint behavior from the UPWARD server.
An UPWARD server uses an application's definition file to determine how the server should handle a request and build the response for it.
The main purpose of an UPWARD server is to do the following:
- Receive a request from the application
- Determine the appropriate service or process to handle the request
- Get the results from the service or process
- Build the HTTP response from the results
- Send the response back to the application
PWA Studio provides two UPWARD server implementations:
upward-php: A PHP implementation of an UPWARD server used in conjunction with the magento2-upward-connector. This is mainly used in production environments where the storefront project code and Magento 2 backend code are on the same server.
UPWARD server characteristics#
UPWARD server implementations have the following characteristics:
Requests sent to an UPWARD server are idempotent. This means that a request to the server has no side effects, so it does not matter if you send the same request multiple times to the server.
Provide a simple communication strategy for services#
All services provided by the server are available through a single data exchange strategy, such as GraphQL. Limiting the methods of communication between a PWA and its resources simplifies PWA development. It removes the responsibility of knowing how to work with different external resources and allows developers to concentrate on using a single, familiar technology.
Contain no business logic#
Having business logic spread across multiple architectural layers is an antipattern that harms testability. The declarative nature of an UPWARD specification prevents the creation of arbitrary business logic on the server. It pushes this logic into re-usable templates or queries, the frontend application, or the backend services, so it cannot hide in the middle tier.
Since an UPWARD server cannot contain business logic, it also cannot hold a local state. This responsibility is also moved to the frontend or backend layer.
UPWARD server implementations must serve data over HTTPS to protect the information and privacy of PWA users.
UPWARD and PWA Studio storefronts#
An UPWARD server sits between a PWA Studio storefront and its resources, such as an Adobe Commerce or Magento Open Source application. It acts as the backend service for the application that proxies requests to connected services or serve static files.
See RATIONALE.md in the
upward-spec package for a more detailed explanation of the need for an UPWARD server.
UPWARD in Venia#
When you set up a new project, the scaffolding tool creates an UPWARD definition file called
upward.yml in the new project.
This file contains references to a
veniaResponse object defined in the
To deploy your storefront application, pass this file onto an UPWARD server to make it accessible to users.
Changing the default Venia responses#
To change the default UPWARD server behavior from a Venia-based project, you must change the configuration file.
The most direct way to do this is by editing the
upward.yml file and changing the values for the
You can refer to the
upward.yml file in the
venia-ui package to see the default instructions and make the necessary changes.
You can also tap into the
transformUpward target in your storefront or extension project to make changes in a more programmatic language.
upward-security-headers extension for an example of this approach.