Shopify Theme Check: 特定のファイルパスとセクションLiquidファイルをターゲットにする方法

Shopify Theme Checkは単一のファイルパスを位置引数として受け入れることができません。shopify theme check sections/hero.liquidを実行してもそのファイルだけをリントすることはできません。このツールは常にテーマ全体のツリーを検証しますが、何をチェックするか、何でエラーを終了させるか、何を出力に表示させるかを絞り込めるサポートされた複数のテクニックがあります。Theme Check 2.xで導入された変更を含む、機能するすべての方法を紹介します。

重要なポイント

• shopify theme check sections/hero.liquidは無効な構文であり、Theme Check 2.xではエラーで終了します。
• --pathは実行を単一ファイルではなくサブディレクトリにスコープします。
• JSON出力(-o json)をjqにパイプすることが、結果を特定のファイルに確実にフィルタリングする唯一の方法です。
• .theme-check.ymlは全グロブパターンを無視でき、サードパーティまたは生成ファイルからのノイズを抑制します。
• インライン{% # theme-check-disable CheckName %}コメントはあらゆるLiquidファイル内の特定のルールを抑制します。
• CLI 4.0(2026年5月)以降、Theme CheckはNode 22.12以上が必要であり、このツールはパッケージマネージャー経由で自動的にアップグレードされます。

単一ファイル引数が存在しない理由

Theme Checkはファイルごとの構文チェッカーではなく、テーマ全体のリンターです。多くのルールは設計上ファイル間にまたがっています。MissingSnippetは{% render %}呼び出しがテーマ内の他の場所の実際のファイルに解決されるかをチェックし、UnusedAssignは変数を消費する可能性のあるすべてのテンプレートを見る必要があります。1つのファイルに対して単独で実行すると、まさにそれらのチェックで偽陽性が生じます。

その設計のため、Shopifyの公式CLIドキュメントはTheme Checkがテーマ全体のツリーを分析することを意図していることを確認しています。現在のCLIには--fileまたは--onlyフラグはありません。

方法1: --pathでサブディレクトリをスコープする

単一ファイルリントに最も近いサポートされた代替案は--pathです。これはテーマチェックではなくテーマルートがどこにあるかを指示します。ただし、CIで創造的なディレクトリ構造と組み合わせることで近い結果が得られます。

# 現在の作業ディレクトリからテーマ全体をリント(デフォルト)
shopify theme check

# サブディレクトリ内に存在するテーマをリント
shopify theme check --path ./my-theme

リポジトリの特定のPRでセクションフォルダだけが変更された場合、変更されたファイルのみを含む一時コピーに--pathを指すことができます。これはほとんどのチームにとってやり過ぎですが、複数のテーマを含むモノレポでは役立ちます。

--pathがしないこと:単一ファイルsections/hero.liquidをその値として受け入れることはできません。ファイルパスではなくディレクトリを渡してください。

方法2: jqへのJSON出力パイプでファイルごとのフィルタリング

これはCIパイプラインで特定のsections/*.liquidファイルをターゲットにするための最も実用的な方法です。Theme Checkの-o jsonフラグはファイルパスでキーされたマシン可読フラットアレイを出力します。それをjqにパイプして、関心のあるエントリのみを抽出します。

# フルチェックを実行、JSONを出力、次に1つのファイルにフィルタリング
shopify theme check -o json \
  | jq '.[] | select(.path == "sections/hero.liquid")'

フィルタリングされた結果に基づいてゼロ以外の終了コードを自分で主張することもできます。

ERRORS=$(shopify theme check -o json \
  | jq '[.[] | select(.path == "sections/hero.liquid") | .offenses[] | select(.severity == "error")] | length')

if [ "$ERRORS" -gt 0 ]; then
  echo "hero.liquid has $ERRORS error(s)"
  exit 1
fi

このパターンは存在しないフラグを必要としなくても、GitHub ActionsまたはGitLab CIジョブでファイルごとのゲーティングに相当するものを提供します。

方法3: .theme-check.yml無視パターン

目標がファイルまたはフォルダをターゲットにするのではなくサイレント化することである場合、.theme-check.ymlはチェックごとのグロブベースの無視リストをサポートしています。トップレベルのignoreキーを使用してすべてのチェックから全ディレクトリを無視することもできます。

# .theme-check.yml
TemplateLength:
  enabled: true
  ignore:
    - sections/legacy-*
    - snippets/vendor-*

UnusedAssign:
  enabled: true
  ignore:
    - snippets/replo-*

スターターコンフィグを生成するには:

shopify theme check --init

これは、生成またはサードパーティファイル(Replo snippetsなど)がある場合に特に便利です。そのようなファイルには意図的に分割されたLiquidが含まれており、そうでなければtheme devでLiquidHTMLParsingErrorをトリガーします。

方法4: セクションLiquid内のインライン抑制コメント

特定のセクションファイル内の単発ルールについては、Liquidインラインコメントで名前付きチェックをコードブロック周辺で無効化および再度有効化できます。

{%- comment -%} ベンダーレンダーパターンからの偽陽性を抑制します {%- endcomment -%}
{% # theme-check-disable UnusedAssign %}
{%- assign hero_context = section.settings.context -%}
{% # theme-check-enable UnusedAssign %}

ファイル全体の場合は最初の行に無効化コメントを配置することで、チェックを抑制することもできます。

{% # theme-check-disable SpaceInsideBraces %}
{%assign x = 1%}

このアプローチはコードレビューで表示され(1行のdiffとして表示されます)、テーマ内の他のファイルには影響しません。

方法5: ローカル開発用のVS Code onlySingleFileChecks

セクションファイルを積極的に編集しているエディタで高速フィードバックが目標の場合、Shopify Liquid VS Code拡張機能には開いているファイルのみにTheme Checkを制限する設定があります。

// .vscode/settings.json
{
  "themeCheck.onlySingleFileChecks": true
}

これをオンにすると、ファイル間チェック(MissingSnippetなど)がスキップされ、アクティブタブでのみ単一ファイルルールが実行されます。公式リポジトリは、「開発中に複数ファイルにまたがるチェックを無視できる場合のパフォーマンスに最適」と説明しています。ファイル間の問題をキャッチするためにCIで完全なshopify theme checkを実行してください。

比較: すべての方法を並べて

見落としてはいけないCLI 4.0要件(2026年5月)

CLI 4.0が2026年5月にリリースされて以来、Theme Checkを実行するすべてのCIパイプラインに影響する2つの要件が変更されました。

• Node 22.12以上が必須です。古いNodeバージョンはサイレントに失敗するか、予期しない出力を生成します。
• このツールはパッケージマネージャー経由で自動的にアップグレードされ、設計上CIの自動アップグレードをスキップします。package.jsonまたはCIイメージで明示的にバージョンをピンしてください。

また知っておく価値があること: --categoryおよび--exclude-categoryはTheme Check 2.x(2024年1月)で削除されました。これらのフラグを表示する古いチュートリアルを見つけた場合、それらはもう機能しません。利用可能なすべてのチェックを明示的に実行するには-C theme-check:allを使用してください。

CIゲートパターン: パイプラインでTheme Checkを実行する正しい方法

Shopifyの公式ドキュメントが推奨するベストプラクティスのパイプラインシーケンスはこちらです。

# 1. エラー(およびほとんどのチームがデフォルトで無視する警告)でゲート
shopify theme check --fail-level warning

# 2. 未発行の開発テーマにプッシュしてプレビュー
shopify theme push --unpublished --json

# 3. 手動レビュー後のみ昇格
shopify theme publish --theme <ID> --force

避けるべき2つの一般的な誤りがあります。

• デフォルトの--fail-levelはerrorです。これは警告が累積されてサイレントに無視され、CIジョブは依然として0で終了することを意味します。--fail-level warningを渡してそれらをブロックしてください。
• theme pushでの--strictもTheme Checkが成功しない限りプッシュをブロックします。これはデプロイ時に2番目の安全ネットを提供します。

PR別のプレビューテーマについては、shopify theme push --development-context "pr-482"で開発テーマをPR番号のような安定識別子に結びつけます。

まとめる: セクションLiquidの実践的なワークフロー

上記を経た後、ほとんどのチームが終わるシーケンスはこちらです。

1. エディタ:VS CodeでonlySingleFileChecksを有効にして、セクションLiquidを書きながら高速でファイル内フィードバックを得ます。
2. プリコミットフック:コミットが上がる前に、テーマ全体に対してshopify theme check --fail-level errorを実行します。
3. CIプルリクエストゲート:shopify theme check -o json | jqを実行して、変更されたセクションファイルのみを抽出し、それに対して主張します。
4. CDデプロイゲート:shopify theme push --strictを実行して、誰かがステップ3をバイパスしても、エラーを含むプッシュはブロックされます。
5. 設定:生成またはベンダースニペットのターゲット無視グロブを含む.theme-check.ymlを維持して、偽陽性が実際の作業を停止するのを防ぎます。

実際のパイプラインでこれを配線するのに支援が必要ですか? Shopifyテーマ開発者サービスページにはクライアントプロジェクト用にこれをセットアップする方法に関するコンテキストがあり、Shopify速度最適化はTheme Checkがフラグを立てる最も一般的なパフォーマンスチェックについてカバーしています。