shopify theme check --path vs arguments positionnels: Le guide de syntaxe définitif

Utilisez shopify theme check --path ./your-theme pour limiter une exécution lint à un répertoire. Il n'y a pas d'arguments positionnels dans le Shopify CLI actuel : shopify theme check ./sections/header.liquid est une syntaxe invalide et la CLI ne linter pas ce fichier. Le flag --path est le seul et unique mécanisme que l'outil expose pour limiter le répertoire.

Points clés à retenir

• --path limite l'exécution à un répertoire ; il n'accepte pas un chemin de fichier unique.
• Les arguments positionnels (par exemple shopify theme check ./sections/header.liquid) ne sont pas supportés et ne produisent aucune sortie utile.
• Omettre --path par défaut utilise le répertoire de travail actuel.
• La variable d'environnement SHOPIFY_FLAG_PATH est l'équivalent CI de --path.
• Depuis la CLI 4.0 (sortie en mai 2026), Node 22.12+ et Git 2.28+ sont requis.

La confusion centrale : pourquoi la commande semble accepter un fichier

Tous les autres linters populaires (ESLint, Stylelint, RuboCop) acceptent un fichier ou un glob positionnel :

eslint src/main.js          # valide
stylelint "src/**/*.css"    # valide
shopify theme check ./sections/header.liquid  # INVALIDE

Shopify Theme Check ne suit pas cette convention. La commande theme check de la CLI n'accepte aucun argument positionnel. Si vous passez un chemin en tant qu'argument positionnel, la CLI ne produit pas d'erreur bruyante ; elle l'ignore simplement et lint le répertoire de travail actuel à la place. Ce repli silencieux est ce qui rend ce bug difficile à trouver.

Cela compte plus qu'il n'y paraît. Les développeurs qui déboguent un fichier bruyant unique exécutent souvent shopify theme check ./snippets/icon-sprite.liquid, voient un rapport complet du thème, supposent que le check a réussi pour ce fichier, et déploient. Le check n'a jamais été exécuté isolément.

Le flag --path : ce qu'il fait réellement

Le flag --path indique à Theme Check quel répertoire utiliser comme racine du thème. Il prend par défaut le répertoire de travail actuel quand il est omis.

# Lint le thème dans le répertoire actuel (implicite)
shopify theme check

# Lint un thème dans un sous-répertoire
shopify theme check --path ./my-theme

# Lint un thème dans un dossier de sortie de build
shopify theme check --path ./dist

Important : --path doit pointer vers un répertoire qui contient la structure de dossier Shopify standard (templates/, sections/, snippets/, etc.). Le passer un chemin de fichier unique n'est pas valide non plus.

L'équivalent variable d'environnement est SHOPIFY_FLAG_PATH, qui suit le modèle de nommage standard SHOPIFY_FLAG_* que presque tous les autres flags utilisent dans la CLI actuelle.

Référence complète des flags pour shopify theme check

Voici tous les flags que vous utiliserez réellement, avec leurs objectifs :

Le flag --fail-level est particulièrement important pour les pipelines CI. Par défaut, Theme Check ne quitte avec le code 1 que sur des problèmes de sévérité error. Si vous voulez aussi bloquer sur les avertissements, vous devez être explicite :

shopify theme check --path ./theme --fail-level warning

Pourquoi vous ne pouvez pas linter un fichier unique avec la CLI

Theme Check est conçu comme un linter de thème entier, pas un linter de fichier. De nombreux checks dépendent du contexte entre fichiers :

• UnusedSnippet doit connaître tous les fichiers qui appellent {% render %}.
• TranslationKeyExists doit lire les fichiers locales aux côtés de votre Liquid.
• MissingTemplate doit avoir le répertoire templates/ complet pour vérifier les références.

Exécuter un check de fichier unique produirait des résultats dénués de sens pour ces règles entre fichiers. C'est une décision de conception délibérée, pas une omission. Si vous voulez des commentaires par fichier au fur et à mesure que vous tapez, utilisez l'extension Shopify Liquid VS Code, qui exécute le Language Server Protocol (LSP) de Theme Check en temps réel.

