Shopify to NEXT theme migration

What changes from Shopify

The platforms share a file-based theme model, reusable partials, assets, and merchant settings. The main differences are DTL syntax, explicit template inheritance, Spark's build pipeline, and the boundary between cached HTML and customer-specific state.

Directory structure mapping

Start with a complete NEXT starter or an existing store theme. Do not build a theme from an empty directory.

theme/
├── assets/
├── config/
├── layout/        ← theme.liquid
├── locales/
├── sections/
├── snippets/
└── templates/

theme/
├── assets/       ← CSS, JS, images
├── configs/      ← settings JSON
├── layouts/      ← base layouts
├── locales/      ← i18n translations
├── partials/     ← reusable components
├── sass/ or css/ ← SCSS or local Tailwind source
└── templates/    ← page templates

Full-page caching and customer state

Shopify renders each page request for its visitor, so {{ cart.item_count }} is current. NEXT caches storefront pages for 5 minutes on mapped custom domains. The cache is keyed by URL, language, and currency. Visitors with the same locale receive the same cached HTML.

This has two consequences: product pricing is safe (it varies by currency, and the cache handles each combination separately), but per-user data is completely incompatible with page caching. One visitor's cart state gets baked into HTML and served to thousands of others.

Hydrate the header cart count from the GraphQL API after each page load. Reuse Spark's cart client and event contracts instead of adding another cart state implementation.

Template syntax: Liquid and DTL

Output and filters

Both languages use double-curly-brace syntax for output, but filter syntax differs. DTL uses a colon with no spaces between the filter name and argument.

{{ product.title }}
{{ product.price | money }}
{{ 'hero.jpg' | asset_url }}
{{ product.title | upcase }}
{{ product.title | truncate: 50 }}

{{ product.get_title }}
{{ product.price|currency }}
{{ 'hero.jpg'|asset_url }}
{{ product.get_title|upper }}
{{ product.get_title|truncatechars:50 }}

Conditionals

{% if product.available %}
  In stock
{% elsif product.coming_soon %}
  Coming soon
{% else %}
  Sold out
{% endif %}

{% if product.is_available %}
  In stock
{% elif product.coming_soon %}
  Coming soon
{% else %}
  Sold out
{% endif %}

Note: elsif in Liquid becomes elif in DTL. Same logic, different keyword.

Loops

{% for product in collection.products %}
  {{ product.title }}
  {% if forloop.first %}First!{% endif %}
{% endfor %}

{% for product in products %}
  {{ product.get_title }}
  {% if forloop.first %}First!{% endif %}
{% endfor %}

Loop syntax is nearly identical. DTL also supports forloop.counter, forloop.last, and a built-in {% empty %} handler for when the iterable has no items.

Template inheritance

In Shopify, theme.liquid wraps all templates implicitly. In Next Commerce, templates explicitly declare which layout they extend and which blocks they fill:

{# templates/pages/about.html #}
{% extends "layouts/base.html" %}

{% block content %}
  <h1>{{ page.title }}</h1>
  <div class="page-body">{{ page.body|safe }}</div>
{% endblock %}

The layout in layouts/base.html defines named blocks that child templates override. NEXT can use different layouts for different page types.

Comments

{% comment %}
  Multi-line comments work fine
  in Liquid with comment tags
{% endcomment %}

{%- # Inline comment (Liquid 2.0) -%}

{# Single-line comment: correct #}

{# This is WRONG:
   multi-line DTL comments render
   as visible text on the page #}

Context variables and objects

The global objects available in templates differ between platforms. Here are the most common mappings:

Styling systems

Both starter themes compile to plain CSS. Their source directories and build commands differ.

SCSS track (Intro Bootstrap)

ntk compiles each .scss file in sass/ to a matching .css file in assets/ before upload.

# Watch files, compile SCSS, and upload changes
ntk watch

# That's it. No extra build step required.

Tailwind v4 track (Spark 1.3)

Spark's Makefile runs Tailwind and the platform compatibility checks. Keep css/input.css and the compiled assets/main.css together in each change.

Use make dev for normal development. Use make build only when you need a one-time local compile instead of the watcher.

# Fetch the Tailwind CLI once
make install-tailwind

# Tailwind watcher and ntk watch
make dev

# Before release or handoff
make verify-theme
make release

{# BAD: Tailwind cannot see "blue" or "red" at build time #}
<div class="bg-{{ settings.color }}">

{# GOOD: wire settings to CSS custom properties #}
<style>:root { --primary: {{ settings.primary_color|default:"#1E293B" }}; }</style>
<div class="bg-[var(--primary)]">

{# GOOD: use static classes in conditionals #}
<div class="{% if large %}text-2xl{% else %}text-base{% endif %}">

Interactive UI with web components and GraphQL

Shopify sections combine markup and schema. NEXT keeps merchant settings in configs/settings_schema.json and composes pages from DTL layouts, blocks, and partials.

Spark uses Web Components for add to cart, the side cart, quantity controls, and other live behavior. DTL renders the static shell. Browser code handles mutations and customer-specific updates.

Keep the native form action, CSRF token, and submit button when changing add-to-cart presentation. Spark's Web Component enhances that form with GraphQL while preserving its non-JavaScript fallback.

Tooling map

Settings and configuration

Both platforms let merchants customize themes through a settings UI without editing code:

// config/settings_schema.json
[{
  "name": "Colors",
  "settings": [{
    "type": "color",
    "id": "primary_color",
    "label": "Primary color",
    "default": "#3C7DFF"
  }]
}]

// configs/settings_schema.json
{
  "Colors": {
    "primary_color": {
      "type": "color",
      "label": "Primary Color",
      "default": "#3C7DFF"
    }
  }
}

In templates, access settings via {{ settings.primary_color }}. The setting types and JSON schema are very similar between platforms.

Migration workflow

This guide covers the translation decisions. The storefront development workflow is the source for repository setup, store credentials, deployment, QA, and handoff.

make install-tailwind
make dev

# Before release or handoff
make verify-theme
make release

Quick reference

Resources

Links and references

Internal guide for Shopify-to-NEXT migrations. Verified against Spark 1.3 and Theme Kit 1.3 on Sep 4, 2026.