Shopify Liquid入門｜テーマの表示ロジックを安全に実装する基本と判断基準

「shopify liquid」で調べる人の多くは、Liquidのタグ一覧だけを知りたいわけではありません。

商品カードに価格、比較価格、在庫、ラベルを出したい。商品ページに素材、サイズ表、注意事項を出したい。コレクション一覧で条件に応じてバッジを切り替えたい。カート内の商品条件で配送案内を出したい。section settingsやblock settingsでEC担当者が編集できるようにしたい。メタフィールドを表示したいが、空欄時や長文時に崩れないようにしたい。

Shopify公式のLiquid referenceでは、Liquidはobjects、tags、filtersを使ってShopifyテーマのHTMLを組み立てるテンプレート言語として説明されています。また、公式のTheme architectureでは、テーマはlayout、templates、sections、blocks、snippets、config、assetsなどの構造で整理されるとされています。さらにSettingsでは、settings、section.settings、block.settingsとしてテーマエディタの値をLiquidから参照できることが示されています。

つまりLiquidは、単独の文法ではなく、Shopifyテーマ構造の中で表示ロジックを置く場所です。

Shopifyテーマ開発の実務設計では、Online Store 2.0、sections/blocks、メタフィールド、Git運用まで含めたテーマ改修全体を整理しました。この記事ではそこから範囲を絞り、テーマ全体の開発手順ではなく、Liquidで何を書き、どこで部品化し、どこからJS/API/アプリへ逃がすべきかに集中します。

Shopify Liquidの品質は、文法の多さではなく、表示ロジックを「商品データ」「編集設定」「再利用部品」「動的処理」に分けられているかで決まります。

先に結論：Liquidは表示の組み立てに絞る

Liquidは、Shopifyがすでに持っている商品、コレクション、カート、メタフィールド、テーマ設定を使ってHTMLを組み立てる場所です。外部データ取得、管理データ更新、複雑な状態管理、購入後処理までLiquidに押し込むと、テーマが壊れやすくなります。

やりたいこと	Liquidで持つ	Liquidで持たない	判断のポイント
商品名、価格、画像、在庫状態を出す	product objectを使った表示	商品マスタの同期や在庫更新	Shopify内の値を表示するだけならLiquid
コレクション一覧の商品カードを出す	collection.productsのループ、商品カードsnippet	独自検索エンジンのランキング処理	並び順や検索ロジックがShopify外なら別設計
カート内の商品条件で案内文を出す	cart.itemsを見た表示切り替え	配送可否や決済制御の確定判定	注意表示はLiquid、購入制御はFunctionsや設定も検討
商品ごとの素材・注意事項を出す	メタフィールドを読み、空欄時に隠す	商品説明HTMLへの直書き	値はデータ側、見せ方はLiquid
見出し、余白、表示有無を編集可能にする	section/block settings	EC担当者に触らせるべきでない構造	編集範囲と崩してはいけない範囲を分ける
画面遷移なしでカート数量を変える	初期HTMLと状態表示	非同期更新そのもの	Ajax APIやJSへ分ける
外部CRMの会員ランクで出し分ける	同期済みタグ・メタフィールドの表示	外部CRMへのリアルタイム照会	認証・失敗時表示・キャッシュが必要ならアプリ/API
レビュー、診断、チャットを出す	app blockを受ける位置の整備	アプリ内部ロジック	テーマは配置と崩れ防止に徹する

Liquidを「全部できる場所」と見ない方がよいです。Liquidは表示の最終組み立てに強い一方、データの正本管理、外部連携、再実行ログ、認証、複雑なフロント状態管理には向きません。

objects、tags、filtersを役割で覚える

Liquidの基本は、objects、tags、filtersです。公式リファレンスでも、objectsは変数やShopifyリソースを参照し、tagsは条件分岐やループなどのロジックを定義し、filtersは出力を加工するものとして整理されています。

実務では、文法名を丸暗記するより、次のように役割で覚える方が安全です。

