Installing Magento PWA Studio

The Magento Progressive Web App (PWA Studio) is becoming more talked about in the Magento space with some sites already using it in production environments. A Progressive Web App is a web application that uses modern web technologies and design patterns to provide a reliable, fast, and engaging user experience.

PWA studio uses a modern tech stack built in JavaScript using React and GraphQL for querying the data among other technologies.

It essentially splits a Magento site into 2 core areas, the PWA frontend and the Magento admin area. PWA studio handles the frontend which connects to the Magento install via the available APIs and renders the data to the end user. By using the PWA tech stack we can provide a faster and more engaging user experience.

Today I’m going to show you how to get PWA Studio setup with a local Magento 2 install.

Step 1: Project Structure

First setup the project structure. The Magento and PWA Studio files will be contained in separate folders, for now create a new directory to contain our project:

mkdir magento-pwa

Step 2: Download PWA Studio

Next we need to download PWA Studio within our new top level directory using the following command:

# directory magento-pwa/
git clone https://github.com/magento/pwa-studio.git

This will download PWA Studio into the pwa-studio directory.

Step 3: Install Project Dependencies

Now we need to install the project dependencies using yarn.

Note: Don’t use npm install since PWA Studio has been configured with Yarn Workspaces. yarn install needs to be used to properly install, hoist, and cross-link dependencies.

# directory magento-pwa/pwa-studio/
yarn install

Note: At the time of writing PWA Studio requires node v10.x – if you’re on a different version you will be prompted to install the compatible version. I’d recommend using a Node version manager like NVM to easily switch between multiple versions.

Step 4: Download Magento

Now we need to download Magento within our top level directory using the following command:

# directory magento-pwa/
composer create-project --repository=https://repo.magento.com/ magento/project-community-edition:2.3.1 magento

This will download Magento into the magento directory. You should now have the following directories setup:

magento-pwa/
magento-pwa/pwa-studio/
magento-pwa/magento/

Step 5: Install Venia Sample Data

The Venia storefront looks best when running against a Magento 2 backend with the Venia sample data installed. To install we need to copy the following deploy script from PWA Studio into our Magento directory.

packages/venia-concept/deployVeniaSampleData.sh

To copy the file using the terminal run the following command:

# directory magento-pwa/
cp pwa-studio/packages/venia-concept/deployVeniaSampleData.sh magento

Before running the deploy script we need to setup authentication with GitHub, if we don’t do this step it will fail to run.

First copy the auth.json.sample file to a new file:

# directory magento-pwa/magento/
cp auth.json.sample auth.json

Then edit the file in your text editor where we’ll added the credentials in, the file should look something like the following:

{
    "github-oauth": {
        "github.com": "<github-personal-access-token>"
    },
    "http-basic": {
        "repo.magento.com": {
            "username": "<public-key>",
            "password": "<private-key>"
        }
    }
}

For the http-basic object you can get your access keys from your Magento Marketplace account. Please read the documentation on how to create access keys. Once you have them enter the public key for the username and the private key for the password.

For the github-oauth object you need to create a new access token under your GitHub profile, you can follow these steps as a guide:

  • Under your profile click on Developer Settings
  • From here click on Personal Access Tokens > Generate New Token
  • Enter the name of the token e.g Magento PWA, you can leave the scopes as default, click Generate Token
  • Copy the access token into the auth.json file and save

Now we can run the deploy script using the following command:

# directory magento-pwa/magento/
bash deployVeniaSampleData.sh

It will then ask you for the absolute path to your Magento 2 root folder, in our case its the current directory we are in so we can pass a dot:

Please specify absolute path to your Magento 2 instance
Magento root folder: .

Step 6: Install Magento

Now we have everything setup we can go ahead and install Magento using the setup/install command. I have already created a blank database ready for the install, if you need help on how to install Magento checkout my article here.

# directory magento-pwa/magento/
bin/magento setup:install \
--db-host=localhost \
--db-name=magento-pwa \
--db-user=root \
--db-password=root \
--backend-frontname=admin \
--base-url=http://m2pwa.local/ \
--language=en_GB \
--timezone=Europe/London \
--currency=GBP \
--admin-firstname=Magento \
--admin-lastname=User \
[email protected] \
--admin-user=admin \
--admin-password=password1

Confirm your Magento installation works by heading to the url you specified in the browser.

Step 7: Setup PWA Studio

At this stage we have PWA Studio downloaded and Magento installed successfully. At the moment they don’t talk to one another, we now need point the PWA Studio codebase to our Magento installation.

To do this we create a .env file within PWA Studio that sets the MAGENTO_BACKEND_URL variable to our Magento installation.

You can create the .env file and set the MAGENTO_BACKEND_URL value at the same time using the following command:

# directory magento-pwa/pwa-studio/
MAGENTO_BACKEND_URL="http://m2pwa.local/" yarn buildpack create-env-file packages/venia-concept

Notice I am passing my local Magento installation url that we setup in the previous step.

The PWA features requires a HTTPS secure domain, to obtain a trusted SSL certificate we can run the following command which will generate a random hostname and SSL certificate for us:

# directory magento-pwa/pwa-studio/
yarn buildpack create-custom-origin packages/venia-concept

Step 8: Run PWA Studio

If you’ve made it this far congrats! We now have everything in place for us to run the server.

Before running the server, we need to generate build artifacts for Venia using the following command in the PWA root directory:

yarn run build

Now we can run either of the following commands each with their own uses.

Start the Venia storefront development environment:

yarn run watch:venia

Run the full PWA Studio developer experience, which includes Venia hot-reloading and concurrent Buildpack/Peregrine rebuilds:

yarn run watch:all

Generate build artifacts and run the staging environment, which uses more compressed assets and more closely reflects production:

yarn run build && yarn run stage:venia

After running any one of these commands you’ll be given a URL in the terminal where you can browse your application in the browser, it will look something like:

PWADevServer ready at https://magento-venia-concept-quyen.local.pwadev:8382/
GraphQL Playground ready at https://magento-venia-concept-quyen.local.pwadev:8382/graphiql

Note: This is the PWA frontend URL. For accessing the Magento admin URL you will still use the base URL we setup during the Magento installation, in my case it is:

http://m2pwa.local/
http://m2pwa.local/admin/

Wrap up

Hopefully you now have a fully working installation of Magento PWA Studio! I’d recommend reading through the documentation to learn more and check back soon for some future articles.