Menu
Menu Sheet Overlay
Search
Search Sheet

Quick Start

    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:

    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:

    Project files #

    Every project using Mobify’s Progressive Mobile Web technology begins with a set of project files, including:

    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.

    1. Verify that you have been given access to the pwa-training repository on GitHub.
      (You will see a 404 page until you have been given access to it by Mobify.)
    2. Open a terminal window
    3. Change to the directory where you want the project files to go
    4. 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:

    Linux #

    1. Open a Bash terminal
    2. Run the following commands from the web directory 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
    

    macOS #

    1. Open your terminal and go to the web directory inside your project directory
    2. Run open dev-server/localhost.pem. The Keychain Access app will open.
    3. Add the certificate to your login keychain
    4. In the Keychain Access app, search for Mobify Development Server
    5. Right click it and select Get Info
    6. Expand the Trust section
    7. Set Secure Socket Layer (SSL) to Always Trust
    8. Close the info window. You will need to enter your password.

    Windows #

    1. Select Start Menu → Run and enter mmc.exe
    2. Select File → Add/Remove Snap-in
    3. Select Certificates and click Add
    4. Select Computer Account and click Next
    5. Select Local Computer and click Finish
    6. Click OK to close the Add or Remove Snap-Ins dialog
    7. Expand the Certificates node and right-click on the Trusted Root Certification Authorities node
    8. Select All Tasks → Import
    9. Import the localhost.p7b file in web\dev-server\. Leave all other settings as is while importing.
    10. After clicking Finish, you should get an alert saying “The import was successful”
    11. 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 pwa-training.

    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:

    npm start
    

    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.)

    Dev server output showing preview URL (highlighted)

    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.

    Google Chrome emulating a mobile device

    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!

    Mobify Preview

    Troubleshooting #

    If you encounter errors in your terminal while starting your development server: #

    1. Run node -v from your terminal
    2. Check that the version is v8.9.4. If you have a different version of Node installed:

    If you see a blank, white screen while loading your PWA: #

    1. Clear your cookies for localhost and merlinspotions.com
    2. Go to the terminal running your development server
    3. Press control + c to stop the development server
    4. Run npm start
    5. Copy the preview URL from the terminal output
    6. Paste the URL into your browser
    7. Emulate a mobile device using your browser’s developer tools. You must do this before the next step!
    8. 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: #

    1. Open Chrome’s DevTools
    2. Go to application tab (in the DevTools window)
    3. Click the Clear site data button
    4. Verify that your local development server is running
    5. Copy the Preview URL from the terminal again
    6. Load the Preview URL (but don’t click the Preview button yet!)
    7. Emulate a mobile device using Chrome’s DevTools
    8. Click the Preview button