Cursor rule

1---
2description: Liquid syntax standards
3globs: *.liquid
4alwaysApply: false
5---
6 
7# Liquid Syntax Standards
8 
9## ⚠️ CRITICAL: Schema Editing
10 
11**NEVER edit the `{% schema %}` block directly in `.liquid` files!**
12 
13Schemas are generated from source files in the `schemas/` folder. To make schema changes:
14 
151. Find the corresponding `.js` file in `schemas/blocks/` or `schemas/sections/`
162. Edit the JavaScript source file
173. Run `pnpm run build:schemas` to regenerate the `.liquid` files
18 
19See [@schemas](mdc:.cursor/rules/schemas.mdc) for more details.
20 
21---
22 
23## Valid Tags with Parameters
24 
25**Control Flow:**
26 
27- `if condition` / `endif` - Conditional logic
28- `unless condition` / `endunless` - Negative conditional
29- `case variable` / `when value` / `endcase` - Switch statement
30- `for item in array` / `endfor` - Loop with optional `limit:`, `offset:`
31 
32**Variable Assignment:**
33 
34- `assign variable = value` - Create variable
35- `capture variable` / `endcapture` - Capture output
36- `increment variable` - Add 1 to counter
37- `decrement variable` - Subtract 1 from counter
38 
39**Template Inclusion:**
40 
41- `render 'snippet-name'` - Include snippet
42- `render 'snippet-name', param: value` - With parameters
43- `section 'section-name'` - Include section
44 
45**Forms:**
46 
47- `form 'cart'` / `endform` - Cart form
48- `form 'product'` / `endform` - Product form
49- `form 'customer_login'` / `endform` - Login form
50 
51**Other:**
52 
53- `paginate collection.products by 12` / `endpaginate` - Paginate results
54- `liquid` / `endliquid` - Multiline Liquid block
55- `comment` / `endcomment` - Block comments
56- `raw` / `endraw` - Output without processing
57 
58## Valid Filters
59 
60**Array Filters:**
61 
62- `compact` - Remove nil values: `array | compact`
63- `concat` - Join arrays: `array | concat: array`
64- `find` - Find object: `array | find: property, value`
65- `where` - Filter objects: `array | where: property, value`
66- `map` - Extract property: `array | map: property`
67- `sort` - Sort array: `array | sort`
68- `reverse` - Reverse order: `array | reverse`
69- `first` - First item: `array | first`
70- `last` - Last item: `array | last`
71- `size` - Count items: `array | size`
72 
73**String Filters:**
74 
75- `escape` - HTML escape: `string | escape`
76- `truncate` - Limit length: `string | truncate: 150`
77- `handleize` - URL handle: `string | handleize`
78- `replace` - Replace text: `string | replace: 'old', 'new'`
79- `split` - Split string: `string | split: 'delimiter'`
80- `upcase` - Uppercase: `string | upcase`
81- `downcase` - Lowercase: `string | downcase`
82- `capitalize` - Capitalize: `string | capitalize`
83 
84**Money Filters:**
85 
86- `money` - Format price: `price | money`
87- `money_with_currency` - With symbol: `price | money_with_currency`
88- `money_without_currency` - No symbol: `price | money_without_currency`
89 
90**Media Filters:**
91 
92- `image_url` - Responsive image: `image | image_url: width: 800`
93- `image_tag` - Complete img tag: `image | image_tag`
94- `asset_url` - Theme asset: `'style.css' | asset_url`
95 
96## Syntax Rules
97 
98- Use `{% liquid %}` for multiline code blocks
99- Use `{% # comment %}` for inline comments
100- Never invent new filters, tags, or objects
101- Follow proper tag closing order (last opened, first closed)
102- Use object dot notation: `product.title` not `product['title']`
103- Respect object scope and availability
104 
105## Snippet Documentation with {% doc %}
106 
107All snippets must include documentation using `{% doc %}` and `{% enddoc %}` tags.
108 
109**Parameter types:** `{object}`, `{string}`, `{number}`, `{boolean}`, `{array}`
110**Optional params:** Use brackets like `[param_name]`
111**Nested properties:** Use dash notation like `object - .property`
112 
113**Example:**
114 
115```liquid
116{% doc %}
117  Volume Pricing Info
118 
119  Renders volume pricing information with quantity rules in a popover.
120  Only renders if variant has quantity rules or volume pricing.
121 
122  @param {object} variant - The variant object to display pricing for
123  @param {string} [unique_id] - Optional unique identifier to append to popover ID
124  @param {number} [quantity] - The current quantity (for highlighting active tier)
125 
126  @example
127  {% render 'volume-pricing-info',
128    variant: item.variant,
129    unique_id: item.index,
130    quantity: item.quantity
131  %}
132{% enddoc %}
133```
134 
135## Inline Variables Pattern
136 
137For props that are relatively straightforward, prefer to inline the liquid instead of declaring extra variables. In smaller components it doesn't make a big difference, but in bigger ones it helps not having to scroll up and down to know what is being applied where.
138 
139**✅ Do this (inline approach):**
140 
141```liquid
142<div
143  class='component component--{{ settings.style_modifier }}'
144  style='
145    color: {{ settings.text_color }};
146    {% if settings.show_border %}
147      border: 1px solid {{ settings.border_color }};
148    {% endif %}
149  '
150>
151  <h2>{{ 'sections.component.title' | t }}</h2>
152 
153  {{ content | truncate: settings.max_length | default: 200 }}
154 
155  <a
156    href='{{ link_url }}'
157    class='link--{{ settings.link_style | default: 'primary' }}'
158  >
159    {{ 'general.read_more' | t }}
160  </a>
161</div>
162```
163 
164**❌ Don't do this (variable declaration approach):**
165 
166```liquid
167{% liquid
168  assign component_class = 'component component--' | append: settings.style_modifier
169  assign text_color = settings.text_color
170  assign truncate_length = settings.max_length | default: 200
171  assign link_class = 'link--' | append: settings.link_style | default: 'primary'
172%}
173 
174{% capture component_style %}
175  color: {{ text_color }};
176  {% if settings.show_border %}
177    border: 1px solid {{ settings.border_color }};
178  {% endif %}
179{% endcapture %}
180 
181<div
182  class='{{ component_class }}'
183  style='{{ component_style }}'
184>
185  <h2>{{ 'sections.component.title' | t }}</h2>
186 
187  {{ content | truncate: truncate_length }}
188 
189  <a
190    href='{{ link_url }}'
191    class='{{ link_class }}'
192  >
193    {{ 'general.read_more' | t }}
194  </a>
195</div>
196```
197 
198**Exceptions:**
199 
200- When Liquid filter parameters require string values and complex logic cannot be inlined
201- When the same complex calculation is used multiple times
202- When the logic is extremely complex and would harm readability
203- When you need to build a string incrementally with conditional parts
204 
205**Benefits:**
206 
207- Easier to understand what's being applied where
208- No need to scroll up and down to find variable definitions
209- Reduces cognitive load in larger components
210- Makes the code more maintainable
211