Previously, ScandiPWA used a docker setup. This configuration is now considered legacy, and you can easily upgrade to the new create-scandipwa-app setup.

Before You Start

Before migrating, make sure that you have backed up the current state of the project, preferrably with a version control system such as Git. Verify that your system meets the requirements.

Creating the New Setup

In the new setup, the theme is developed in the localmodules directory. If it does not exist yet, create it in your project's source directory:

mkdir src/localmodules
cd src/localmodules

yarn create scandipwa-app <your-app-name>

npx create-scandipwa-app <your-app-name>

cd <your-app-name>

git clone https://github.com/scandipwa/scandipwa
cd scandipwa

yarn

Run the compilation process in magento mode:

BUILD_MODE=magento yarn start

cd <your-app-name>
BUILD_MODE=magento npm start

Switching to the New Setup

Now the new theme is created, but we need to reconfigure the project to use it instead of the old theme. The changes we need are easiest to make from within the docker container, so start the app and gain bash access to it:

From the project root
dc up -d
inapp bash # to enter the app container

Removing the Old Setup

Previously, our theme was installed via the scandipwa/installer package, but we no longer require it. To clean up and avoid confusion, remove it:

(from within the app container)
composer remove scandipwa/installer

Adding the New Setup

We will install the newly-created theme by taking advantage of Composer's ability to install from local repository sources. First, we add our theme as a local repository source. This will alter composer.json to add a new item in the repositories field:

(from within the app container)
composer config repo.theme path localmodules/<your-app-name>

(from within the app container)
composer config repo.theme path localmodules/scandipwa/packages/scandipwa

Next, we install our theme by using require. This will resolve the package to the localmodules directory we configured above:

(from within the app container)
composer require scandipwa/<your-app-name>

(from within the app container)
composer require scandipwa/scandipwa

Making the Switch

Run the upgrade command and disable full-page caching:

(from within the app container)
bin/magento setup:upgrade
bin/magento cache:disable full_page

It is now time to enable the new theme. In the Magento admin panel, navigate to Content > Design > Configuration. Edit the scope you want to change (typically the most general one in the list), and select the new theme. Finally, flush the cache:

(from within the app container)
bin/magento cache:flush

Migrating the Code

You can now copy the code from your old theme into the new setup. However, note that the file structure has changed to improve organization, and you will need to make adjustments:

Once your code has been copied, you can delete the old location of your theme. Your app should now work as expected with the new setup!

Extension mechanism changes

The extensions are no longer Composer packages, but NPM packages. Thus, the frontend and backend (Magento 2) extension are now separated. Internal file structure is also different. Previously, the extensions had to be created under then scandipwa/app folder of the composer package, now, you can simply put your code into extension's src folder. Inside of this folder, the file-structure is unchanged.

You can read more about new extension registration sytax here, it replaces the legacy scandipwa.json file.