Shopify Theme Check: Por qué un argumento de ruta de archivo único no funciona (y qué hacer en su lugar)

Ejecutar shopify theme check ./sections/header.liquid no hace nada útil. El comando es sintácticamente inválido en la CLI actual: Theme Check no acepta un argumento de ruta de archivo posicional. La bandera de alcance correcta es --path, y solo acepta un directorio, no un archivo único. Aquí está exactamente qué funciona, por qué la linting de archivo único funciona diferente a lo que esperas, y cómo configurarlo correctamente en CI.

Puntos clave

• shopify theme check ./sections/header.liquid es inválido en la CLI de Shopify actual. No hay argumentos de archivo posicionales.
• Usa --path para apuntar a un directorio (por defecto el directorio de trabajo actual si se omite).
• La retroalimentación verdadera de archivo único proviene del Language Server de VS Code (themeCheck.onlySingleFileChecks), no de la CLI.
• El --fail-level predeterminado es error, por lo que CI pasa silenciosamente mientras las advertencias se acumulan. Siempre pasa --fail-level warning.
• A partir de Shopify CLI 4.0 (mayo de 2026), la herramienta requiere Node 22.12+ y se actualiza automáticamente a través de tu gestor de paquetes fuera de CI.

El error exacto que comete la mayoría de los desarrolladores

Estás editando sections/hero.liquid, detectas un posible problema de linting, y escribes:

shopify theme check ./sections/hero.liquid

Nada útil sucede. En la CLI actual, ese argumento posicional simplemente se ignora o produce un error sobre un directorio de tema faltante.

Esta confusión tiene una causa específica: Theme Check 2.x (la versión basada en Node que se envía dentro de Shopify CLI) reemplazó la gema de Ruby más antigua, y la gema de Ruby sí aceptaba un argumento de ruta posicional. Los tutoriales más antiguos, respuestas de StackOverflow y publicaciones de blog escritas antes de la migración de Theme Check 2.x (finalizada a principios de 2024, con --category y --exclude-category eliminadas al mismo tiempo) aún muestran la sintaxis antigua. Esas publicaciones ahora son incorrectas.

Como se confirma en la referencia de CLI propia de Shopify, --path es la única forma de determinar el alcance de una ejecución, y se aplica a un directorio, no a un archivo.

Lo que la bandera realmente hace

# Limitar a un directorio de tema específico
shopify theme check --path ./my-theme

# Por defecto al directorio de trabajo actual
shopify theme check

# Corregir automáticamente infracciones reparables en el lugar
shopify theme check -a

# Cambiar qué nivel de severidad causa una salida distinta de cero
shopify theme check --fail-level warning

# Salida legible por máquina (matriz plana por archivo)
shopify theme check -o json > results.json

# Listar cada verificación activa y su severidad
shopify theme check --list

--path le dice a Theme Check cuál es el directorio raíz del tema. Cada archivo dentro de ese directorio (plantillas, secciones, fragmentos, diseño, activos) se verifica en un solo paso. No puedes limitarlo a un archivo único en el nivel de CLI.

Cómo linting realmente un archivo único: el enfoque del Language Server

La CLI es una herramienta para temas completos. La retroalimentación de archivo único es tarea del Language Server de Liquid de Shopify, que potencia la extensión de Shopify Liquid para VS Code.

La extensión expone una configuración llamada themeCheck.onlySingleFileChecks. Cuando se establece en true, desactiva las verificaciones de tema completo (como UnusedSnippet y TranslationKeyExists) y solo verifica los archivos que están abiertos en el editor. Esto hace que las verificaciones de textDocument/didChange se ejecuten aproximadamente 125 veces más rápido en comparación con re-verificaciones de tema completo en cada pulsación de tecla.

Añade esto a tu configuración del espacio de trabajo de VS Code:

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

La compensación: te perderás verificaciones entre archivos mientras codificas. El patrón recomendado es ejecutar onlySingleFileChecks: true localmente para velocidad, luego ejecutar el shopify theme check completo en todo el tema en CI antes de cualquier push.

Comparación: CLI vs Language Server para retroalimentación de archivo único

