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.