We value your feedback. Please take a 1-minute survey to help us improve our Help Center. Click ‘Yes’ to participate.

Yes
✕
Start Strong
Sell Smart
Manage with Ease
Market to Success

OS 2.1 to 3.0 Migration Guide for Private Themes

If you're currently using a private theme built on OS 2.1 and plan to upgrade to OS 3.0, this guide will walk you through the full migration process. It includes feature comparisons, syntax changes, plugin compatibility, multilingual configuration, UGC data migration, and important precautions. This version has been optimized for readability and clarity.

 

 

Migration Benefits Overview

When to Use:

This applies to merchants who have already developed and launched a private theme on OS 2.1 and plan to upgrade to OS 3.0 to benefit from a more unified architecture, enhanced functionality, and long-term performance improvements.

Comparison Area OS 2.1 Private Theme OS 3.0 Private Theme
(Post-Migration)
System Architecture Legacy system, nearing sunset New architecture with ongoing improvements
Template Syntax Handlebars Sline (faster rendering, unified debugging)
Multi-language/Market Limited flexibility Full support for primary market, multi-language
Template Management Single template support Master and sub-template management
Module Configuration Dispersed features Stronger modular structure with nested support
Rendering Performance Basic Faster compilation and better performance
Plugin Compatibility Heavy reliance on custom plugins More native features and unified integration
Future Development Maintenance only Core innovations will focus on 3.0

 

 

Syntax Differences and Migration Guide

When migrating from a 2.1 private theme to OS 3.0, you will need to fully convert Handlebars template syntax to Sline. See the syntax comparison below:

Comparison Item Handlebars (OS 2.1) Sline (OS 3.0)
Layout Support Supported via layout Not supported; use template/page
Data Context Manual or inconsistent Unified data structure

 

 

Plugin Compatibility Overview

When to Use:

  • If third-party plugins were installed in your 2.1 private theme, you’ll need to confirm whether they are compatible with the 3.0 theme before migration.

Recommended Actions:

  • List all active plugins and cross-check with the official compatibility list.
  • Refer to the official plugin compatibility list (available from your Customer Success Manager).
  • If a plugin is not yet supported in OS 3.0, evaluate whether a built-in system feature provides equivalent functionality, or contact the plugin provider for support.
  • For plugins that are no longer compatible, consider removing them or developing a custom replacement.
Notes:
  • Plugins may differ in UI/UX behavior and data structure between OS 2.1 and OS 3.0.
  • It is strongly recommended to test plugin functionality thoroughly on a staging site before going live.

 

 

Multilingual Configuration Migration

When to Use:

If your 2.1 theme has multi-language content, ensure field structures remain intact in OS 3.0.

Steps:

  1. Review translation fields in all rich text and module configurations.
  2. Use the UGC Multi-Language Translator plugin to assist with migration.
  3. Start validation from the primary market's default language.
Notes:
  • The translation logic in the theme editor remains largely unchanged.
  • Language switching still relies on the system translation module.
  • Nested rich text structures may behave differently in Sline—manual checks are recommended.

 

 

UGC Components Migration

When to Use: 

If UGC are used in your 2.1 theme, they must be manually migrated to OS 3.0.

Steps:

  1. Export each UGC's JSON configuration from the settings page before migration.
  2. Recreate matching component structures in the OS 3.0 theme.
  3. Import the JSON files into the new UGCs and bind them to your theme.
Notes:
  • Automatic migration is not supported.
  • Ensure full data export before starting.
  • Use consistent naming to ensure smooth binding and rendering.

 

 

Risks and Precautions

  • All Handlebars code must be manually rewritten using Sline syntax.
  • Confirm plugin compatibility in advance and prepare alternatives.
  • Market-specific localization for headers, footers, and global settings is not yet supported.
  • Recommended for merchants with developer support.
  • Strongly advised to test the full process in a staging environment before going live.
  • All UGC data must be exported, rebuilt, and reconnected manually.