Buildtime architecture

The build architecture of PWA Studio is the system used to compile JavaScript and CSS source code into a production-ready PWA storefront application.

Magento store dependency

PWA Studio is part of Magento’s service-oriented architecture vision. This vision minimizes dependencies by separating the merchant-facing store admin and the shopper-facing storefront application. Separating these two applications minimizes the dependencies between them.

The Venia build system respects this principle by running the build process independent from the Magento core application. However, the build system does use the Magento API at compilation time for additional validation and optimization of storefront code.

Repository organization

Unlike Magento themes, the source code for a PWA Studio storefront does not need to be located within the Magento application code. A PWA Studio storefront and its backing Magento server are two separate applications, so their codebase is separate from each other.

The Venia concept storefront uses the yarn package for dependency management, but storefronts built using PWA Studio can also use NPM to manage dependencies and run scripts.

Early adopters of PWA Studio have cloned the pwa-studio repository and made direct customizations to the Venia concept source. This can lead to conflicts when updating to the latest version of the codebase. The preferred approach is to add PWA Studio tools and libraries as dependencies in a project.

Build pipeline

The build pipeline is the mechanism that consumes the project source code to generate production-ready files. This process includes code transpilation and smart script bundling. Like most modern Web compilation tools, it is built on NodeJS.

The main tools used for the build pipeline are Babel and Webpack. The Buildpack library provides a convenient API for configuring these tools, but the underlying API for building a Magento PWA is a direct configuration of Babel and Webpack.

The Venia example storefront project contains an opinionated build pipeline setup, using Buildpack’s configureWebpack API, but developers can also use the PWA-Studio build libraries and configurations to define custom pipelines.

Venia build steps

The following sections provide insight into the processes that make up Venia’s build pipeline.

Starting a build

Venia’s build process begins at the command prompt. It is compatible with OSX and most Linux environments that use a bash shell.

Windows support is an ongoing project.

PWA Studio projects use NPM scripts to organize frequently used commands. These yarn run commands are found in the scripts section of the Venia storefront’s package.json file.

Use the build command to start the build process:

yarn run build

Cleanup step

The build process runs a clean script to remove old artifacts from the Venia concept’s dist directory before generating the code.

Environment validation

The next phase uses the buildpack load-env command to load and validate the .env file, which describes the store project configuration. This file is found in the root directory of the Venia concept project.

If there is no .env file in your project, create one with the buildpack create-env-file command.

Query validation

After the environment validation phase, the build runs the validate-queries script. This script uses the graphql-cli-validate-magento-pwa-queries tool to analyze the GraphQL queries in the project and validates them against the schema downloaded from the configured Magento instance.

The connected Magento instance is defined by the MAGENTO_BACKEND_URL environment variable.

Webpack execution

The final step in the build process uses the webpack CLI (webpack) to process files into bundles. The webpack.config.js file in the storefront project’s root configures webpack to use external tools, such as Babel and Workbox, during file processing and bundle creation.

The artifacts generated by webpack are located in the dist folder. These are static files ready to be served from an HTML document’s app shell.

When a browser loads these files, it launches a single-page application that is the Venia storefront.

Other build features

The following build features are used mainly in a development environment. They are not part of the normal production build process.

Watch mode

The watch script launches a development server and a persistent compiler process that monitors the source code for changes. When a change is detected, it initiates an incremental rebuild instead of a full build to keep the application in the browser up to date.

This feature allows you to make edits in the code and see the changes in the application without going through the full build process.

Linting and testing

The Venia concept project also contains scripts for formatting (yarn run prettier), style analysis (yarn run lint), and running unit tests (yarn test).

Use these scripts to keep your codebase well-formatted and test functionality.