PWA Studio

Magento PWA Studio is a collection of tools that lets developers build complex Progressive Web Applications on top of Magento 2 stores.

Documentation

PWA Studio documentation site

Community Contributors

The PWA Studio project welcomes all codebase and documentation contributions. We would like to recognize the following community members for their efforts on improving the PWA Studio project:

mage2pratik	vdiachenko	jissereitsma	rossmc

bobmotor	gavin2point0	neeta-wagento	mtbottens

Jakhotiya	JStein92	bgkavinga	philwinkle

bobbyshaw	matthewhaworth	shakyShane	Igloczek

mhhansen	rowan-m	artKozinets	camdixon

For more information about contributing to this repository, see the Contribution guide.

About this repository

To ease local development, testing, and versioning, the PWA Studio project uses a monorepo, with package management orchestrated by lerna. All packages are versioned in a single repo, but released to npm as independent packages.

Packages

This repository includes the following packages:

• venia-concept - Reference/Concept Storefront
• pwa-buildpack - Build tooling
• peregrine - eCommerce Component Library
• pwa-module
• pwa-devdocs - Project source for the documentation site
• upward-js - Reference implementation of the UPWARD specification
• upward-spec - UPWARD specification and test suite

Quick Setup

PWA Studio 2.0 requires much less setup than PWA Studio 1.0. The UPWARD architecture means that the Magento instance does not need to be configured to use your project as a theme. Instead, you connect to your Magento instance by simply specifying its URL in your environment.

Obtain Magento 2.3

1. Make sure the Magento instance you're using is set to development mode, and has the latest 2.3.

   • You need development mode for GraphQL introspection queries to work.
   • The latest codebase will have the most up-to-date GraphQL schema.

2. Ensure that the Venia sample data is installed on the Magento instance. (TODO: painless instructions for the Composer commands to do that)

Install Dependencies

Note: You must have a version of node.js >= 8.0.0, and a version of npm >= 5.0.0. The latest LTS versions of both are recommended.

Follow these steps to install the dependencies for all the packages in the project:

1. Clone the repository.
2. Navigate to the root of the repository from the command line
3. Run npm install
4. Watch the bootstrapping take place.
5. Create a packages/venia-concept/.env file (or set environment variables manually)
6. Set the environment variable MAGENTO_BACKEND_DOMAIN to the URL of the backing Magento instance you are using
7. To run the Venia storefront development experience, run npm run watch:venia from package root.
8. To run the full PWA Studio developer experience, with Venia hot-reloading and concurrent Buildpack/Peregrine rebuilds, run npm run watch:all from package root.
9. To run the staging environment, which uses more compressed assets and more closely reflects production, run npm run stage:venia from package root. (This requires that you first run npm run build to generate the artifacts being served.)

Troubleshooting

When I run the developer mode, I get validation errors

Make sure you have created a .env file in packages/venia-concept which specifies variables for your local development environment. You can copy from the template packages/venia-concept/example.env.

Venia queries to GraphQL produce validation errors

Venia and its GraphQL queries may be out of sync with the schema of your connected Magento instance. Make sure the Magento instance is up to date with the 2.3 development branch, and your copy of this repository (or your dependency on it) is up to date.

To test whether your queries are up to date, run npm run validate:venia:gql at project root.

Things not to do

• Our monorepo is set up so that npm install can cross-link dependencies (such as Venia's dependency on Buildpack) without any extra tools. Do not run lerna bootstrap.
• All devDependencies are installed in the repository root. This means that all scripts must be run from repository root; otherwise, the locally installed CLI commands they use will not be available.
• Production dependencies are sometimes installed in child packages, but for some projects, such as Venia, it makes no sense to have production dependencies, because of bundling.
• Don't check in a big change to package-lock.json, and don't check in any package-lock.json files but the root one.
• Make sure to run npm run prettier and npm run lint before any commit you intend to push. You may want to set up a Git hook for this.