種類	例	実務での役割	注意点
objects	product、collection、cart、section、settings	Shopifyが持つ現在のデータやテーマ設定を参照する	そのテンプレートで使えるobjectか確認する
tags	if、unless、for、case、assign、render	表示条件、繰り返し、変数、snippet呼び出しを定義する	深いネストや例外分岐を増やしすぎない
filters	money、image_url、image_tag、escape、default、json	値を表示用に加工する	HTML、URL、JS文脈ごとに安全な出力を選ぶ
operators	==、!=、contains、and、or	表示条件を判定する	タグや文字列の曖昧な判定を増やさない
whitespace control	{%-、-%}	余分な改行や空白を抑える	読みにくくなるほど詰めない

たとえば商品カードでは、product objectからタイトル、URL、画像、価格を取り、ifで在庫や比較価格を判定し、image_urlやmoneyのようなfilterで表示用に整えます。

{% render 'product-card',
  product: product,
  show_vendor: section.settings.show_vendor,
  badge_text: product.metafields.display.badge.value
%}

この例で大事なのは、商品カードのHTMLをコレクションsectionに直接書かず、product-card snippetへ渡していることです。Liquidの文法そのものより、「商品カード」という再利用部品へ切る判断が保守性を左右します。

product、collection、cartは表示責務を分ける

Liquidでよく触るobjectは、商品、コレクション、カートです。ただし、同じ商品情報でも表示する場所によって責務が違います。

表示場所	主なobject	Liquidで行うこと	避けたいこと
商品ページ	product、section、block	商品情報、バリエーション、購入ボタン周辺、商品別メタフィールドを表示する	商品タイプごとの例外を大量に直書きする
商品カード	product、collection	画像、タイトル、価格、在庫ラベル、簡易バッジを表示する	ページごとにカードHTMLを複製する
コレクション一覧	collection、paginate	商品一覧、絞り込みUI、空欄時表示、ページネーションを組み立てる	独自ランキングや複雑な検索をLiquidだけで作る
カート	cart、cart.items	カート内商品の表示、数量、合計、注意文、配送案内を表示する	受注処理、在庫引当、決済制御をLiquidで済ませる
共通ヘッダー	cart、settings	カート件数、ナビ、テーマ設定を表示する	商品ページ固有の判断を混ぜる

商品ページのLiquidは、購入判断に必要な情報を出す場所です。素材、サイズ、注意事項、FAQ、配送条件を表示することは自然です。ただし、それらの値をLiquid内に固定文言として書くのではなく、商品メタフィールドやメタオブジェクトを読みます。

コレクション一覧では、商品カードを再利用できる状態にしておくことが重要です。トップページのおすすめ商品、検索結果、関連商品、コレクション一覧でカードHTMLが分かれると、価格表示やバッジ表示の修正漏れが起きます。

カートでは、Liquidで注意文を出すことはできます。たとえば冷凍商品が含まれる場合に配送案内を出す、予約商品が含まれる場合に発送時期を出す、といった表示です。ただし、購入を禁止する、配送方法を確定制御する、決済方法を制限する、といった処理はLiquid表示だけでは足りません。必要に応じてShopify Functions、標準設定、アプリ、API連携の領域として扱います。

section settingsとblock settingsは編集範囲を決める道具

Liquidの表示ロジックは、テーマエディタから渡されるsettingsと組み合わせて初めて運用しやすくなります。Shopify公式のsettingsドキュメントでは、作成場所に応じてsettings、section.settings、block.settingsから値にアクセスできると説明されています。

ここで重要なのは、何でもsettings化しないことです。EC担当者が変えてよい値と、開発者が守るべき構造を分けます。

設定場所	向いている値	Liquidでの扱い	設計上の注意
theme settings	ブランドカラー、共通余白、グローバルな表示ON/OFF	settings.xxx	全ページへ効くため、影響範囲を明確にする
section settings	section見出し、レイアウト、背景、表示件数	section.settings.xxx	そのsectionの責務に閉じる
block settings	Q&Aの質問・回答、ボタン文言、画像、リンク	block.settings.xxx	並び替えや追加削除しても崩れない粒度にする
product metafields	商品ごとの素材、注意事項、スペック	product.metafields.xxx.yyy	入力値が空でも表示崩れしないようにする
metaobjects	共通FAQ、サイズ表、ブランド情報	参照先をLiquidで表示	同じ情報を複数商品へ直書きしない

