shopify theme check --path vs Argumentos posicionales: La guía de sintaxis definitiva

Usa shopify theme check --path ./your-theme para limitar una ejecución de linting a un directorio. No hay argumentos posicionales en el Shopify CLI actual: shopify theme check ./sections/header.liquid es una sintaxis inválida y el CLI no hará linting de ese archivo. El flag --path es el único mecanismo que expone la herramienta para limitar el alcance de un directorio.

Puntos clave

• --path limita la ejecución a un directorio; no acepta una ruta de archivo individual.
• Los argumentos posicionales (por ejemplo, shopify theme check ./sections/header.liquid) no están soportados y no producen resultados útiles.
• Omitir --path por defecto usa el directorio de trabajo actual.
• La variable de entorno SHOPIFY_FLAG_PATH es el equivalente de CI de --path.
• Desde CLI 4.0 (lanzado en mayo de 2026), se requieren Node 22.12+ y Git 2.28+.

La confusión principal: por qué el comando parece que debería aceptar un archivo

Todos los linters populares (ESLint, Stylelint, RuboCop) aceptan un archivo posicional o un glob:

eslint src/main.js          # válido
stylelint "src/**/*.css"    # válido
shopify theme check ./sections/header.liquid  # INVÁLIDO

Shopify Theme Check no sigue esa convención. El comando theme check del CLI no acepta argumentos posicionales en absoluto. Si pasas una ruta como argumento posicional, el CLI no muestra un error de forma evidente; simplemente la ignora y hace linting del directorio de trabajo actual en su lugar. Ese fallback silencioso es lo que hace que este bug sea difícil de encontrar.

Esto importa más de lo que parece. Los desarrolladores depurando un archivo problemático a menudo ejecutan shopify theme check ./snippets/icon-sprite.liquid, ven un reporte de tema completo, asumen que la verificación pasó para ese archivo, y lo envían. La verificación nunca se ejecutó de forma aislada.

El flag --path: qué hace realmente

El flag --path le dice a Theme Check cuál es la carpeta que debe usar como raíz del tema. Por defecto usa el directorio de trabajo actual cuando se omite.

# Hacer linting del tema en el directorio actual (implícito)
shopify theme check

# Hacer linting de un tema en un subdirectorio
shopify theme check --path ./my-theme

# Hacer linting de un tema en una carpeta de salida de construcción
shopify theme check --path ./dist

Importante: --path debe apuntar a un directorio que contenga la estructura de carpetas estándar de Shopify (templates/, sections/, snippets/, etc.). Pasarle una ruta de archivo individual tampoco es válido.

El equivalente de variable de entorno es SHOPIFY_FLAG_PATH, que sigue el patrón de nomenclatura estándar SHOPIFY_FLAG_* que casi todos los demás flags usan en el CLI actual.

Referencia completa de flags para shopify theme check

Aquí están todos los flags que realmente usarás, con sus propósitos:

El flag --fail-level es especialmente importante para tuberías de CI. Por defecto, Theme Check solo sale con código 1 en problemas de severidad error. Si también quieres bloquear en advertencias, debes ser explícito:

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

Por qué no puedes hacer linting de un archivo individual con el CLI

Theme Check está diseñado como un linter de tema completo, no un linter de archivo. Muchas verificaciones dependen del contexto entre archivos:

• UnusedSnippet necesita saber cada archivo que llama a {% render %}.
• TranslationKeyExists necesita leer archivos de locales junto con tu Liquid.
• MissingTemplate necesita el directorio completo templates/ para verificar referencias.

Ejecutar una verificación de un solo archivo produciría resultados sin sentido para esas reglas entre archivos. Esa es una decisión de diseño deliberada, no un descuido. Si quieres retroalimentación por archivo mientras escribes, usa la extensión Shopify Liquid VS Code, que ejecuta el Protocolo de Servidor de Lenguaje (LSP) de Theme Check en tiempo real.

Fue un salto significativo cuando se lanzó Theme Check 2.0, unificando el linter y agregando características de LSP como documentos flotantes y autocompletado para configuraciones, traducciones, HTML y Liquid directamente dentro de los editores.

Qué cambió en CLI 4.0 (Mayo de 2026)

Si estás ejecutando tutoriales más antiguos, ten en cuenta que Shopify CLI 4.0, lanzado en mayo de 2026, introdujo varios cambios que afectan cómo se ejecuta theme check:

• Autoactualizacion por defecto: El CLI ahora se auto-actualiza a través de tu gestor de paquetes. La autoactualizacion se omite en entornos de CI y en bumps de versión mayor.
• Se requiere Node 22.12+ y Git 2.28+. Las versiones anteriores de Node lanzarán errores al instalar.
• theme init ahora clona Skeleton, no Dawn. Esto afecta qué estructura de tema se genera para nuevas construcciones.
• Sin comandos de login interactivos: No hay shopify login o shopify whoami en el CLI actual. La autenticación está basada en tokens.

Para tuberías de CI/CD, el patrón no interactivo documentado sigue siendo una puerta de linter seguida de un push:

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

Limitando Theme Check en CI: la forma correcta

Aquí hay un paso de GitHub Actions mínimo pero listo para producción:

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 usas la theme-check-action@v2 oficial de Shopify, el equivalente de path es la entrada theme_root, no un argumento posicional:

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

La entrada theme_root se asigna a --path internamente. La entrada flags te permite pasar cualquier flag adicional, incluyendo --fail-level.

Tres enfoques comparados

Silenciando falsos positivos sin desactivar verificaciones completas

Si Theme Check marca código válido (un filtro Liquid personalizado, una etiqueta de terceros), usa comentarios de supresión en línea en lugar de desactivar la verificación completa globalmente:

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

Para falsos positivos persistentes en múltiples archivos, la clave ignore en .theme-check.yml es más limpia:

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

Puedes generar una configuración inicial en cualquier momento con shopify theme check --init, que escribe un .theme-check.yml precargado con las configuraciones recomendadas de Shopify.

La cadena de precedencia de variables de entorno

La precedencia en el CLI actual es: flag > variable de entorno > shopify.theme.toml. Un flag --path en la línea de comandos anula SHOPIFY_FLAG_PATH en el entorno, que anula cualquier path establecido en el archivo toml. Un flag en línea perdido en un script anulará silenciosamente una variable de entorno de CI, que es una fuente común de confusión tipo "funciona localmente pero no en CI".

Si tu paso de CI aún está pidiendo interactivamente, agrega SHOPIFY_FLAG_FORCE=1 para suprimir avisos de confirmación.

Para una mirada más profunda a cómo encaja un flujo de trabajo profesional de desarrollo de temas, consulta mi guía sobre mejores prácticas de desarrollo de temas Shopify con Liquid. Si estás optimizando el rendimiento front-end de tu tema junto con linting, optimización de velocidad Shopify cubre el lado complementario del tiempo de ejecución.