Important: Our installation instructions have been updated to reflect many new technologies released starting in November 2018. If you need to install a project that was generated before November 2018, you can still access the old Quick Start guide.
Supported operating systems
The Mobify Platform supports the following operating systems:
- macOS 10.13 or greater
- Windows 7 or greater
- Ubuntu Linux 18.x or greater
We recommend the following for your hardware setup, at a minimum:
- 16 GB RAM
- Solid-state drive (SSD)
- 2 or more CPU cores
Installing required software
Before you start development, you’ll need to install the following software on any computers you plan to use for development:
Download our recommended version of Node, version 8.10.0:
(These links will directly download the compatible
.msifile for your machine.)
Run the installer and complete the setup instructions after downloading.
When prompted by the installer, accept the default option to also install the Node.js runtime and Node Package Manager (npm), and to add the runtime to your path. This will give you npm version 5.6, but we will overwrite it later with our recommended version, npm 5.7.1.
Open your Command Prompt and run
Confirm that Node 8.10.0 has been installed successfully
- Open your Command Prompt and run
npm install -g email@example.com
npm -vto confirm that npm 5.7.1 has been installed successfully
- Download our recommended version of Node, version 8.10.0. (This link will directly download the compatible
- Run the installer and complete the setup instructions after downloading.
- Open your terminal and run
- Confirm that Node 8.10.0 has been installed successfully.
- Go to this direct download link for Node 8.10.0
- Download the right binary for your machine. (For example, if you have a 64-bit Intel machine, you would choose the x64 file.)
- Extract the binaries and complete the setup instructions after downloading.
- Open your terminal and run
- Confirm that Node 8.10.0 has been installed successfully.
Installing your project files
Next, we'll install a set of project files and get your development server running on your machine. If you’re working on multiple machines, you’ll want to run through these steps on each one.
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 don't already have a set of project files to work from, please contact Mobify to request access to our
Now we need to download and install package dependencies using Node Package Manager (npm) by running the following command from your project directory:
npm install --quiet
Note It might take a few minutes before you see any activity in the terminal, so don’t cancel the process until it finishes. Thanks for your patience!
Additional steps for tag-loaded projects
Tag-loaded PWAs require a few additional steps before setup is complete. These include trusting the self-signed certificate, installing the Mobify Tag, and installing the Mobify Service Worker.
Trusting the self-signed certificate
For tag-loaded projects, the development server uses a self-signed certificate to serve pages over HTTPS.
If you don't trust the certificate on your machine, you will see HTTPS errors in your browser that will block you from doing local development.
Here’s how to trust the certificate on different operating systems:
- 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
packages\pwa\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.
- Open your terminal and go to the
packages/pwadirectory inside your project directory
open dev-server/localhost.pem. The Keychain Access app will now 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.
- Copy the address of the bundle location (for example,
192.168.0.1:8443/loader.jsfor LAN previewing)
- Open a new tab and go to the copied address
- A warning screen will appear saying "This Connection Is Not Private"
- Click Show Details
- Click Visit this website
- Confirm that the certificate has been accepted and that you access your project in the tab you opened previously
- Open a Bash terminal
- Go to the
packages/pwadirectory inside your project folder, and run the following commands:
# Install libnss3-tools for managing certs: sudo apt-get install libnss3-tools # Initialize a database of certificates mkdir -p $HOME/.pki/nssdb # Pass in a password (default we’re doing below is no password) certutil -d $HOME/.pki/nssdb -N --empty-password # Add trust for the cert: certutil -d sql:$HOME/.pki/nssdb -A -t "P,," -n dev-server/localhost.pem -i dev-server/localhost.pem
We recommend closing the terminal window and re-opening a new one to ensure your changes are applied.
Installing the Mobify tag
Before you can start development on a tag-loaded PWA, you, or someone on your team, will need to insert the Mobify tag into your site’s HTML.
Mobify Cloud project
Check that you have a project created for you in Mobify Cloud. If your project does not appear, contact Mobify support to make sure that the project has been created and that you have been granted access to it as a team member.
After you have access to Mobify Cloud, make sure you can access your project-specific Mobify tag by logging in to Mobify Cloud, then clicking the Tag tab on the left-hand side navigation menu. This page provides you with the code you will need to add to your site's HTML.
To complete the setup, you will need to change the HTML sent by your web server to include the Mobify tag. If you’re not sure how to do this, ask your site’s administrator for help.
Send Mobify support a list of any development, testing, and production environments. A Mobify tag with multiple environments in place will be set up accordingly on Mobify Cloud, allowing you to select a target environment to deploy bundles of code when you’re ready to publish. If you’d like to add new environments later, a new tag will need to be generated after Mobify adds the new target. We do not need to replace old tags that have already been installed.
Steps to install the Mobify Tag
The installation process for the Mobify tag will be a bit different depending on your site's ecommerce backend:
If you’re working with a Salesforce Commerce backend, you can skip these steps because Mobify’s cartridge will install the Mobify tag for you. For more details, see Commerce Integrations
If you’re working with an SAP Hybris backend, you can skip these steps because Mobify’s extensions for SAP Hybris will install the Mobify tag for you. For more details, see Commerce Integrations
<!doctype> <html> <head> <title>Example Title</title> <meta name="title" content="Example Meta Title"> <meta name="description" content="Example Meta Description"> <!-- 📍 The tag goes here, early in the <head>, after SEO tags: --> <!-- MOBIFY --> <!-- ... --> <!-- END MOBIFY --> </head> <!-- ... --> </html>
- Early in the
- Below SEO tags such as
Installing the Mobify service worker
Service workers are web browser features that provide PWAs with some of their app-like superpowers, including the ability to work offline and to be installed to users' home screens, just like native apps. To realize the full potential of the Mobify Platform, tag-loaded PWAs will need to install the service worker (it comes pre-configured in server-side rendered projects). The installation steps will depend on your site's ecommerce backend:
If you’re working with a Salesforce Commerce backend, you can skip these steps because Mobify’s cartridge will install the Mobify service worker for you. For more details, see the cartridge section in Commerce Integrations.
If you’re working with an SAP Hybris backend, you can skip these steps because Mobify’s extensions for SAP Hybris will install the Mobify service worker for you. For more details, see the extensions section in Commerce Integrations.
Steps to install the service worker
- Find the code for your worker in your project:
packages/pwa/service-worker-loader.js. Copy its contents.
- On your server, create a worker file called
service-worker-loader.jsthat is available from the root of your domain. For example, if your domain is example.com, the file must be
- Paste the worker’s code (from step one) into the file you just created.
Steps to verify that the worker is installed correctly:
- Open your browser and navigate to the service worker over HTTPS. For example,
if your domain is
example.com, you would open https://example.com/service-worker-loader.js.
- Check the worker opens using HTTPS without errors. Service workers are powerful features that only work over secure connections.
- Check the worker is served exactly from the path
/service-worker-loader.jswithout redirection. Redirects break the worker’s scope by changing the URL where it is registered.
- Check that the contents of the worker on your server exactly match the contents of the worker in your project.
- Check the worker is served using the Content Type
You can see an example of a correctly installed worker by opening this URL in your web browser: https://www.merlinspotions.com/service-worker-loader.js
If it’s not possible to install the service worker during development, workarounds are possible using Charles, an HTTP Proxy application.
In production, the service worker must be installed correctly. To get help with installation during production, contact firstname.lastname@example.org.