たとえばFAQ sectionなら、少数の自由なQ&Aはblock settingsでもよいです。一方、複数商品で同じFAQセットを使い回すなら、blockに直書きするよりメタオブジェクトや商品メタフィールド参照の方が保守しやすいです。

悪いsettings設計は、テーマエディタを便利に見せますが、運用で壊れます。購入ボタン周辺に任意HTMLを入れられる、商品カードの構造をblockで細かく分解しすぎる、全ページ共通設定で商品ページ固有の表示を制御する、といった設計は避けます。

snippetsは「再利用する表示部品」に切る

Shopify Liquidでは、snippetsを使って再利用する表示部品を分けます。公式のrenderタグでは、snippetを呼び出し、必要な変数を渡せます。実務では、snippetは「ファイルを小さくするため」ではなく、「同じ判断を複数箇所で再利用するため」に使います。

snippet候補	渡す値の例	切る理由	切らない方がよい場合
product-card	product、show_vendor、badge_text	商品カードの価格・画像・バッジ表示を統一する	1箇所でしか使わない特殊LP
price	productまたはvariant	通常価格、比較価格、税込表示を統一する	ページごとに価格ルールがまったく違う場合
product-badges	product、collection	NEW、SALE、在庫切れ、予約などの表示を統一する	バッジが単純で1行で済む場合
metafield-row	label、value	仕様表や成分表の空欄処理を統一する	表示文脈ごとにHTMLが大きく違う場合
cart-note-line	cartまたはitem	カート注意文の条件を整理する	購入制御まで含む場合

snippetへ切るときは、呼び出し元のobjectに依存しすぎないようにします。たとえばproduct-cardの中で、特定sectionのsection.settingsを直接参照しすぎると、別ページで使い回しにくくなります。必要な値は引数として渡します。

{% render 'product-card',
  product: product,
  show_badges: section.settings.show_badges,
  image_ratio: section.settings.image_ratio
%}

この形なら、同じ商品カードをトップページ、コレクション一覧、関連商品sectionで使い回しやすくなります。

メタフィールド表示は空欄・型・公開範囲を見る

メタフィールドはLiquid表示と相性がよいです。ただし、メタフィールドを読めばよい、という単純な話ではありません。表示してよいデータか、型は何か、空欄時にどうするか、長文時に崩れないかを見ます。

Shopifyメタフィールド設計ガイドでは、namespace/key/type、CSV、API、外部PIM/DBまで含めたデータ設計を整理しました。Liquid側では、その設計済みデータを安全に表示する責務に絞ります。

表示したい情報	データの置き場所	Liquidで見ること	悪い書き方
素材	商品メタフィールド	空欄なら行ごと非表示	素材：だけ残る
サイズ表	メタフィールドまたはメタオブジェクト	画像・表・参照型に応じて表示を分ける	商品説明HTMLへ表を直書き
注意事項	商品メタフィールド	購入ボタン周辺に出すか、詳細内に出すか	法務確認文言をLiquidに固定
ブランド説明	メタオブジェクト	複数商品で参照し、更新漏れを防ぐ	商品ごとに同じ文章を複製
出荷条件	商品またはバリエーションメタフィールド	カート内でも参照が必要か確認	商品ページだけ表示してカートで消える
社内管理ID	管理用メタフィールド	原則ストアフロントに出さない	HTMLに隠し出力する

メタフィールド表示では、次のようなガードを入れます。

{% assign material = product.metafields.spec.material.value %}

{% if material != blank %}
  <dl class="product-spec">
    <dt>素材</dt>
    <dd>{{ material | escape }}</dd>
  </dl>
{% endif %}