C'était un bond en avant important quand Theme Check 2.0 a été publié, unifiant le linter et ajoutant des fonctionnalités LSP comme les docs au survol et la complétion de code pour les réglages, les traductions, le HTML et le Liquid directement dans les éditeurs.

Ce qui a changé dans la CLI 4.0 (mai 2026)

Si vous suivez des tutoriels plus anciens, sachez que Shopify CLI 4.0, publié en mai 2026, a introduit plusieurs changements qui affectent le fonctionnement de theme check :

• Auto-mise à jour par défaut : La CLI se met maintenant à jour automatiquement via votre gestionnaire de paquets. La mise à jour automatique est ignorée dans les environnements CI et les sauts de version majeure.
• Node 22.12+ et Git 2.28+ requis. Les versions antérieures de Node produiront des erreurs lors de l'installation.
• theme init clone maintenant Skeleton, pas Dawn. Cela affecte la structure de thème qui est générée pour les nouvelles builds.
• Aucune commande de connexion interactive : Il n'y a pas de shopify login ou shopify whoami sur la CLI actuelle. L'authentification est basée sur les tokens.

Pour les pipelines CI/CD, le modèle documenté non-interactif est toujours une porte linter suivie d'un push :

shopify theme check --path ./theme --fail-level error
shopify theme push --json --theme staging

Limiter Theme Check en CI : la bonne façon

Voici une étape GitHub Actions minimale mais prête pour la production :

name: Theme Check
on: [push, pull_request]
jobs:
  theme-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - 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
        env:
          SHOPIFY_FLAG_STORE: ${{ secrets.SHOPIFY_STORE }}

Si vous utilisez l'action officielle Shopify theme-check-action@v2, l'équivalent de chemin est l'input theme_root, pas un argument positionnel :

- uses: Shopify/theme-check-action@v2
  with:
    theme_root: './dist'
    flags: '--fail-level warning'

L'input theme_root correspond en interne à --path. L'input flags vous permet de passer tous les flags supplémentaires, incluant --fail-level.

Trois approches comparées

Supprimer les faux positifs sans désactiver les checks entiers

Si Theme Check signale du code valide (un filtre Liquid personnalisé, une balise tierce), utilisez des commentaires de suppression inline plutôt que de désactiver le check entier globalement :

{% # theme-check-disable LiquidTag %}
{{ product.title | my_custom_filter }}
{% # theme-check-enable LiquidTag %}

Pour les faux positifs persistants sur plusieurs fichiers, la clé ignore dans .theme-check.yml est plus propre :

LiquidTag:
  enabled: true
  ignore:
    - snippets/vendor-component.liquid

Vous pouvez générer une configuration de démarrage à tout moment avec shopify theme check --init, qui écrit un .theme-check.yml pré-chargé avec les réglages recommandés de Shopify.

La chaîne de précédence des variables d'environnement

La précédence dans la CLI actuelle est : flag > variable d'env > shopify.theme.toml. Un flag --path sur la ligne de commande remplace SHOPIFY_FLAG_PATH dans l'environnement, qui remplace tout chemin défini dans le fichier toml. Un flag inline égaré dans un script remplacera silencieusement une variable d'env CI, ce qui est une source courante de confusion 'ça fonctionne localement mais pas en CI'.

Si votre étape CI demande toujours de manière interactive, ajoutez SHOPIFY_FLAG_FORCE=1 pour supprimer les invites de confirmation.

Pour un aperçu plus approfondi de la façon dont un flux de travail professionnel de développement de thème s'adapte ensemble, consultez mon guide sur les meilleures pratiques Shopify de développement de thème Liquid. Si vous optimisez les performances front-end de votre thème aux côtés du linting, l'optimisation de vitesse Shopify couvre le côté complémentaire du runtime.