# Migrating to CMA & CSA

Previously, ScandiPWA used a [docker setup](https://github.com/scandipwa/magento-docker). 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](/getting-started-1.md#prerequisites).

## 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:

```bash
mkdir src/localmodules
cd src/localmodules
```

{% tabs %}
{% tab title="If you want to use the ScandiPWA theme" %}
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):

```bash
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:

```bash
cd <your-app-name>
```

{% endtab %}

{% tab title="If you are a ScandiPWA contributor" %}
Clone the ScandiPWA repo in localmodules:

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

Install dependencies:

```
yarn
```

In the instructions below, `<your-app-name>` will be "scandipwa".
{% endtab %}
{% endtabs %}

Run the compilation process in magento mode:

{% tabs %}
{% tab title="yarn (recommended)" %}

```bash
BUILD_MODE=magento yarn start
```

{% endtab %}

{% tab title="npm" %}

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

{% endtab %}
{% endtabs %}

{% hint style="info" %}
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.
{% endhint %}

## 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:

{% code title="From the project root" %}

```bash
dc up -d
inapp bash # to enter the app container
```

{% endcode %}

#### 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:

{% code title="(from within the app container)" %}

```bash
composer remove scandipwa/installer
```

{% endcode %}

#### Adding the New Setup

We will install the newly-created theme by taking advantage of Composer's ability to install from [local repository sources](https://getcomposer.org/doc/05-repositories.md#path). First, we add our theme as a local repository source. This will alter `composer.json` to add a new item in the `repositories` field:

{% tabs %}
{% tab title="If you want to use the ScandiPWA theme" %}
{% code title="(from within the app container)" %}

```bash
composer config repo.theme path localmodules/<your-app-name>
```

{% endcode %}
{% endtab %}

{% tab title="If you are a ScandiPWA contributor" %}
{% code title="(from within the app container)" %}

```bash
composer config repo.theme path localmodules/scandipwa/packages/scandipwa
```

{% endcode %}
{% endtab %}
{% endtabs %}

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

{% tabs %}
{% tab title="If you want to use the ScandiPWA theme" %}
{% code title="(from within the app container)" %}

```bash
composer require scandipwa/<your-app-name>
```

{% endcode %}
{% endtab %}

{% tab title="If you are a ScandiPWA contributor" %}
{% code title="(from within the app container)" %}

```
composer require scandipwa/scandipwa
```

{% endcode %}
{% endtab %}
{% endtabs %}

#### Making the Switch

Run the `upgrade` command and disable full-page caching:

{% code title="(from within the app container)" %}

```bash
bin/magento setup:upgrade
bin/magento cache:disable full_page
```

{% endcode %}

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:

{% code title="(from within the app container)" %}

```bash
bin/magento cache:flush
```

{% endcode %}

{% hint style="success" %}
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.
{% endhint %}

{% hint style="warning" %}

### Heads up!

The "[hot-reload](https://webpack.js.org/concepts/hot-module-replacement/)" feature only works in **insecure HTTP mode** of your Magento 2 server.
{% endhint %}

## 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:

| Old Path                                                                                                                                                        | Changes                                                                                                                                                                                                                                                 |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <p><code>etc</code></p><p><code>registration.php</code></p><p><code>theme.xml</code></p><p><br><em>\<any other Magento-specific file you have created></em></p> | Magento files now moved under a new `magento` directory for better organization. The new paths are `magento/etc`, `magento/registration.php`, etc.                                                                                                      |
| `src/public`                                                                                                                                                    | <p>Now moved outside <code>src</code>, the new path is <code>public</code>.</p><p>The file <code>index.production.phtml</code> is renamed to <code>index.php</code>, and <code>index.development.html</code> is renamed to <code>index.html</code>.</p> |
| `src/config`                                                                                                                                                    | <p>Removed. The webpack configuration now lives in the </p><p><code>@scandipwa/scandipwa-scripts</code> package. To modify this configuration, use build configuration plugins.</p>                                                                     |
| `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!

## 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](https://scandipwa.gitbook.io/create-scandipwa-app/extensions/extensions), it replaces the legacy `scandipwa.json` file.

{% hint style="info" %}
A tool for automated extension transformation from the old to the new format is available for use [on GitHub](https://github.com/scandipwa/split-legacy-extension).&#x20;
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.scandipwa.com/getting-started-1/depricated-docker-setup/migrating-from-the-docker-setup-legacy.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.