値がない場合はラベルごと出さない。自由テキストをHTMLとして解釈させない。長文や改行を含む値は表示領域を確認する。リッチテキストや参照型のように型ごとの出力が必要な場合は、Shopifyのmetafield_tagなど、型に合う出力方法も検討します。

また、メタフィールドのkeyがsize、first、lastのようなLiquidの組み込み名とぶつかる場合は、ドット記法ではなく角括弧記法を使う方が安全です。

{{ product.metafields.spec["size"].value }}

こうした細部は地味ですが、テーマ変更や商品追加が増えたときに効きます。

出力エスケープと表示崩れをレビューする

Liquidでは、値をどの文脈へ出すかで安全な書き方が変わります。HTML本文、属性値、URL、JavaScript内JSONでは、使うfilterや出力方法を分けます。Shopify公式のescape filterは、HTML上で特別な意味を持つ文字をエスケープするためのfilterとして説明されています。

出力先	よく使うfilter/方法	確認すること	NG例
HTML本文	escape、metafield_tag	自由入力値をHTMLとして解釈させない	{{ block.settings.text }}を無条件に出す
HTML属性	escape	引用符、改行、長文で属性が壊れないか	alt="{{ product.title }}"だけで放置
URL	url_escape、url_param_escape	検索語やパラメータがURLを壊さないか	入力値をそのままクエリに連結
JavaScript内	json	文字列をJSへ安全に渡せるか	var title = "{{ product.title }}";
画像	image_url、image_tag	幅・高さ、alt、lazy load、CLSを確認	元画像をそのまま巨大表示
価格	money系filter、テーマ方針	通貨、比較価格、税込表記を統一	ページごとに価格フォーマットを手書き

表示崩れは、Liquidの条件分岐ミスだけでなく、入力値の長さや空欄で起きます。レビューでは、通常商品だけでなく、長い商品名、画像なし、在庫切れ、バリエーション多数、メタフィールド未入力、予約商品、比較価格あり、タグなしの商品を確認します。

テストデータ	見る場所	壊れやすい箇所
商品名が長い	商品カード、商品ページ、カート	タイトルの折り返し、価格との重なり
画像がない	商品カード、関連商品	画像枠の高さ、alt、プレースホルダー
メタフィールド空欄	仕様表、FAQ、注意事項	ラベルだけ残る、余白だけ残る
在庫切れ	商品ページ、カード、カート	購入ボタン、売り切れバッジ、再入荷案内
比較価格あり	商品カード、商品ページ	SALE表示、価格順序、アクセシビリティ
カート内に特定商品あり	カート、ドロワーカート	注意文の重複、配送案内の出し漏れ

Liquidレビューでは「正しい商品で見えるか」だけでは不十分です。空欄、長文、在庫切れ、画像なし、カート混在時にも壊れないかを見る必要があります。

悪いLiquidの書き方を早めに止める

Liquidは柔軟なので、動くけれど保守しにくい書き方が入りやすいです。レビューでは、文法エラーだけでなく、責務の混在を見ます。

悪い書き方	起きる問題	直し方
商品IDやhandleを大量にifで分岐する	例外が増え、商品追加時に漏れる	メタフィールド、タグ、商品タイプ、コレクションで判定する
商品カードHTMLを複数sectionに複製する	価格やバッジ修正が一部だけ漏れる	product-card snippetへ寄せる
sectionの中に長いCSS/JS/Liquidを全部入れる	変更範囲が読めず、速度影響も見えない	表示、スタイル、動的挙動の責務を分ける
product.tags contains 'sale'だけに依存する	タグ運用の表記ゆれで表示が壊れる	タグ命名規則やメタフィールドへ整理する
メタフィールド値をHTMLとして直出しする	意図しないHTML崩れや表示事故が起きる	型に合う出力、escape、metafield_tagを使う
カート内判定を商品名文字列で行う	商品名変更で条件が外れる	商品タグ、type、metafield、variant情報で判定する
JSにLiquid文字列をそのまま埋める	引用符や改行でJSが壊れる	json filterで渡す
外部API呼び出し前提の情報をLiquidで出そうとする	認証・失敗時表示・速度が設計できない	Storefront API、app proxy、アプリへ分ける