La trampa de --fail-level que silenciosamente rompe CI

Esto engaña a casi todos los equipos que configuran una puerta de linting por primera vez.

Por defecto, --fail-level se establece en error. Eso significa que una ejecución que encuentra solo advertencias sale con código 0. Tu trabajo de CI verifica el código de salida, ve 0, marca el paso en verde, y esas advertencias se acumulan silenciosamente en docenas de PRs hasta que alguien finalmente nota un filtro deprecado o un problema de rendimiento que ha estado sentado en producción durante meses.

Arréglalo en una línea:

shopify theme check --fail-level warning

Niveles aceptados, de más a menos estrictos:

• info
• suggestion
• style
• warning
• error (por defecto)
• crash

Para la mayoría de las tiendas, warning es el umbral correcto. Detecta problemas reales sin bloquear sugerencias puramente estilísticas.

Un patrón de CI de nivel producción (GitHub Actions)

A continuación se muestra el patrón mínimo y actual. Usa SHOPIFY_CLI_THEME_TOKEN para autenticación no interactiva y bloquea la compilación en Theme Check antes de cualquier 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 }}

Ten en cuenta que --strict en theme push bloquea solo en errores de Theme Check, por lo que pasar --fail-level warning en el paso de verificación dedicado es la puerta correcta, no confiar solo en --strict.

Tres banderas más que vale la pena conocer

• -a / --auto-correct: corrige infracciones que Theme Check puede resolver sin criterio humano (espaciado dentro de {% %}, asignaciones sin usar). Ejecuta esto localmente, nunca ciegamente en CI.
• --list: imprime cada verificación habilitada y su severidad. Útil cuando un miembro del equipo añade un .theme-check.yml y quieres verificar el conjunto de reglas activas antes de un lanzamiento.
• -C theme-check:all: habilita cada verificación disponible, incluyendo las deshabilitadas en theme-check:recommended. Usa esto para una auditoría profunda periódica, no como una puerta diaria.

Lo que cambió en CLI 4.0 (mayo de 2026) que afecta tu configuración

Si tu pipeline comenzó a comportarse de manera extraña después de mayo de 2026, la causa es probablemente Shopify CLI 4.0. Dos cosas cambiaron que afectan las ejecuciones de theme check:

1. Node 22.12+ es ahora requerido. Los pipelines fijados a Node 18 o 20 fallarán en el paso de instalación.
2. La actualización automática se omite en CI. La CLI detecta entornos de CI y no se actualiza automáticamente, que es el comportamiento correcto. Pero las instalaciones locales del proyecto tampoco omiten la actualización automática, por lo que asegúrate de que tu pipeline instale explícitamente la versión que deseas.

Como bonificación, theme init ahora clona el tema Skeleton de Shopify de forma predeterminada en lugar de Dawn. Eso no afecta el comportamiento de Theme Check, pero importa si estás andamiando un nuevo proyecto en el mismo pipeline.

Errores comunes de .theme-check.yml

Tu archivo .theme-check.yml se encuentra en la raíz del tema y controla qué verificaciones se ejecutan y con qué severidad. Algunos patrones que causan confusión:

# Correcto: extender desde recomendado, luego anular
extend: theme-check:recommended

TemplateLength:
  enabled: false

UnusedAssign:
  severity: suggestion   # degradar desde warning

ParserBlockingJavaScript:
  enabled: true
  severity: error

• No uses --category o --exclude-category. Estas banderas fueron eliminadas en Theme Check 2.x. Usa el archivo YAML en su lugar.
• La clave root solo es necesaria cuando tus archivos de tema viven en un subdirectorio (por ejemplo, una carpeta de salida de compilación como dist/). No la necesitas para una estructura estándar de Dawn u Horizon.

Para una vista más amplia de cómo Theme Check encaja en un flujo de trabajo de tema Shopify completo, consulta mi guía sobre desarrollo de temas de Shopify y mejores prácticas de Liquid.

Si estás configurando esto en un pipeline de CI/CD como parte de una migración más grande o sistema de compilación, la página de servicio del desarrollador de temas de Shopify cubre cómo abordamos puertas de calidad automatizadas en proyectos de clientes.