Migrating to CMA & CSA
If you have already set up ScandiPWA with docker, you can upgrade to the new setup
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 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.
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
If you want to use the ScandiPWA theme
If you are a ScandiPWA contributor
Now, using the new
create-scandipwa-app
script, you can re-create the theme (replace <your-app-name>
):Using Yarn (recommended):
yarn create scandipwa-app <your-app-name>
Using
npx
(if you don't have yarn):npx create-scandipwa-app <your-app-name>
It will take a few minutes for the script to download the required packages and initialize the theme. When it completes, navigate to the newly-created theme:
cd <your-app-name>
Clone the ScandiPWA repo in localmodules:
git clone https://github.com/scandipwa/scandipwa
cd scandipwa
Install dependencies:
yarn
In the instructions below,
<your-app-name>
will be "scandipwa".Run the compilation process in magento mode:
yarn (recommended)
npm
BUILD_MODE=magento yarn start
cd <your-app-name>
BUILD_MODE=magento npm start
You will need to keep this process running – it continuously re-builds the theme when changes are made. Open a new terminal tab to enter new commands.
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
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
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:If you want to use the ScandiPWA theme
If you are a ScandiPWA contributor
(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:If you want to use the ScandiPWA theme
If you are a ScandiPWA contributor
(from within the app container)
composer require scandipwa/<your-app-name>
(from within the app container)
composer require scandipwa/scandipwa
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
The new theme should now be served on the frontend! For now, it will be the default ScandiPWA theme, because we haven't migrated the cusomized code yet.
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:
Old Path | Changes |
etc registration.php theme.xml
<any other Magento-specific file you have created> | Magento files now moved under a new magento directory for better organization. The new paths are magento/etc , magento/registration.php , etc. |
src/public | Now moved outside src , the new path is public .The file index.production.phtml is renamed to index.php , and index.development.html is renamed to index.html . |
src/config | Removed. The webpack configuration now lives in the @scandipwa/scandipwa-scripts package. To modify this configuration, use build configuration plugins. |
src/app | Now the contents of app are moved to src , and app no longer exists. The new path is src . This was done to create a more shallow and easy to navigate file structure. |
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!
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.A tool for automated extension transformation from the old to the new format is available for use on GitHub.
Last modified 2yr ago