特に、商品IDやhandleの直書き分岐は短期対応として入りやすいです。しかし、商品追加、複製、商品名変更、テーマ移行で破綻します。どうしても一時対応が必要な場合でも、理由、対象、撤去条件をコメントや改修台帳に残すべきです。

パフォーマンスはLiquid、画像、JS、アプリをセットで見る

Liquidはサーバー側でHTMLを生成しますが、テーマ全体の表示速度はLiquidだけで決まりません。商品ループ、画像出力、不要なsnippet、全ページで読み込むJS、アプリ埋め込みが積み重なります。

観点	Liquidで見ること	逃がす・減らす判断
商品ループ	表示件数、ネストしたループ、不要な計算	ページネーション、sectionの表示件数制限
snippet	同じsnippetを過剰に呼んでいないか	カード表示に必要な値だけ渡す
画像	image_url、image_tag、幅、高さ、遅延読み込み	元画像サイズのまま出さない
メタフィールド	ループ内で複雑な参照を増やしすぎない	表示に必要な項目だけに絞る
JavaScript	Liquidで初期HTMLを出し、動的処理だけJSへ渡す	全ページ読み込みを避ける
アプリ	app block/app embedの表示位置と必要性	不要アプリ、二重タグ、重いウィジェットを棚卸し

たとえば商品カードで、一覧ごとにバッジ、レビュー、在庫、メタフィールド、関連情報を全部出すと、見た目は豊かでも重くなります。カードに必要な情報は、一覧で購入判断に必要な最小限にし、詳細情報は商品ページで出します。

また、JavaScriptへ渡す初期データはjson filterを使って安全に出します。

<script>
  window.productOptions = {{ product.options_with_values | json }};
</script>

LiquidでHTMLを出し、JSで必要なインタラクションだけ補う。これが基本です。JSで全商品カードを再描画する、Liquidで済む表示を無理にAPI化する、アプリのウィジェットを全ページへ出す、といった設計は、速度と保守性を落とします。

JS、Storefront API、アプリへ逃がす境界

Liquidで作るべきか、JavaScriptやAPIへ分けるべきかは、表示タイミング、データの場所、認証、失敗時の扱いで決めます。

Shopify APIの種類と選び方では、Liquid、Ajax API、Storefront API、Admin API、Webhook、Functionsの境界を整理しました。Liquid側の判断では、次の表を使うと切り分けやすいです。

要件	Liquid	JS / Ajax API	Storefront API	アプリ / Admin API
商品ページにスペックを出す	向く	不要	不要	データ同期が必要なら候補
コレクション一覧に商品カードを出す	向く	絞り込みUI補助なら候補	ヘッドレスなら候補	不要
カート数量を画面遷移なしで変える	初期表示に向く	向く	テーマ外なら候補	不要
外部サイトでShopify商品を表示する	向かない	場合による	向く	管理データ更新なら別
顧客別の外部CRM情報を出す	同期済み値なら向く	認証なしでは危険	顧客向け体験なら候補	認証・同期が必要なら候補
レビューや診断を表示する	app blockの配置に向く	アプリ側JS	場合による	向く
商品マスタを更新する	向かない	向かない	向かない	Admin API
購入可否や配送方法を制御する	注意表示まで	UI補助まで	購入体験次第	Functions、設定、アプリ

境界判断の目安は単純です。

質問	Yesなら
Shopify内のデータをHTMLとして出すだけか	Liquidを第一候補にする
ユーザー操作に応じて画面の一部を変えるだけか	JSやAjax APIを検討する
Shopifyテーマ外のフロントで商品・カート体験を作るか	Storefront APIを検討する
管理データを読み書きするか	Admin APIやカスタムアプリを検討する
認証、外部DB、失敗時再実行、監査ログが必要か	Liquidから出してアプリ/APIへ分ける
購入フローの判定そのものを変えるか	Liquid表示ではなくFunctionsや設定を検討する

「Liquidでできるか」ではなく、「Liquidに置いて保守できるか」で判断します。

