Home › Shopify › Shopify Liquid theme rules
Shopify Liquid theme rules
Cursor rules for Shopify Online Store 2.0 themes: sections and blocks, JSON templates, Liquid performance, Theme Check.
CursorShopify
How to use
Save this as .cursor/rules/shopify-theme.mdc in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.
Note: Review and test before use. Provided as is, without warranty. See Terms.
.cursor/rules/shopify-theme.mdcDownload ---
description: Shopify Liquid theme conventions
globs: ["**/*.liquid","templates/*.json","sections/*.json","locales/*.json","assets/*.js"]
alwaysApply: false
---
# Shopify theme (Online Store 2.0)
- Develop with `shopify theme dev --store <store>`; lint with `shopify theme check`. Push/publish only when asked (`shopify theme push --unpublished`).
- Pages are JSON templates (`templates/*.json`) composed of sections. New features are sections (`sections/*.liquid`) with a `{% schema %}` defining settings, blocks, and presets so merchants can add them in the editor.
- Reusable markup goes in snippets rendered with `{% render 'card-product', product: product %}`; never `{% include %}`.
- All merchant-facing text comes from locales: `{{ 'products.add_to_cart' | t }}` with keys in `locales/en.default.json`; schema labels in `*.schema.json` locale files.
- Images: `{{ image | image_url: width: 800 | image_tag: loading: 'lazy', widths: '400,800,1200', sizes: '(min-width: 750px) 50vw, 100vw' }}`. The first/LCP image is not lazy.
- Avoid heavy Liquid loops: don't iterate over all products in a collection without `paginate`; limit nested loops; use `{% liquid %}` blocks for readability.
- JavaScript: small vanilla JS custom elements per section, loaded with `defer`. No jQuery. Use the Section Rendering API or Ajax Cart API for dynamic updates.
- CSS scoped per section (`{% stylesheet %}` or a section asset); respect the theme's color schemes and settings.
- Accessibility: labelled form controls, focus management in drawers/modals, `aria-live` for cart updates.
## Done when
`shopify theme check` reports no errors and the section works in the theme editor (add, reorder, change settings).