Articles on: Magento 2 User Guide

MIgrating from manual SSH installation to Composer Installation

Starting with version 1.16.0 of all of our products, we've introduced Composer Installation. This has become the sole available installation method for all WeltPixel Products, including the Google Analytics 4 integration, the Pearl Theme and all other extensions. This means products and new updates will no longer be provided via zip files.

If you already have your WeltPixel product installed via SSH (in the app/code/WeltPixel directory), you'll need to migrate to Composer Installation. There are numerous advantages to this, including:

Significantly increased security
Faster, easier updates
Cleaner codebase and maintainability

The migration process is very simple, and we'll address it in the sections below.

Composer Setup

To gain access to Composer Installation, follow the steps below:

Log in to your customer account on the WeltPixel website
Use the navigation menu on the left to head into My Products.
Find your product and click Enable Composer. The page will refresh.
At the top of the page, you'll see your Composer Configuration Commands.
Run these commands in the root of your Magento 2 project.

Note: Please ensure you perform these changes on a development/staging environment first. Additionally, ensure your Magento instance is in developer mode when doing so. When migrating to production, ensure you have a backup.

To migrate to Composer Installation for individual products and packages (excluding the Pearl Theme), you'll need to remove the existing extension files from the app/code directory. To do this, you can simply remove the entire WeltPixel folder in app/code:

Head into app/code

rm -rf WeltPixel

After the WeltPixel folder is removed, you'll be able to properly install your product(s) via Composer with the installation commands found in your WeltPixel account's My Products section. These are revealed when you click the Enable Composer button. For example, if you want to install the Google Analytics 4 PRO extension via composer, after enabling Composer access via the button, you can run the following command to install the extension, after you head back into the Magento root:

composer require weltpixel/module-ga4-pro

Note: If your product has additional satellite products that can be installed (for example, the Hyvä theme compatibility modules for the Google Analytics 4 PRO extension), you'll find the Composer installation commands for those as well.

Repeat this process for all extensions you've purchased and want to install via composer.

Pearl Theme for Magento 2

To migrate to Composer Installation for the Pearl Theme, there are a few extra steps required. You'll need to remove the extension files from app/code, as well as the theme files from app/design. To do this, follow the process below:

Important: If you have modifications/customizations in the weltpixel_custom Child Theme (or other created Child Themes), don't remove it/them from app/design.

Head into app/code

rm -rf WeltPixel

Head into app/design/frontend/Pearl

rm -rf weltpixel

Once you've removed the files, you can find the Pearl Theme installation commands in your WeltPixel account's My Products section. Hit the Enable Composer button (if you haven't already), which will reveal the Composer Installation commands. The main command depends on your Pearl Theme edition:

Essential Pack

composer require weltpixel/m2-theme-frontend-weltpixel-essential

Professional Pack

composer require weltpixel/m2-theme-frontend-weltpixel

Important: Below the main installation command is the command to install the weltpixel_custom Child Theme. You only need to run this command if you've removed the default Child Theme from app/design/frontend/Pearl.

Pearl Theme for Magento 2 on Commerce Cloud

To properly install on Magento Commerce Cloud, the process is largely the same:

Clone your repo locally.
Remove the files from app/code and app/design/frontend/Pearl.
Download the updated Magento Cloud Installation Patches from Github: [Link](https://github.com/Weltpixel/magento2-weltpixel-pearl-miscellaneous/tree/master/Magento%20Commerce%20Cloud%20Patch/Composer%20installation%20(vendor))
Complete with the normal upgrade/installation steps for Magento Cloud:

Troubleshooting

Possible issues after migrating

License is requested for Mobile Detect in the Magento Admin after installing the Pearl Theme via Composer

This happens because of the Magento Admin user session. It should be easily resolvable by logging out of the Magento Admin user and logging back in.

Frontend exception: Required parameter ‘theme_dir’ was not passed after installing the Pearl Theme via Composer

This happens when the weltpixel_custom Child Theme was removed from app/design/frontend/Pearl but was not re-installed via composer. To solve this, install the Child Theme via Composer with:

composer require weltpixel/m2-theme-frontend-weltpixel-custom

Updated on: 07/01/2026

Was this article helpful?