Local ScandiPWA Composer Package Setup

ScandiPWA Composer package installation and upgrade for the Core Team

1. Why

2. How to install

3. How to update

4. Version configuration

Why

Composer always is trying to install the latest possible version of a package. This means, that if your composer.json file has packages with version ^2.1.0, it matches 2.1.1 and 2.1.99.

But since ScandiPWA releases are backward incompatible and during the release cycle we can have multiple backend module releases, this can lead to an issue when a new ScandiPWA setup can install latest composer package that will crash the project.

To solve this issue a developer have to install the latest ScandiPWA frontend. But it may not be possible since it isn't released yet, or for some other reasons. Thus we decided to use strict composer package versions in order to lock changes for a specific ScandiPWA release.

But this leads to another issue for a ScandiPWA Core Team. Since we are developing composer packages locally, we used to specify a local package version to be greater than it is in the packagist.org. So the Composer would prefer the local version over the Packagist version. This will not happen when we lock the versions.

The solution for the Core Team is to use branch alias.

How To Install

In order to install the local package, first we should configure repository:

composer config repo.repo-name path path/to/repo

Then we should lookup the required version of the package in the theme's composer.json. Next is to launch the following command:

composer require "vendor/package dev-master as x.x.x"

For example, in order to install the scandipwa/catalog-graphql version 3.1.24 do the following:

composer require "scandipwa/catalog-graphql dev-master as 3.1.24"

This will add a package to the root composer.json and symlink the package in the vendor directory.

How To Update

In order to update ScandiPWA composer packages the Core Team can use the following command:

composer update "scandipwa/*"

But if a package, that is installed from local directory, has updated in the theme's composer.json, you will have an error like this:

Your requirements could not be resolved to an installable set of packages.

  Problem 1
    - Root composer.json requires scandipwa/scandipwa ^0.0.1 -> satisfiable by scandipwa/scandipwa[0.0.1].
    - scandipwa/scandipwa 0.0.1 requires scandipwa/catalog-graphql 3.1.25 -> found scandipwa/catalog-graphql[dev-master] but it does not match the constraint.

In order to solve it, you have to head to the root composer.json and update the version manually. Then do the update command from the above.

Version Configuration

Please note that you don't have to edit the package composer.json and specify it's version. The dev-master is already the latest version you could have.

If you experiencing some issues with it, you might want to configure the root composer.json like this:

"minimum-stability": "dev",
"prefer-stable": false

When you switch the branches in the package while development, there shouldn't be any issue with the version you have installed, since the package directory is symlinked and will sync all changes to the vendor directory. But if you encounter any issue because you have a different branch, just change dev-master to dev-branch-name in the root composer.json.

Same issue will happen when you have a different default branch, like main instead of master.

In order to check whether the ScandiPWA package is symlinked, you can launch the following command:

ls -lF vendor/scandipwa

It will display all symlinks and their targets.