Shopify Theme Check: Cómo dirigirse a rutas de archivo específicas y archivos Liquid de secciones

Shopify Theme Check no puede aceptar una única ruta de archivo como argumento posicional. Ejecutar shopify theme check sections/hero.liquid no lintará solo ese archivo. La herramienta siempre valida el árbol de temas completo, pero varias técnicas compatibles te permiten limitar lo que se verifica, lo que sale con un error y lo que aparece en tu salida. Aquí hay todos los métodos que funcionan, incluidos los cambios introducidos en Theme Check 2.x.

Puntos clave

• shopify theme check sections/hero.liquid es sintaxis inválida y sale con un error en Theme Check 2.x.
• --path limita la ejecución a un subdirectorio, no a un único archivo.
• La salida JSON (-o json) canalizada a través de jq es la única forma confiable de filtrar resultados a un archivo específico.
• .theme-check.yml puede ignorar patrones glob completos, silenciando el ruido de archivos de terceros o generados.
• Los comentarios en línea {% # theme-check-disable CheckName %} suprimen reglas específicas dentro de cualquier archivo Liquid.
• Desde CLI 4.0 (mayo de 2026), Theme Check necesita Node 22.12+ y la herramienta se actualiza automáticamente a través de tu gestor de paquetes.

Por qué no hay un argumento de archivo único

Theme Check es un linter de tema completo, no un verificador de sintaxis archivo por archivo. Muchas de sus reglas están diseñadas para ser entre archivos: MissingSnippet comprueba si una llamada {% render %} se resuelve a un archivo real en otro lugar del tema, y UnusedAssign necesita ver cada plantilla que podría consumir una variable. Ejecutarlo contra un solo archivo de forma aislada produciría falsos positivos en exactamente esas comprobaciones.

Debido a ese diseño, la documentación oficial de CLI de Shopify confirma que Theme Check está destinado a analizar el árbol de temas completo. No hay bandera --file o --only en la CLI actual.

Método 1: --path para limitar un subdirectorio

La aproximación más cercana compatible al linting de archivo único es --path. Le dice a Theme Check dónde vive la raíz del tema, no qué archivo verificar. Pero puedes combinarlo con una estructura de directorios creativa durante CI para acercarte:

# Lint el tema completo desde el directorio de trabajo actual (predeterminado)
shopify theme check

# Lint un tema que vive dentro de un subdirectorio
shopify theme check --path ./my-theme

Si tu carpeta de secciones es la única parte del repositorio que ha cambiado en un PR determinado, puedes apuntar --path a una copia temporal que contenga solo los archivos modificados. Esto es exagerado para la mayoría de los equipos, pero es útil cuando un monorepo contiene múltiples temas.

Lo que --path NO hace: no acepta un único archivo como sections/hero.liquid como su valor. Pasa un directorio, no una ruta de archivo.

Método 2: Salida JSON canalizada a jq para filtrado por archivo

Este es el método más práctico para dirigirse a un archivo específico sections/*.liquid en un pipeline de CI. La bandera -o json de Theme Check emite una matriz plana legible por máquina codificada por ruta de archivo. Canalízala a través de jq para extraer solo la entrada que te interesa:

# Ejecuta la verificación completa, salida JSON, luego filtra a un archivo
shopify theme check -o json \
  | jq '.[] | select(.path == "sections/hero.liquid")'

También puedes afirmar un código de salida distinto de cero tú mismo basado en el resultado filtrado:

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

Este patrón te da el equivalente a portería por archivo en tu trabajo de GitHub Actions o GitLab CI, sin necesitar una bandera que no existe.

Método 3: Patrones de ignorancia de .theme-check.yml

Si el objetivo es silenciar un archivo o carpeta específica en lugar de dirigirse a él, .theme-check.yml admite listas de ignorancia basadas en glob por comprobación. También puedes ignorar directorios completos de todas las comprobaciones usando la clave de nivel superior ignore:

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

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

Genera una configuración inicial con:

shopify theme check --init

Esto es especialmente útil cuando tienes archivos generados o de terceros (como fragmentos de Replo) que contienen Liquid intencionalmente dividido que de otro modo desencadenaría LiquidHTMLParsingError en theme dev.

Método 4: Comentarios de supresión en línea dentro de secciones Liquid

Para reglas ocasionales dentro de un archivo de sección específico, los comentarios en línea Liquid te permiten deshabilitar y reactivar cualquier comprobación nombrada alrededor de un bloque de código:

{%- comment -%} Suppress false positive from vendor render pattern {%- endcomment -%}
{% # theme-check-disable UnusedAssign %}
{%- assign hero_context = section.settings.context -%}
{% # theme-check-enable UnusedAssign %}

También puedes suprimir una comprobación para el archivo completo colocando el comentario de deshabilitación en la primera línea:

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

Este enfoque es visible en la revisión de código (aparece como un diff de una línea) y no afecta a ningún otro archivo del tema.

Método 5: VS Code onlySingleFileChecks para desarrollo local

Si tu objetivo es una retroalimentación rápida en tu editor mientras editas activamente un archivo de sección, la extensión Shopify Liquid de VS Code tiene una configuración que limita Theme Check solo al archivo abierto:

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

Con esto activado, se omiten las comprobaciones entre archivos (como MissingSnippet) y solo se ejecutan reglas de archivo único en la pestaña activa. El repositorio oficial la describe como "excelente para el rendimiento si puedes ignorar comprobaciones que abarcan múltiples archivos durante el desarrollo". Ejecuta el shopify theme check completo en CI para detectar los problemas entre archivos.

Comparación: todos los métodos lado a lado

Requisitos de CLI 4.0 que no debes pasar por alto (mayo de 2026)

Desde que se lanzó CLI 4.0 en mayo de 2026, dos requisitos cambiaron que afectan a cada pipeline de CI que ejecuta Theme Check:

• Se requiere Node 22.12+. Las versiones anteriores de Node fallarán silenciosamente o producirán una salida inesperada.
• La herramienta se actualiza automáticamente a través de tu gestor de paquetes y omite la actualización automática dentro de CI por diseño. Fija tu versión en package.json o en tu imagen de CI explícitamente.

También vale la pena saber: --category y --exclude-category fueron eliminados en Theme Check 2.x (enero de 2024). Si encuentras tutoriales más antiguos que muestren esas banderas, ya no funcionan. Usa -C theme-check:all para ejecutar explícitamente cada comprobación disponible.

Patrón de portería de CI: la forma correcta de ejecutar Theme Check en un pipeline

Aquí está la secuencia de pipeline idiomática recomendada por la propia documentación de Shopify:

# 1. Portería en errores (y advertencias, que la mayoría de los equipos ignoran por defecto)
shopify theme check --fail-level warning

# 2. Empuja a un tema de desarrollo no publicado para vista previa
shopify theme push --unpublished --json

# 3. Promover solo después de revisión manual
shopify theme publish --theme <ID> --force

Dos errores comunes a evitar:

• El --fail-level predeterminado es error, lo que significa que las advertencias se acumulan silenciosamente y tu trabajo de CI aún sale con 0. Pasa --fail-level warning para bloquearlas.
• --strict en theme push también bloquea el push a menos que Theme Check pase, lo que te da una segunda red de seguridad en el momento de la implementación.

Para temas de vista previa por RP, shopify theme push --development-context "pr-482" vincula un tema de desarrollo a un identificador estable como un número de RP.

Ponerlo todo junto: el flujo de trabajo práctico para secciones Liquid

Aquí está la secuencia en la que la mayoría de los equipos terminan después de pasar por lo anterior:

1. Editor: habilita onlySingleFileChecks en VS Code para una retroalimentación rápida y en el archivo mientras escribes sección Liquid.
2. Hook anterior al commit: ejecuta shopify theme check --fail-level error contra el tema completo antes de que un commit suba.
3. Portería de RP de CI: ejecuta shopify theme check -o json | jq para extraer y afirmar solo en los archivos de sección cambiados.
4. Portería de implementación de CI: ejecuta shopify theme push --strict para que incluso si alguien omite el paso 3, se bloquee un push con errores.
5. Configuración: mantén un .theme-check.yml con globs de ignorancia específicos para cualquier fragmento generado o de proveedor para evitar falsos positivos que detengan el trabajo real.

¿Necesitas ayuda para conectar esto a un pipeline real? La página de servicios de desarrollador de tema Shopify tiene contexto sobre cómo configuro esto para proyectos de clientes, y la optimización de velocidad de Shopify cubre las comprobaciones de rendimiento que Theme Check marca más a menudo.