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.

Lerna Packages

This repository includes the following packages managed by lerna:

• venia-concept - Reference/Concept Storefront
• pwa-buildpack - Build tooling
• peregrine - eCommerce Component Library
• upward-js - Reference implementation of the UPWARD specification
• upward-spec - UPWARD specification and test suite

Other Packages

This repository also includes modules that are not managed by Lerna, because they are not meant to be distributed via NPM, and/or they should not have their dependencies centrally managed by Lerna.

• pwa-devdocs - Project source for the documentation site

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)

One simple way to obtain Magento 2.3 is using the Core Contributor Vagrant box.

Using the Vagrant Box

1. Clone the https://github.com/paliarush/magento2-vagrant-for-developers/ repository and follow the setup instructions.

2. Make sure that all sample data auto-installation parameters in the config.yaml file are disabled.

3. When installation is complete, then install the Venia sample data. Copy this shell script and save it in your Magento root directory as installVeniaSampleData.sh.

4. Run vagrant ssh to login to the Magento VM.

5. Run bash installVeniaSampleData.sh. The Venia sample data should install, and the Vagrant host is ready to use.

6. Update your .env file in PWA Studio to set MAGENTO_BACKEND_URL to the URL of the Vagrant box.

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. Copy packages/venia-concept/.env.dist to packages/venia-concept/.env
5. Uncomment the line for MAGENTO_BACKEND_URL in packages/venia-concept/.env, and set MAGENTO_BACKEND_URL to the fully-qualified URL of a Magento store running 2.3.
6. On your first install, run npm run build from package root.
7. To run the Venia storefront development experience, run npm run watch:venia from package root.

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/.env.dist.

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.

My browser complains that the connection is not secure

Generating certificates is handled by devcert. If you're on a Linux machine make sure that libnss3-tools (or whatever the equivalent is) is installed on your system. Further information provided in this section of the devcert readme.

To test whether your queries are up to date, run npm run validate-queries 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.