Shopify Theme Check: Pourquoi un seul chemin de fichier en argument ne fonctionne pas (et ce qu'il faut faire à la place)

Exécuter shopify theme check ./sections/header.liquid ne produit rien d'utile. La commande est syntaxiquement invalide sur la CLI actuelle : Theme Check n'accepte pas d'argument de chemin de fichier positionnel. Le drapeau de portée correct est --path, et il n'accepte qu'un répertoire, pas un seul fichier. Voici exactement ce qui fonctionne, pourquoi le linting d'un seul fichier fonctionne différemment de ce que vous attendez, et comment l'intégrer correctement à votre CI.

Points clés à retenir

• shopify theme check ./sections/header.liquid est invalide sur la Shopify CLI actuelle. Il n'y a pas d'arguments de fichier positionnels.
• Utilisez --path pour pointer vers un répertoire (par défaut le répertoire courant si omis).
• Les retours véritables pour un seul fichier proviennent du serveur de langage VS Code (themeCheck.onlySingleFileChecks), pas de la CLI.
• Le --fail-level par défaut est error, donc la CI passe silencieusement tandis que les avertissements s'accumulent. Passez toujours --fail-level warning.
• À partir de Shopify CLI 4.0 (mai 2026), l'outil nécessite Node 22.12+ et se met à jour automatiquement via votre gestionnaire de paquets en dehors de la CI.

L'erreur exacte que commet la plupart des développeurs

Vous éditez sections/hero.liquid, vous repérez un problème de linting potentiel, et vous tapez :

shopify theme check ./sections/hero.liquid

Rien d'utile ne se produit. Sur la CLI actuelle, cet argument positionnel est simplement ignoré ou produit une erreur concernant un répertoire de thème manquant.

Cette confusion a une cause précise : Theme Check 2.x (la version basée sur Node fournie avec Shopify CLI) a remplacé l'ancienne gem Ruby, et la gem Ruby acceptait un argument de chemin positionnel. Les anciens tutoriels, les réponses StackOverflow et les articles de blog écrits avant la migration Theme Check 2.x (finalisée début 2024, avec --category et --exclude-category supprimés au même moment) montrent toujours l'ancienne syntaxe. Ces articles sont maintenant incorrects.

Comme confirmé par la propre référence CLI de Shopify, --path est le seul moyen de délimiter une exécution, et il délimite un répertoire, pas un fichier.

Ce que le drapeau fait réellement

# Délimiter à un répertoire de thème spécifique
shopify theme check --path ./my-theme

# Défaut au répertoire courant
shopify theme check

# Corriger automatiquement les violations corrigeables sur place
shopify theme check -a

# Changer le niveau de sévérité qui entraîne une sortie non nulle
shopify theme check --fail-level warning

# Résultat lisible par machine (tableau plat par fichier)
shopify theme check -o json > results.json

# Lister chaque vérification active et sa sévérité
shopify theme check --list

--path indique à Theme Check quel répertoire traiter comme racine du thème. Chaque fichier à l'intérieur de ce répertoire (templates, sections, snippets, layout, assets) est vérifié en une seule passe. Vous ne pouvez pas le restreindre à un seul fichier au niveau de la CLI.

Comment linter réellement un seul fichier : l'approche Language Server

La CLI est un outil pour l'ensemble du thème. Les retours sur un seul fichier relèvent du serveur de langage Shopify Liquid, qui alimente l'extension Shopify Liquid VS Code.

L'extension expose un paramètre appelé themeCheck.onlySingleFileChecks. Lorsqu'il est défini à true, il désactive les vérifications de thème entier (telles que UnusedSnippet et TranslationKeyExists) et vérifie uniquement les fichiers actuellement ouverts dans l'éditeur. Cela rend les vérifications textDocument/didChange environ 125 fois plus rapides par rapport aux re-vérifications de thème complet à chaque frappe.

Ajoutez ceci aux paramètres de l'espace de travail VS Code :

{
  "themeCheck.checkOnOpen": true,
  "themeCheck.checkOnChange": true,
  "themeCheck.checkOnSave": true,
  "themeCheck.onlySingleFileChecks": true
}

Le compromis : vous manquerez les vérifications entre fichiers lors du codage. Le motif recommandé est d'exécuter onlySingleFileChecks: true localement pour la vitesse, puis d'exécuter le shopify theme check complet sur le thème entier en CI avant tout push.

Comparaison : CLI vs Language Server pour les retours d'un seul fichier

La faille --fail-level qui casse silencieusement la CI

Cela trompe presque chaque équipe qui configure une barrière de linting pour la première fois.

Par défaut, --fail-level est défini à error. Cela signifie qu'une exécution qui ne trouve que des avertissements se termine avec le code 0. Votre travail CI vérifie le code de sortie, voit 0, marque l'étape verte, et ces avertissements s'accumulent silencieusement sur des dizaines de PR jusqu'à ce que quelqu'un remarque finalement un filtre déprécié ou un problème de performance qui s'est retrouvé en production pendant des mois.

Corrigez-le en une ligne :

shopify theme check --fail-level warning

Niveaux acceptés, du plus au moins strict :

• info
• suggestion
• style
• warning
• error (par défaut)
• crash

Pour la plupart des magasins, warning est le bon seuil. Il détecte les vrais problèmes sans bloquer sur des suggestions purement stylistiques.

Un motif CI prêt pour la production (GitHub Actions)

Voici le motif minimal et actuel. Il utilise SHOPIFY_CLI_THEME_TOKEN pour l'authentification non-interactive et conditionne la création sur Theme Check avant tout push.

name: Theme Lint and Deploy
on:
  push:
    branches: [main]
  pull_request:

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: '22'

      - name: Install Shopify CLI
        run: npm install -g @shopify/cli @shopify/theme

      - name: Run Theme Check
        run: shopify theme check --path . --fail-level warning -o json > tc-results.json
        env:
          SHOPIFY_FLAG_STORE: ${{ secrets.SHOPIFY_STORE }}

      - name: Upload results
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: theme-check-results
          path: tc-results.json

  deploy:
    needs: lint
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: '22'
      - name: Install Shopify CLI
        run: npm install -g @shopify/cli @shopify/theme
      - name: Push theme
        run: shopify theme push --json --theme ${{ secrets.SHOPIFY_THEME_ID }}
        env:
          SHOPIFY_CLI_THEME_TOKEN: ${{ secrets.SHOPIFY_CLI_THEME_TOKEN }}
          SHOPIFY_FLAG_STORE: ${{ secrets.SHOPIFY_STORE }}

Notez que --strict sur theme push bloque uniquement sur les erreurs Theme Check, donc passer --fail-level warning dans l'étape de vérification dédiée est la bonne barrière, plutôt que de compter uniquement sur --strict.

Trois autres drapeaux à connaître

• -a / --auto-correct : corrige les violations que Theme Check peut résoudre sans jugement humain (espacement à l'intérieur de {% %}, assigns inutilisés). Exécutez ceci localement, jamais aveuglément en CI.
• --list : affiche chaque vérification activée et sa sévérité. Utile quand un membre de l'équipe ajoute un .theme-check.yml et que vous voulez vérifier l'ensemble des règles actives avant une version.
• -C theme-check:all : active chaque vérification disponible, y compris celles désactivées dans theme-check:recommended. Utilisez ceci pour un audit approfondie périodique, pas comme barrière quotidienne.

Ce qui a changé dans CLI 4.0 (mai 2026) qui affecte votre configuration

Si votre pipeline a commencé à se comporter bizarrement après mai 2026, la cause est probablement Shopify CLI 4.0. Deux choses ont changé qui affectent les exécutions de theme check :

1. Node 22.12+ est maintenant requis. Les pipelines bloqués sur Node 18 ou 20 échoueront à l'étape d'installation.
2. La mise à jour automatique est ignorée en CI. La CLI détecte les environnements CI et ne se met pas à jour automatiquement, ce qui est le comportement correct. Mais les installations locales au projet ignorent également la mise à jour automatique, donc assurez-vous que votre pipeline installe explicitement la version que vous voulez.

En bonus, theme init clone maintenant le thème Skeleton de Shopify par défaut au lieu de Dawn. Cela n'affecte pas le comportement de Theme Check, mais c'est important si vous échafaudez un nouveau projet dans le même pipeline.

Erreurs courantes dans .theme-check.yml

Votre fichier .theme-check.yml se trouve à la racine du thème et contrôle quelles vérifications s'exécutent et à quelle sévérité. Quelques motifs qui causent de la confusion :

# Correct : étendre à partir de recommandé, puis surcharger
extend: theme-check:recommended

TemplateLength:
  enabled: false

UnusedAssign:
  severity: suggestion   # réduire de warning

ParserBlockingJavaScript:
  enabled: true
  severity: error

• N'utilisez pas --category ou --exclude-category. Ces drapeaux ont été supprimés dans Theme Check 2.x. Utilisez le fichier YAML à la place.
• La clé root n'est nécessaire que quand vos fichiers de thème se trouvent dans un sous-répertoire (par exemple un dossier de sortie de construction comme dist/). Vous n'en avez pas besoin pour une structure standard Dawn ou Horizon.

Pour un regard plus large sur la façon dont Theme Check s'insère dans un flux de travail de thème Shopify complet, consultez mon guide du développement de thème Shopify et des bonnes pratiques Liquid.

Si vous intégrez ceci dans un pipeline CI/CD dans le cadre d'une migration plus large ou d'un système de construction, la page du service de développeur de thème Shopify couvre comment nous abordons les barrières de qualité automatisées sur les projets clients.