Shopify Theme Check: Verificar Archivos y Secciones Específicas con CLI

Para ejecutar Shopify Theme Check en archivos o secciones específicas, tienes tres opciones: pasar un argumento de ruta directamente al CLI, usar comentarios Liquid inline para desactivar verificaciones en bloques de código específicos, o configurar un patrón ignore en tu archivo .theme-check.yml. No existe un único flag --only que restrinja la salida a un archivo, pero combinando estos tres enfoques obtienes control preciso sobre qué se valida y qué se omite.

Puntos clave

• shopify theme check ./sections/hero.liquid limita la ejecución a un archivo específico.
• Los comentarios inline {% # theme-check-disable %} suprimen verificaciones para un bloque de código Liquid.
• .theme-check.yml te permite ignore patrones glob completos (por ejemplo, snippets/icon-*) de forma permanente.
• El flag --config anula tu archivo de configuración sobre la marcha, útil en pipelines CI.
• La gema Ruby heredada Shopify/theme-check fue archivada en julio de 2024; el linter actual está dentro de Shopify CLI a través de los paquetes @shopify/cli y @shopify/theme.

Por qué importa el linting dirigido (y de dónde viene la confusión)

Ejecutar shopify theme check contra un tema grande con cientos de archivos Liquid genera una avalancha de advertencias. La mayoría de los desarrolladores quieren validar solo el archivo en el que están trabajando, o suprimir una verificación ruidosa para una sección sin desactivarla en todo el tema. La documentación del CLI aborda esto, pero está dispersa en tres páginas separadas, por lo que esta pregunta sigue apareciendo.

La buena noticia: la herramienta es genuinamente flexible. Una vez que sabes qué palanca tirar para cada caso de uso, el flujo de trabajo es rápido.

Método 1: Pasar una ruta de archivo como argumento posicional

El enfoque más directo. En lugar de ejecutar Theme Check contra la raíz completa del tema, añade la ruta relativa del archivo o directorio que quieres verificar:

shopify theme check sections/custom-hero.liquid
shopify theme check snippets/product-card.liquid
shopify theme check sections/

Esto le indica al linter que analice solo ese archivo o carpeta. Una advertencia importante: las verificaciones de todo el tema se suprimen parcialmente cuando te limitas a un archivo. Las verificaciones que requieren conciencia entre archivos, como UnusedSnippet o TranslationKeyExists, se desactivan en modo de archivo único porque necesitan leer el tema completo para producir un resultado significativo.

Para errores estrictamente a nivel de archivo (sintaxis Liquid, filtros obsoletos, objetos indefinidos, etiquetas {% endschema %} faltantes), el alcance de archivo único funciona perfectamente.

Método 2: Suprimir verificaciones inline con comentarios Liquid

Cuando quieres mantener una ejecución amplia de shopify theme check pero silenciar una verificación específica para una sección de código, usa las directivas de comentarios integradas de Theme Check:

{% # theme-check-disable UnusedAssign %}
{% assign debug_mode = true %}
{% # theme-check-enable UnusedAssign %}

Para desactivar todas las verificaciones para un bloque:

{% # theme-check-disable %}
  {# ...código heredado que aún no has migrado... #}
{% # theme-check-enable %}

Este enfoque es la opción correcta cuando estás iterando en una sección personalizada compleja, heredando una base de código de tema desordenada, o añadiendo Theme Check a un proyecto que tiene un gran backlog de problemas preexistentes que no estás listo para resolver de una sola vez. Los comentarios están ampliamente limitados: nada fuera de esos delimitadores se ve afectado.

Método 3: Configurar patrones ignore en .theme-check.yml

Para rutas que quieres excluir permanentemente, el archivo de configuración .theme-check.yml es la herramienta correcta. Puedes generar un archivo de inicio con:

shopify theme check --init

Luego edita el archivo para añadir globs ignore bajo verificaciones específicas o globalmente:

TemplateLength:
  enabled: true
  max_length: 400
  ignore:
    - sections/legacy-homepage.liquid
    - snippets/icon-*

También puedes establecer niveles de severidad por verificación (error, warning, info) para que ciertos problemas causen fallo en una ejecución CI mientras que otros se reportan solo como informativos. Por defecto, Theme Check retorna código de salida 1 cuando se detecta al menos un problema con severidad error. Usa --fail-level para ajustar este umbral en tu pipeline:

shopify theme check --fail-level suggestion

Método 4: Anular la configuración sobre la marcha con --config

Si mantienes múltiples perfiles de verificación (uno estricto, uno permisivo), el flag --config te permite cambiar entre ellos sin editar ningún archivo:

shopify theme check --config theme-check:recommended
shopify theme check --config theme-check:all

Estos presets integrados cubren los escenarios más comunes. theme-check:recommended es el predeterminado para la mayoría de envíos de temas; theme-check:all habilita todas las verificaciones disponibles y es útil para una auditoría exhaustiva antes de publicar en la Shopify Theme Store.

Qué cambió en 2024: repositorio theme-check archivado

Si tienes marcadores antiguos o tutoriales que hacen referencia a la gema Ruby autónoma Shopify/theme-check, ten en cuenta que este repositorio fue archivado como solo lectura en julio de 2024. Todo el desarrollo activo se trasladó al monorepo Shopify/theme-tools, y el linter ahora se distribuye a través de los paquetes npm @shopify/cli y @shopify/theme.

Para instalar o actualizar:

# macOS
brew upgrade shopify-cli

# npm (global)
npm install -g @shopify/cli @shopify/theme

A partir de Shopify CLI 4.0, el CLI se actualiza automáticamente usando el gestor de paquetes con el que lo instalaste, así que en la mayoría de los casos ya estás en la versión más reciente.

La extensión de VS Code (Shopify Liquid) también incluye Theme Check y expone una configuración themeCheck.onlySingleFileChecks. Cuando se establece en true, la extensión solo verifica el archivo actualmente abierto, desactivando verificaciones de tema completo por rendimiento. Esto refleja el comportamiento de ruta de archivo único del CLI y vale la pena habilitarlo en temas grandes donde el linting de tema completo en cada guardado ralentiza el editor.

Juntarlo todo: un flujo de trabajo práctico para desarrollo de secciones

Aquí está el patrón que funciona bien cuando construyes o depuras una sección Liquid personalizada:

1. Inicia un servidor de desarrollo: shopify theme dev --store your-store.myshopify.com
2. Edita tu sección: realiza cambios en sections/your-section.liquid
3. Valida solo ese archivo: shopify theme check sections/your-section.liquid
4. Suprime verificaciones ruidosas inline para cualquier problema preexistente que no estés solucionando hoy.
5. Ejecuta una verificación completa (shopify theme check) antes de abrir un pull request o hacer push a producción.
6. Bloquea CI solo en errores usando --fail-level error para que las advertencias no causen fallos en despliegues.

Este enfoque mantiene tu bucle de retroalimentación interno rápido mientras atrapa errores reales antes de que lleguen a los clientes.

Mantener el código de tu tienda limpio es una capa de la pila de operaciones. La otra capa es saber, todos y cada uno de los días, qué productos están a punto de agotarse y te costarán ventas reales. Si gestionas inventario en docenas o cientos de SKU, Stockcast: Inventory Forecast muestra predicciones de agotamiento clasificadas por urgencia con matemáticas transparentes y explicables detrás de cada recomendación, para que las decisiones de reorden nunca sean una suposición.

Prueba Stockcast: Inventory Forecast en la Shopify App Store

Preguntas frecuentes

¿Puedo ejecutar shopify theme check en un archivo de sección Liquid individual? Sí. Pasa la ruta del archivo como argumento posicional: shopify theme check sections/your-section.liquid. Ten en cuenta que las verificaciones de tema completo (como la detección de snippets sin usar) se desactivan cuando te limitas a un archivo único, ya que requieren leer el tema completo para funcionar correctamente.

¿Cómo desactivo una regla de Theme Check específica para un bloque de código sin apagarla en todas partes? Usa directivas de comentarios Liquid inline: {% # theme-check-disable CheckName %} antes del bloque y {% # theme-check-enable CheckName %} después. Esto suprime solo esa verificación nombrada dentro del bloque delimitado y deja el resto del archivo y el tema completamente validados.

¿Qué pasó con la gema theme-check autónoma y el CLI en 2024? Shopify archivó el repositorio de la gema Ruby Shopify/theme-check en julio de 2024 y trasladó todo el desarrollo activo al monorepo Shopify/theme-tools. Theme Check ahora se distribuye como parte de @shopify/cli y se ejecuta a través de shopify theme check. Si estás en una configuración más antigua, actualiza con brew upgrade shopify-cli o npm install -g @shopify/cli @shopify/theme.