Migration guide from OS 2.1 to OS 3.0​

This guide provides an understanding of the differences between Online Store 2.1 (OS 2.1) and Online Store 3.0 (OS 3.0) versions of theme app extensions, as well as the steps required for migration.

Directory upgrade​

The following shows the main differences in the theme app extension directories between OS 2.1 and OS 3.0:

For more detailed information on the directories for theme app extensions in OS 2.1 and OS 3.0, refer to:

• Directory for OS 2.1 theme app extensions
• Directory for OS 3.0 theme app extensions

Syntax upgrade​

Migration steps​

If you need to upgrade your existing project to support the OS 3.0 theme, follow these steps:

1. Add compatibility: true in the .shopline-cli.yml file.

---
compatibility: true                   # Newly added
project_type: extension
organization_id: 0
EXTENSION_TYPE: THEME_APP_EXTENSION

2. Create a new compatibility directory in the root of your project. Place the OS 2.1 theme app extension directories into this compatibility folder.

└── theme-app-extension
    ├── blocks
    │   └── ...
    ├── components
    │   └── ...
    ├── i18n
    │   └── ...
    ├── public
    │   └── ...
    ├── compatibility        # New directory
    │   ├── assets
    │   ├── blocks
    │   ├── locales
    │   ├── snippets
    │   └── ...
    └── .shopline-cli.yml

3. Migrate the locales field within the deprecated schema to the i18n directory.

<div>{{ "title" | t() }}</div>
{{#schema}}
{
  ...
  locales: {              # Deprecated
    "en": {
      "title": "Title"
    },
    "zh-hans-cn": {
      "title": "标题"
    }
  }
}
{{/schema}}

Migrate English content to i18n/en.json:

{
  "title": "Title"
}

Migrate Chinese content to i18n/zh-hans-cn.json:

{
  "title": "标题"
}

4. Install and use the new version of the SHOPLINE CLI.

npm install @shoplineos/cli -g