---
title: "Migration guide from OS 2.1 to OS 3.0"

doc_type: static
doc_category: static
doc_version: v20270301
source_url:
  html: 'https://developer.shopline.com/docs/online-store-3-0-themes/integrate-apps-with-themes/theme-app-extension/migration-guide-from-os-2-1-to-os-3-0'
  md: 'https://developer.shopline.com/docs/online-store-3-0-themes/integrate-apps-with-themes/theme-app-extension/migration-guide-from-os-2-1-to-os-3-0.md'
---
# 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{#ztJxc}
The following shows the main differences in the theme app extension directories between OS 2.1 and OS 3.0: 

| **OS 2.1 Directory** | **OS 3.0 Directory** |
| --- | --- |
| assets | public |
| locales | i18n |
| snippets | components |


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](https://developer.shopline.com/docs/themes-2-0/integrate-apps-with-themes/theme-app-extension/framework?version=v20251201#file-structure)
+ [Directory for OS 3.0 theme app extensions](https://developer.shopline.com/docs/online-store-3-0-themes/integrate-apps-with-themes/theme-app-extension/structure.md?lang=en)


## Syntax upgrade{#Zseai}
| **OS 2.1** | **OS 3.0** |
| --- | --- |
| Handlebars | [Sline](https://developer.shopline.com/docs/sline/object/additional-checkout-buttons.md) |



## Migration steps{#A3ca6}
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.

```yaml
---
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. 

```shell
└── 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](https://developer.shopline.com/docs/themes-2-0/integrate-apps-with-themes/theme-app-extension/framework/?version=v20250601#schema) to the `i18n` directory. 

```html
<div>{{ "title" | t() }}</div>

{{#schema}}
{
  ...
  locales: {              # Deprecated
    "en": {
      "title": "Title"
    },
    "zh-hans-cn": {
      "title": "标题"
    }
  }
}
{{/schema}}
```

Migrate English content to `i18n/en.json`:

```json
{
  "title": "Title"
}
```

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

```json
{
  "title": "标题"
}
```

4. Install and use the [new version of the SHOPLINE CLI](https://developer.shopline.com/docs/online-store-3-0-themes/development-tools/cli/overview.md). 

```shell
npm install @shoplineos/cli -g
```