Setting up the theme with remote M2 server

While using this setup:

1. ScandiPWA theme is run by wepack-dev-server

2. All /graphql requests are sent to your remote server

3. There is an Nginx routing the requests

Note:

it is impossible to test the website in production mode (of the webpack build). This is the main downside of this approach.

Note:

the https://scandipwa.local wont be available. The PWA features will not function.

In code examples, you might stumble across such declaration:

# to clone the fork
git clone [e-mail]:<YOUR GITHUB USERNAME>/scandipwa-base.git

Note:

the <YOUR GITHUB USERNAME> is not a literal text to keep, but the “template” to replace with the real value.

Before you start

1. If you plan to make changes to the theme make sure to create GitHub account, or sign in into existing one.

   1. Make sure you have a SSH key assigned to your GitHub account, and you current machine has the same key. Read how to setup SSH key on GitHub.

   2. Make sure to fork scandipwa-base repository. Read how to fork repository on GitHub.

2. Make sure your remote server has ScandiPWA installed on it

   The Magento theme could be different, but ScandiPWA modules should be installed and enabled. Read more how to install the ScandiPWA on existing Magento 2 server here.

   In case you do not have the ScandiPWA instance yet, try completing this setup using our instances: demo.scandipwa.com or scandipwapmrev.indvp.com. You can also request your own cloud instance by composing a mail to [e-mail].

3. Make sure you have node available on you machine. To test this, run:

node -v # should be 10^

In case this command resulted in error, install node using the official guide. Prefer nvm installation to get NODE version 10 specifically.

Time to decide - core or custom?

The theme can be developed in two modes - as contribution into core theme, or as custom theme development on top of core theme. Let’s review each one:

For ScandiPWA core contribution

1. Get the copy of base-theme - clone your fork, or clone the original repository.

# to clone the fork
git clone [e-mail]:<YOUR GITHUB USERNAME>/base-theme.git

# to clone the original repository
git clone [e-mail]:scandipwa/base-theme.git

# to clone via HTTPS (not recommended)
git clone https://github.com/scandipwa/base-theme.git

Note:

sometimes, after the repository is cloned, the git chooses the master branch as default. This is the legacy (incorrect) default branch in case of base-theme. Please make sure you are using 3.x-stable. You can do it using following command:

git status # expected output `On branch 3.x-stable`

If any other output has been returned, execute the following command to checkout the correct branch:

git checkout 3.x-stable

Later, for development purposes any new branch created from 3.x-stable can be used.

2. Add following key to package.json:

{
    // ...
    "proxy": "https://demo.scandipwa.com"
}

Note:

Do not commit this change, if planning to use with docker.

3. From the cloned theme folder, execute following:

npm ci # install dependencies
npm run watch-core

For custom theme development

Note:

initial setup must happen on real instance. After the bootstrapped theme is committed to the repository, you can proceed with this installation

1. Inside, clone your already bootstrapped scandipwa-base package with theme already bootstrapped. The theme file should be present in <REPO SOURCE>/src/app/design/frontend/<VENDOR>/<THEME>/.

git clone <CUSTOM THEME REPOSITORY GIT REMOTE>

2. Then, get matching scandipwa/source package version from GitHub (lookup the required version in src/composer.lock, lookup scandipwa/source package) and clone it to vendor folder. Make sure the folder is present.

mkdir -p src/vendor/scandipwa/source
git clone [e-mail]:scandipwa/base-theme.git src/vendor/scandipwa/source

3. Add following key to package.json, located in your theme’s folder (<REPO SOURCE>/src/app/design/frontend/<VENDOR>/<THEME>/package.json):

{
    // ...
    "proxy": "https://demo.scandipwa.com"
}

Note:

Do not commit this change, if planning to use with docker.

4. From the custom theme theme folder, execute following:

npm ci # install dependencies
npm run watch

Time to open the site

1. Open your favorite browser, i.e. Google Chrome

2. Open un-secure localhost:3003 domain

Note:

in case you are getting CORS issues printed out in console, make sure to run chrome with disabled web-security flag set.

Something does not work?

Follow this simple algorithm:

1. Refer to the FAQ page. It most probably already has the solution to your problem.

Note:

the Docker setup related issues are also mentioned in this document.

1. If the issue still persists, join our community slack, and feel free to ask questions in #pwa_tech public channel.

2. Alternatively create an issue on GitHub - however, the response time there will be a little-bit longer than in community Slack.