Important: These instructions will not work with projects generated after November 2018, but we've left them here in case you still need to refer to them.
The latest installation instructions can be found on our new Getting Started page.
This guide will show you how to install and configure all the software you’ll need to start building a Progressive Web App (PWA) with the Mobify Platform.
Required software #
If you haven’t already, you’ll need to install the following software:
- Git (usually preinstalled on Linux and Mac)
- Node Version Manager (nvm)
- Node 8.10.0
- To install with Node Version Manager, run
nvm install 8.10.0
- To install directly, download the 8.10.0 release from the Node.js archive
- To install with Node Version Manager, run
Windows users: Always use the Git Bash terminal application that is installed with Git for Windows to run any terminal commands that you see in our documentation. Do not use Command Prompt (cmd.exe) or PowerShell.
Recommended software #
We strongly recommend that you also install the following software:
- Google Chrome and the following extensions:
- Visual Studio Code from Microsoft and the ESLint extension from Dirk Baeumer.
Project files #
Every project using Mobify’s Progressive Mobile Web technology begins with a set of project files, including:
- The Progressive Mobile Web Software Development Kit (SDK)
- A fully functional PWA for ecommerce based on a fictional store called Merlin’s Potions
- Open-source libraries
- A development server for previewing your work
- Scripts for automating common tasks, such as generating boilerplate code for pages and components
Most of the time, the project files will already be generated for you, and you will need to ask someone from your team to give you access to them.
If you have been asked to generate the project files, please follow the instructions in the Generating a Project guide.
Cloning a Mobify repository #
Once the project files have been generated, the files are usually kept in a source code respository–often on GitHub.
Here’s how to clone the GitHub repository that we use for our Mobify training courses. The steps will be the same for any other GitHub repository.
- Verify that you have been given access to the pwa-training repository on
(You will see a 404 page until you have been given access to it by Mobify.)
- Open a terminal window
- Change to the directory where you want the project files to go
- Run this command:
git clone https://github.com/mobify/pwa-training.git
Trusting Mobify’s digital certificate #
Now that you’ve cloned or generated your project files, you need to configure your system to trust Mobify’s self-signed digital certificate. Otherwise, you will see HTTPS errors in your browser that will prevent you from doing local development.
Here’s how to trust the certificate on different operating systems:
- Open a Bash terminal
- Run the following commands from the
webdirectory inside your project directory:
#Install libnss3-tools for managing certs. (It's likely that these are already installed.) sudo apt-get install libnss3-tools #Add trust for dev webserver self-signed SSL certificate certutil -d sql:$HOME/.pki/nssdb -A -t "P,," -n dev-server/localhost.pem -i dev-server/localhost.pem
- Open your terminal and go to the
webdirectory inside your project directory
open dev-server/localhost.pem. The Keychain Access app will open.
- Add the certificate to your login keychain
- In the Keychain Access app, search for
Mobify Development Server
- Right click it and select Get Info
- Expand the Trust section
- Set Secure Socket Layer (SSL) to Always Trust
- Close the info window. You will need to enter your password.
- Select Start Menu → Run and enter
- Select File → Add/Remove Snap-in
- Select Certificates and click Add
- Select Computer Account and click Next
- Select Local Computer and click Finish
- Click OK to close the Add or Remove Snap-Ins dialog
- Expand the Certificates node and right-click on the Trusted Root Certification Authorities node
- Select All Tasks → Import
- Import the
web\dev-server\. Leave all other settings as is while importing.
- After clicking Finish, you should get an alert saying “The import was successful”
- Exit the window. You do not need to save the console settings, so click No when prompted.
Previewing your new project #
Before you can preview your project, you must run the following commands in a
terminal to install the Node packages that your project depends on. Substitute
the name of the directory that was cloned or generated for
your-mobify-project-id in the commands listed below. For example, if you
cloned the project files for a Mobify training course, the first command you’ll
run will be
cd your-mobify-project-id cd web npm install
After the Node packages are installed, run the following command to start your development web server:
Warning: Please make sure the digital certificate is configured correctly. You can verify it by opening https://localhost:8443 in Chrome, the security warning indicates the certificate has not been correctly configured.
Now that your development web server is running, look for the preview URL in your terminal and copy it. (You may need to scroll up in your terminal history to find the preview URL.)
For previewing your project during local development, we strongly recommend using Google Chrome because of its accurate emulation of mobile devices and its strong debugging tools.
Now that you’ve copied the preview URL, paste it into Google Chrome, but don’t click the Preview button yet. First, open the Chrome Developer Tools and choose a mobile device to emulate.
When you click the Preview button, a cookie will be created based on your user agent. If click the button without mobile emulation and switch to mobile emulation later, the new mobile user agent will not match the user agent recorded by the cookie. This will cause the PWA loading script to fail, and you will see the regular production website instead of your local PWA build. You can fix this by loading the preview URL again and clicking the button while in mobile emulation mode.
Now you’re ready to hit the Preview button. The Merlin’s Potions home page will appear. (If it does not look like the screenshot below, see the troubleshooting section at the end of this guide).
Now you can preview the changes to your project as you work!
If you encounter errors in your terminal while starting your development server: #
node -vfrom your terminal
- Check that the version is
v8.10.0. If you have a different version of Node installed:
- Install Node Version Manager (nvm)
nvm install 8.10.0or download the 8.10.0 release from the Node.js archive
- Delete your
- Repeat the steps listed in previewing your new project
- Don’t forget to check your Node version before running
If you see a blank, white screen while loading your PWA: #
- Clear your cookies for
- Go to the terminal running your development server
control + cto stop the development server
- Copy the preview URL from the terminal output
- Paste the URL into your browser
- Emulate a mobile device using your browser’s developer tools. You must do this before the next step!
- Click the Preview button
If you see a purple header instead of a blue one or you see the desktop site instead of the PWA: #
- Open Chrome’s DevTools
- Go to application tab (in the DevTools window)
- Click the Clear site data button
- Verify that your local development server is running
- Copy the Preview URL from the terminal again
- Load the Preview URL (but don’t click the Preview button yet!)
- Emulate a mobile device using Chrome’s DevTools
- Click the Preview button