コードレビューは表示責務の混在を見る

Liquidのコードレビューでは、構文チェックだけでは足りません。表示責務、編集範囲、データ参照、出力安全性、パフォーマンス、運用変更への強さを見ます。

レビュー項目	確認内容
objectの妥当性	そのテンプレート・sectionで使えるobjectを参照しているか
条件分岐	商品ID直書き、handle直書き、タグ表記ゆれ依存が増えていないか
snippet分割	再利用すべき商品カード、価格、バッジ、仕様行が複製されていないか
settings設計	EC担当者が触る範囲と、壊してはいけない構造が分かれているか
block設計	blockが細かすぎないか、並び替えても表示が破綻しないか
メタフィールド	namespace/key/type、空欄時、公開範囲、型に合う表示を確認しているか
出力エスケープ	HTML、属性、URL、JSで適切なfilterを使っているか
パフォーマンス	商品ループ、画像、JS、アプリ埋め込みが重くなっていないか
カート表示	商品混在、数量変更、在庫切れ、予約商品で案内が破綻しないか
API境界	Liquidで持つべきでない外部連携や購入制御が混ざっていないか

レビューで特に見たいのは、例外対応です。「この商品だけ表示を変える」「このコレクションだけバナーを出す」「このキャンペーン中だけ文言を変える」といった要件は、Liquidに直書きされがちです。短期施策でも、settings、metafields、tags、templates、sectionsのどこで管理するかを決めた方が、後から消し忘れにくくなります。

外注時はLiquid実装ではなく表示仕様を渡す

制作会社やフリーランスへ依頼する場合、「Liquidで商品ページを直してください」では不足します。表示ロジックの仕様として渡す方が、仕上がりをレビューしやすくなります。

依頼項目	書く内容
対象画面	商品ページ、コレクション一覧、カート、トップのおすすめ商品など
対象データ	商品情報、バリエーション、カート、メタフィールド、メタオブジェクト、settings
表示条件	在庫切れ、比較価格あり、タグあり、メタフィールド空欄、予約商品など
編集範囲	EC担当者がtheme editorで変更する値、商品管理画面で変更する値
snippet方針	商品カード、価格、バッジ、仕様表など再利用部品に切る範囲
出力安全性	自由入力値、HTML、URL、JSに出す値の扱い
JS/API境界	Ajax API、Storefront API、アプリ、Admin APIへ分ける処理
確認データ	長い商品名、画像なし、メタフィールド空欄、在庫切れ、カート混在
納品物	変更ファイル、表示仕様、レビュー観点、今後EC担当が触る場所

この形で依頼すると、単なるLiquid文法の実装ではなく、運用できる売場UIとして確認できます。特に、商品カード、価格表示、メタフィールド表示、カート注意文は、複数ページにまたがるため、最初から再利用とレビュー観点を決めておくべきです。

まとめ

Shopify Liquidは、if、for、filtersを覚えれば書けます。しかし、実務で必要なのは文法入門で終わらせないことです。

objects、tags、filtersで商品・コレクション・カートを表示する。section settingsとblock settingsで編集範囲を決める。snippetsで商品カード、価格、バッジ、仕様表を再利用する。メタフィールドは空欄、型、公開範囲、出力エスケープまで見て表示する。パフォーマンスはLiquidだけでなく画像、JS、アプリ埋め込みとセットで見る。外部データ、認証、管理データ更新、購入制御は、JavaScript、Ajax API、Storefront API、Admin API、Functions、アプリへ分ける。

これらを決めて初めて、Liquidは保守できる表示ロジックになります。

Bitlightでは、Shopify Liquidを単なるテーマ修正の記法としてではなく、商品データ、メタフィールド、sections/blocks、JavaScript、API、アプリの境界を整理した売場UIとして設計します。商品ページやコレクション一覧を直す前に、まずは「Liquidで持つ表示」「snippetへ切る表示」「データ側へ逃がす値」「JS/API/アプリへ分ける処理」を分けることが、長く保守できるShopifyテーマ改修の出発点です。