DEV Community: Yakhyo Ismoildjonov

The Ultimate Guide to Shopify Cart Debugging: How to Save Hours with Shopify Theme Devtools Cart Panel

Yakhyo Ismoildjonov — Wed, 14 Jan 2026 06:12:54 +0000

TL;DR: Stop console.logging your cart state. Shopify Theme Devtools gives you a visual cart inspector, history tracking, test automation, and scenario management—all in your browser while developing themes.

Introduction: Why Cart Debugging is Painful

If you've developed Shopify themes, you know the pain:

Manually adding products to test cart states
Using console.log({{ cart | json }}) to debug
Rebuilding complex carts after every page refresh
No way to test edge cases like gift-with-purchase items or subscriptions
Tracking down which JavaScript is modifying your cart

Shopify Theme Devtools solves all of this with a dedicated Cart Panel that transforms how you debug and test cart functionality.

What is Shopify Theme Devtools?

Shopify Theme Devtools is an open-source, in-browser developer panel for Shopify theme development. Think of it as Chrome DevTools, but specifically designed for Liquid and Shopify.

The Cart Panel is one of its most powerful features—a complete cart management and debugging toolkit that runs directly in your development theme.

Key Features:

Real-time cart state inspection
Visual cart history with diff tracking
Saveable cart scenarios for testing
Automated cart validation tests
AJAX request interception
One-click cart restoration

Getting Started

Installation

npx shopify-theme-devtools init

This adds the Liquid snippet to your theme. The devtools only render on unpublished themes, so your live store is never affected.

Accessing the Cart Panel

Once installed, you'll see a floating devtools panel on your development theme. Click the Cart tab to access all cart debugging features.

Feature 1: Real-Time Cart Inspector

The Problem

Debugging cart state usually means adding {{ cart | json }} to your template, refreshing, copying the JSON, and pasting it into a formatter. Repeat for every change.

The Solution

The Cart Panel shows your complete cart state in a clean, interactive interface:

At a glance, you see:

Total items and price
Currency and total weight
Active discount codes with savings
Cart attributes and notes

For each line item:

Product thumbnail, title, and variant
SKU and quantity
Original price vs. discounted price (with percentage saved)
Selling plan details for subscriptions

Expandable Item Details

Click any item to reveal:

Variant ID, Product ID, and Item Key
Vendor and product type
Complete line item properties
Discount breakdowns by code
Selling plan allocation details

Quick Actions:

Copy Variant ID, Product ID, or Item Key to clipboard
Duplicate item (preserves all properties)
Remove item instantly

Example Use Case

You're debugging why a discount isn't applying correctly. Instead of digging through JSON:

Open Cart Panel
Expand the item in question
See the exact discount allocation and compare with expected values
Notice the discount is applying to line_price but your theme is displaying original_line_price

Time saved: 15+ minutes per debugging session

Feature 2: Cart History & Time Travel

The Problem

You've finally reproduced a cart bug after 10 minutes of adding products. You refresh the page to test your fix—and the cart state is gone or changed.

The Solution

Cart History automatically tracks every cart change with timestamps and visual diffs.

What gets tracked:

Items added (green)
Items removed (red)
Quantity changes (orange with old→new values)
Attribute modifications
Note changes
Discount code applications

One-Click Restoration

See a historical cart state you need? Click Restore and the Cart Panel:

Clears your current cart
Re-adds all items with their exact properties
Restores cart attributes and notes
Maintains selling plan allocations

The entire process takes ~2 seconds.

Example Use Case

You're testing a "free gift at $100" promotion:

Build a cart worth $95
Add a $10 item → gift appears
Test your Liquid display logic
Realize you need to test the $95 state again
Click Restore on the $95 history entry
Continue testing

Time saved: 5-10 minutes per cart rebuild

Feature 3: Cart Scenarios (Saved Cart States)

The Problem

You have 8 different cart configurations you need to test:

Empty cart
Single item
Multiple items
Items with properties (personalization)
Subscription items
Gift-with-purchase items
Mixed cart with discounts
Maximum quantity cart

Rebuilding these manually for every test cycle is exhausting.

The Solution

Cart Scenarios let you save, name, and instantly load predefined cart states.

Creating a Scenario

Build your desired cart state
Click Scenarios → Save Current Cart
Name it (e.g., "GWP Test - $100 threshold")
The scenario saves all items, quantities, properties, attributes, and notes

Loading a Scenario

Click Scenarios
Select your saved scenario
Choose to clear cart first or add to existing
Cart is populated instantly

Scenario Editor

Need to tweak a scenario without rebuilding the cart?

Add/remove items by variant ID
Modify quantities
Add line item properties
Set cart attributes
Include cart notes

Import/Export

Share scenarios with your team:

// Exported scenario file
{
  "name": "GWP Test Cart",
  "items": [
    { "variant_id": "12345678", "quantity": 2, "properties": { "_is_gwp": "true" } }
  ],
  "attributes": { "gift_message": "Happy Birthday!" },
  "note": "Test order - do not fulfill"
}

Example Use Case

Your QA team needs to test 12 different cart states for a new promotion:

Developer creates all 12 scenarios
Exports as JSON file
QA imports into their devtools
QA can now test all 12 states in under a minute

Time saved: Hours of manual cart building across team members

Feature 4: Automated Cart Tests

The Problem

Cart validation logic is complex. Gift-with-purchase items need specific properties. Quantity limits must be enforced. Bundles require companion products. How do you catch these issues before they reach production?

The Solution

Cart Tests let you define validation rules that run automatically against your cart state.

Four Rule Types

1. Property Dependency Rules

"If item has property X, it must also have properties Y and Z"

IF item has property "_is_gwp" = "true"
THEN item MUST have properties: "_gwp_price", "_gwp_source", "_gwp_campaign"

Use cases:

Gift-with-purchase validation
Personalization requirements
Pre-order expected ship dates
Custom product data integrity

2. Field Value Rules

"If item field equals X, then another field must equal Y"

IF item product_type = "Gift Card"
THEN item quantity MUST equal 1

Use cases:

Gift card quantity limits
Digital product shipping flags
SKU requirements
Subscription validation

3. Cart Composition Rules

"If cart contains item X, cart must also contain item Y"

IF cart contains item with product_type = "Electronics"
THEN cart MUST contain item with product_type = "Warranty"

Use cases:

Required accessories
Bundle completeness
Warranty requirements
Cross-sell validation

4. Quantity Rules

"Item/cart quantities must meet min/max/multiple constraints"

SCOPE: per-item
MAX: 10
(No item can have quantity > 10)

SCOPE: cart-total
FILTER: product_type = "Sample"
MAX: 3
(Maximum 3 sample products in cart)

Use cases:

Per-item limits
Cart maximums
Bulk order minimums (B2B)
Sample product limits
Pack quantity enforcement (multiples of 6)

Pre-Built Templates

Don't want to configure from scratch? Choose from 13 pre-built templates:

[Property] GWP Validation
[Property] Personalization Check
[Property] Pre-order Validation
[Field] Gift Card Qty = 1
[Field] Subscription Valid
[Field] Digital Products Check
[Field] SKU Required
[Composition] Warranty Required
[Composition] Bundle Check
[Qty] Max Per Item (10)
[Qty] Cart Max (50 items)
[Qty] Pack of 6 Only
[Qty] Samples Max 3

Auto-Run Tests

Enable Auto-run and tests execute automatically whenever your cart changes. Failed items are highlighted with a red border directly in the cart display.

Test Results

Summary shows pass/fail count
Failed tests show detailed error messages
Specific items causing failures are identified
First 5 failures displayed with "+N more" indicator

Example Use Case

You're implementing a gift-with-purchase promotion:

Create a test: "GWP items must have _gwp_price property"
Enable auto-run
Add a GWP item to cart
Test immediately fails—missing required property
Fix your GWP logic to include the property
Test passes automatically
Ship with confidence

Time saved: Catching bugs before they reach production = priceless

Feature 5: Quick Cart Actions

Add Items Instantly

No need to browse to product pages. Enter a variant ID and quantity, click Add, and the item is in your cart.

Variant ID: 12345678901234
Quantity: 2
[Add]

Apply Discount Codes

Test discount logic directly from the panel without going through checkout:

Discount Code: SAVE20
[Apply]

Cart Permalink

Need to share a specific cart state? Click Link to copy a permalink:

https://yourstore.com/cart/12345678:2,87654321:1

Export Cart JSON

Click Export to download your complete cart state as JSON for documentation or bug reports.

Feature 6: Network Request Tracking

The Problem

Something is modifying your cart unexpectedly. Is it a third-party app? A theme script? A Shopify feature?

The Solution

The Cart Panel intercepts and logs all cart-related AJAX requests:

Tracked endpoints:

/cart.js
/cart/add.js
/cart/update.js
/cart/change.js
/cart/clear.js

For each request, you see:

HTTP method and status
Request/response timing
Request body and headers
Response data
Source identification (which script made the request)

Request Blocking

Found a rogue script modifying your cart? Block requests by source to isolate the issue:

Identify the problematic request
Click Block Source
Future requests from that script are prevented
Continue debugging without interference

Best Practices

1. Create Scenario Libraries

Build a comprehensive set of scenarios for your store:

├── Basic States
│   ├── Empty cart
│   ├── Single item
│   └── Multiple items
├── Edge Cases
│   ├── Max quantity (per item)
│   ├── Max items (cart limit)
│   └── Zero-price items
├── Features
│   ├── Gift with purchase
│   ├── Subscription items
│   ├── Personalized items
│   └── Pre-order items
└── Promotions
    ├── Percentage discount
    ├── Fixed amount discount
    ├── Free shipping threshold
    └── BOGO promotion

2. Write Tests for Business Rules

Document your business logic as automated tests:

Business Rule	Test Type	Configuration
Gift cards qty = 1	Field Value	`product_type = "Gift Card"` → `quantity = 1`
GWP has tracking	Property Dependency	`_is_gwp = true` → requires `_gwp_source`
Electronics need warranty	Cart Composition	`product_type = "Electronics"` → requires `product_type = "Warranty"`
Max 3 samples	Quantity	`cart-total`, `max: 3`, filter: `product_type = "Sample"`

3. Use History for Regression Testing

Build the cart state for your bug
Fix the bug
Use History to restore the original state
Verify the fix
Save as a scenario for future regression testing

4. Share Scenarios with Your Team

Export scenarios as JSON
Commit to your repository
Import on each developer's machine
Everyone can test the same edge cases

5. Enable Auto-Run Tests During Development

Keep tests running automatically while you code. Instant feedback when something breaks.

Comparison: Before vs. After

Task	Without Devtools	With Cart Panel
Inspect cart state	Add Liquid, refresh, copy JSON, format	Click Cart tab
Rebuild specific cart	5-10 min manual work	2 seconds (scenario load)
Test 10 cart states	50-100 minutes	5 minutes
Track cart changes	Custom logging code	Automatic history
Validate GWP logic	Manual testing	Automated tests
Find rogue cart scripts	Console debugging	Request tracking
Share cart states	Screenshots, instructions	JSON export

Common Questions

Does this work on live stores?

No. The devtools only render on unpublished themes for security.

Does it modify my theme code?

It adds a single Liquid snippet that conditionally loads the devtools JavaScript.

Can I use it with any Shopify plan?

Yes. It works with Basic, Shopify, Advanced, and Plus plans.

Is it free?

Yes. Shopify Theme Devtools is open source.

Conclusion

The Cart Panel in Shopify Theme Devtools transforms cart debugging from a tedious, time-consuming task into a streamlined workflow. Whether you're:

Debugging a discount issue
Testing gift-with-purchase logic
Validating subscription cart behavior
Building complex promotional carts
Catching cart validation bugs

...you'll save hours of development time.

Get started:

npx shopify-theme-devtools init

Resources

GitHub Repository

Tags: #shopify #shopifythemes #shopifydevelopment #liquid #ecommerce #webdevelopment #javascript #debugging #devtools #tutorial

How to Debug Shopify Liquid: A Complete Guide

Yakhyo Ismoildjonov — Wed, 14 Jan 2026 05:47:45 +0000

Debugging Shopify Liquid templates is notoriously difficult. There's no built-in debugger, no breakpoints, no step-through execution. When something breaks, you're often left staring at a blank page or cryptic error message with no clear path forward.

This guide covers every method for debugging Liquid — from basic techniques to advanced tooling — so you can diagnose and fix issues faster.

Why Is Liquid Hard to Debug?

Liquid is a templating language, not a programming language. It runs server-side on Shopify's infrastructure, which means:

No browser DevTools — You can't inspect Liquid like you inspect JavaScript
No console.log — There's no native way to print debug output
Silent failures — Many errors render as empty strings instead of error messages
No stack traces — When something breaks, you don't know where
Server-rendered — Every change requires a page refresh to test

This makes debugging a slow, frustrating process of trial and error.

Method 1: The JSON Filter

The most common debugging technique is outputting objects as JSON:

{{ product | json }}

This renders the entire product object as a JSON string in your HTML. You can then:

View page source or inspect element
Copy the JSON output
Paste into a JSON formatter to read it

Limitations

Clutters your HTML output
Easy to forget and leave in production code
Requires refreshing the page for every change
Large objects are hard to navigate
No syntax highlighting or search

Better: Wrap in a script tag

<script>
  console.log('Product:', {{ product | json }});
</script>

Now you can view it in browser DevTools console with proper formatting.

Method 2: Shopify Theme Check

Theme Check is Shopify's official linter for Liquid. It catches common errors before you deploy.

Installation

# Via Shopify CLI
shopify theme check

# Or standalone
gem install theme-check
theme-check

What it catches

Undefined objects and variables
Deprecated tags and filters
Missing template files
Performance issues (too many API calls)
Translation key errors

Limitations

Static analysis only — doesn't catch runtime errors
Can't inspect actual data values
Runs in terminal, not in browser
No live debugging

Method 3: Shopify's Built-in Error Messages

Liquid does surface some errors directly in the HTML output. Look for:

Liquid error: undefined method 'title' for nil:NilClass

Liquid syntax error: Unknown tag 'endfor'

How to find them

View page source (Cmd+U / Ctrl+U)
Search for "Liquid error" or "Liquid syntax"
The error message usually indicates the file and line

Common error patterns

Error	Cause	Fix
`undefined method for nil:NilClass`	Accessing property on null object	Add `{% if object %}` check
`Unknown tag`	Typo in tag name	Check spelling (`endif` not `end if`)
`Could not find snippet`	Missing snippet file	Create the file or fix the path
`Invalid JSON`	Malformed JSON in section schema	Validate your JSON syntax

Method 4: Preview Inspector (Theme Editor)

Shopify's theme customizer has a basic inspector:

Open theme customizer
Click on a section
View available settings and blocks

Limitations

Only shows section settings, not Liquid objects
Can't inspect product, cart, or collection data
No expression evaluation
No error detection

Method 5: Browser DevTools (for JavaScript)

If your Liquid outputs data for JavaScript consumption, you can debug the JavaScript side:

<script>
  window.productData = {{ product | json }};
</script>

Then in browser console:

console.log(productData.title);
console.log(productData.variants[0].price);

Limitations

Only works for data you explicitly expose
Can't access Liquid-only objects like template or request
Requires modifying your code to expose data

Method 6: In-Browser Liquid DevTools

The most comprehensive solution is using dedicated developer tools that run in the browser.

Shopify Theme Devtools is an open-source panel that provides:

Objects Inspector

Browse all Liquid objects in a collapsible tree view:

shop — Store settings, currency, locale
product — Current product with variants, images, metafields
collection — Collection data with products
cart — Live cart state with items and attributes
customer — Logged-in customer data
template — Current template name and directory
request — Page URL, host, path

Click any property to copy its Liquid path.

Live Expression Evaluator

Test Liquid expressions without refreshing:

> product.title
"Classic Cotton T-Shirt"

> product.price | money
"$29.99"

> cart.items | size
3

> product.variants | first | json
{"id": 12345, "title": "Small / Blue", ...}

Supports 50+ Liquid filters including money, money_with_currency, img_url, asset_url, and more.

Automatic Error Detection

Scans the page for common Liquid issues:

Error Type	Example
Liquid errors	`Liquid error: undefined method 'size'`
Syntax errors	`Liquid syntax error: Unknown tag 'endif'`
Drop object leaks	`#<ProductDrop:0x00007f...>`
Missing snippets	`Could not find snippet 'missing-file'`
Schema errors	Invalid JSON in section schema
JSON filter errors	`{"error":"not found"}`

Each error includes a suggested fix.

Cart Debugging

View live cart state with all items and properties
Adjust quantities without leaving the panel
Save and restore cart snapshots
View cart history with timestamps

Installation

npx shopify-theme-devtools init --inject

Then press Cmd+Shift+D (Mac) or Ctrl+Shift+D (Windows) to open.

Only loads on development themes — safe to commit to your repository.

Common Liquid Errors and Solutions

1. "undefined method for nil:NilClass"

Cause: Accessing a property on an object that doesn't exist.

<!-- This breaks if product is nil -->
{{ product.title }}

Fix: Always check if the object exists first.

{% if product %}
  {{ product.title }}
{% endif %}

2. "Unknown tag"

Cause: Typo in a Liquid tag name.

<!-- Wrong -->
{% end if %}

<!-- Correct -->
{% endif %}

3. Drop object leak (#ProductDrop:0x...)

Cause: Outputting a Liquid object without the json filter.

<!-- Wrong — renders as #<ProductDrop:0x...> -->
<script>
  const product = {{ product }};
</script>

<!-- Correct -->
<script>
  const product = {{ product | json }};
</script>

4. "Could not find snippet"

Cause: Rendering a snippet that doesn't exist.

{% render 'non-existent-snippet' %}

Fix: Check the snippet filename and ensure it's in the snippets/ folder.

5. Empty output (no error)

Cause: Variable is nil or empty, but Liquid doesn't error — it just outputs nothing.

Debug: Use the inspect filter or JSON output:

{{ my_variable | json }}
<!-- Shows "null" if nil, actual value otherwise -->

6. "Invalid JSON in schema"

Cause: Section schema has malformed JSON.

{% schema %}
{
  "name": "My Section",
  "settings": [
    {
      "type": "text",
      "id": "title"
      <!-- Missing comma here -->
      "label": "Title"
    }
  ]
}
{% endschema %}

Fix: Validate your JSON at jsonlint.com.

7. Incorrect money formatting

Cause: Using raw price values without the money filter.

<!-- Wrong — outputs "2999" -->
{{ product.price }}

<!-- Correct — outputs "$29.99" -->
{{ product.price | money }}

8. Array index out of bounds

Cause: Accessing an array index that doesn't exist.

<!-- Breaks if product has fewer than 3 images -->
{{ product.images[2].src }}

Fix: Check array size first:

{% if product.images.size > 2 %}
  {{ product.images[2].src }}
{% endif %}

Debugging Workflow: A Step-by-Step Process

When you encounter an issue, follow this process:

Step 1: Check for visible errors

Search your page source for "Liquid error" or "Liquid syntax error".

Step 2: Isolate the problem

Comment out sections of code until the error disappears:

{% comment %}
  {{ potentially_broken_code }}
{% endcomment %}

Step 3: Inspect the data

Use JSON output or a devtools panel to see what data is actually available:

{{ product | json }}

Step 4: Verify object existence

Add existence checks around the problematic code:

{% if product %}
  {% if product.metafields.custom.size > 0 %}
    {{ product.metafields.custom | json }}
  {% else %}
    <!-- No custom metafields -->
  {% endif %}
{% else %}
  <!-- Product is nil -->
{% endif %}

Step 5: Test expressions incrementally

Break complex expressions into smaller parts:

<!-- Instead of this -->
{{ product.metafields.custom.care_instructions.value | newline_to_br }}

<!-- Test each part -->
{{ product.metafields | json }}
{{ product.metafields.custom | json }}
{{ product.metafields.custom.care_instructions | json }}

Performance Debugging

Some Liquid issues aren't errors — they're performance problems.

Too many API calls

Each time you access all_products, collections, or similar global objects, Shopify makes API calls. Too many calls slow down your page.

<!-- Bad — N+1 query problem -->
{% for product_handle in product_handles %}
  {% assign p = all_products[product_handle] %}
  {{ p.title }}
{% endfor %}

<!-- Better — use collection or section settings -->
{% for product in collection.products %}
  {{ product.title }}
{% endfor %}

Heavy JSON output

Outputting large objects as JSON increases page size:

<!-- Bad — includes all product data -->
{{ product | json }}

<!-- Better — only what you need -->
{
  "id": {{ product.id | json }},
  "title": {{ product.title | json }},
  "price": {{ product.price | json }}
}

Identify slow sections

Use browser DevTools Network tab to check page load time. If pages are slow:

Check for excessive for loops
Look for all_products or collections calls
Reduce JSON payload size
Consider lazy loading non-critical content

Debugging Metafields

Metafields are a common source of confusion because they may or may not exist.

Check if a metafield exists

{% if product.metafields.custom.care_instructions %}
  {{ product.metafields.custom.care_instructions.value }}
{% else %}
  No care instructions available.
{% endif %}

List all metafields

<pre>{{ product.metafields | json }}</pre>

Access nested metafield values

For JSON metafields:

{% assign data = product.metafields.custom.specs.value %}
{{ data.weight }}
{{ data.dimensions }}

Summary

Method	Best for	Limitations
`\	json` filter	Quick data inspection
Theme Check	Pre-deploy linting	Static only, no runtime
Browser DevTools	JavaScript debugging	Can't access Liquid objects
Page source search	Finding error messages	No object inspection
Shopify Theme Devtools	Full debugging workflow	Requires installation

For most developers, combining Theme Check (for linting) with an in-browser devtools panel (for runtime debugging) provides the most complete debugging experience.

Additional Resources

Shopify Liquid Reference
Theme Check Documentation
Shopify Theme Devtools
LiquidJS Documentation (for understanding filter behavior)

What debugging techniques do you use for Shopify Liquid? Share your tips in the comments.

Tags: #shopify #liquid #debugging #webdev #ecommerce #tutorial #devtools

Shopify Theme Devtools: Debug Liquid Like It's JavaScript

Yakhyo Ismoildjonov — Sun, 11 Jan 2026 13:01:47 +0000

If you've ever spent hours hunting down a Liquid error buried somewhere in your Shopify theme, or wondered "what the hell is in this product object right now?", this tool is for you.

I built Shopify Theme Devtools — an in-browser developer panel that brings Chrome DevTools-level debugging to Shopify Liquid development. No more {{ product | json }} scattered throughout your templates. No more refreshing the page to check cart state. No more guessing.

The Problem with Shopify Theme Debugging

Shopify's Liquid templating is powerful, but debugging it is painful:

No native debugger — You can't step through Liquid code
Silent failures — Errors often render as empty strings or cryptic messages buried in HTML
Context blindness — You can't easily see what data is available in your current template
Cart state mystery — Testing cart logic requires manually adding/removing items
Metafield hunting — Finding and testing metafield values across resources is tedious

Most developers resort to sprinkling {{ some_object | json }} throughout their code, refreshing, copying the output, and pasting into a JSON formatter. Over and over.

There had to be a better way.

Introducing Shopify Theme Devtools

Shopify Theme Devtools is a single Liquid snippet that injects a full-featured debugging panel into your development theme. It's like having Chrome DevTools, but specifically designed for Shopify Liquid.

Key Features at a Glance

Feature	What It Does
Objects Inspector	Browse all Liquid objects (`shop`, `product`, `cart`, etc.) with search
Live Console	Evaluate Liquid expressions in real-time with autocomplete
Cart Panel	Manipulate cart state, view history, restore snapshots
Error Detection	Automatically finds Liquid errors, Drop leaks, missing assets
Network Monitor	Capture and replay Shopify API requests
Metafields Viewer	Explore metafields across all resources
SEO Inspector	Validate meta tags, Open Graph, JSON-LD

Installation: 60 Seconds to Better Debugging

npx shopify-theme-devtools init --inject

That's it. This command:

Copies the bridge snippet to your snippets/ folder
Automatically adds the render tag to your theme.liquid
Detects and injects your metafields.json schema

Or install manually:

npx shopify-theme-devtools init

Then add this line to layout/theme.liquid just before </body>:

{% render 'theme-devtools-bridge' %}

Security Note

The panel only renders on unpublished/development themes. It checks theme.role != 'main' before loading, so it's completely safe to commit to your repository. Your production store will never see it.

Deep Dive: The Objects Inspector

The Objects Inspector is probably where you'll spend most of your time. It gives you a live, searchable view of every Liquid object available in the current template context.

Browsing Objects

Click through the tree to explore nested properties:

shop
├── name: "My Awesome Store"
├── email: "hello@mystore.com"
├── currency: "USD"
├── metafields
│   └── custom
│       └── announcement_bar: "Free shipping over $50!"
└── ...

One-Click Path Copying

Click any property key to copy its Liquid path to your clipboard:

Click title under product → copies product.title
Click [0] under variants → copies product.variants[0]
Click price under that → copies product.variants[0].price

No more guessing the correct path syntax.

Deep Search

Type in the search box to find properties anywhere in the object tree. Looking for a specific metafield key? Search for it. Need to find where inventory_quantity lives? Search finds it instantly.

Deep Dive: The Liquid Console

This is where Shopify Theme Devtools really shines. The Console panel gives you a live Liquid expression evaluator — think of it as a REPL for Liquid.

Basic Usage

> product.title
"Classic Cotton T-Shirt"

> product.price | money
"$29.99"

> cart.item_count
3

> shop.name | upcase
"MY AWESOME STORE"

Supported Liquid Filters

The evaluator supports 50+ Liquid filters, including Shopify-specific ones:

> product.title | upcase
"CLASSIC COTTON T-SHIRT"

> product.title | downcase | split: ' ' | first
"classic"

> product.price | money_with_currency
"$29.99 USD"

> cart.items | size
3

> product.variants | first | json
{"id": 12345, "title": "Small / Blue", ...}

> product.tags | join: ', '
"cotton, summer, sale"

Array Navigation

Navigate complex data structures with bracket notation:

> product.variants[0].title
"Small / Blue"

> product.images[0].src
"https://cdn.shopify.com/..."

> cart.items[0].properties._gift_wrap
"Yes"

Command History

Use the up/down arrow keys to navigate through previous expressions. Your history persists across page navigations.

Autocomplete

Press Tab to autocomplete object paths as you type. The console knows what properties are available and suggests them.

Deep Dive: Liquid Error Detection

One of the most valuable features is automatic error detection. The Console panel continuously scans your page for common Liquid issues.

Error Types Detected

Error Type	Example	What It Means
Liquid error	`Liquid error: undefined method 'size'`	Runtime error in your Liquid code
Syntax error	`Liquid syntax error: Unknown tag 'endif'`	Invalid Liquid syntax
Drop leaks	`#<ProductDrop:0x00007f...>`	Raw Ruby object rendered (usually from missing `
Missing snippets	{% raw %}`Liquid error: Could not find snippet 'missing-file'`	Referenced snippet doesn't exist
Schema errors	`Liquid error: Invalid JSON in schema`	Malformed JSON in section schema
JSON filter errors	`{"error":"not found"}`	Failed `

Smart Fix Suggestions

Each error comes with context-aware suggestions:
{% raw %}

❌ Liquid error: undefined method 'price' for nil:NilClass
   📍 Found in: sections/product-card.liquid
   💡 Suggestion: Check if 'product' exists before accessing 'price'. 
      Use: {% if product %}{{ product.price }}{% endif %}

Drop Object Detection

This catches a sneaky bug that's easy to miss. If you accidentally render a Liquid object without the | json filter:

<!-- Wrong -->
<script>
  const product = {{ product }};
</script>

<!-- Correct -->
<script>
  const product = {{ product | json }};
</script>

The first version renders as #<ProductDrop:0x00007f...>, breaking your JavaScript. Devtools catches this automatically.

Deep Dive: Cart Panel

Testing cart-dependent features (discounts, upsells, shipping calculators) usually means manually adding items, checking state, removing them, repeat. The Cart Panel changes this.

Live Cart State

See your current cart state in real-time:

Cart (3 items, $89.97)
├── Classic Cotton T-Shirt (Qty: 2) — $59.98
│   └── properties: { _gift_wrap: "Yes" }
├── Leather Belt (Qty: 1) — $29.99
└── attributes: { note: "Please gift wrap" }

Quantity Controls

Adjust quantities directly from the panel. Changes reflect immediately in both the panel and your theme.

Cart History & Snapshots

Every cart mutation is recorded with a timestamp:

12:34:52 — Added "Classic Cotton T-Shirt" (Qty: 1)
12:35:10 — Updated "Classic Cotton T-Shirt" (Qty: 1 → 2)
12:35:45 — Added "Leather Belt" (Qty: 1)

Click any snapshot to restore that exact cart state. Testing "empty cart" vs "3 items" vs "10+ items" becomes instant.

Cart Scenarios

Save named cart configurations for quick testing:

"Empty Cart"
"Single Item"
"Gift Card Only"
"Mixed Products + Subscription"
"Over Free Shipping Threshold"

One click to load any scenario.

Cart Tests

Create validation rules that run automatically when the cart changes:

// Rule: Gift items must have _gwp_source property
{
  type: "property_dependency",
  name: "GWP Validation",
  condition: { property: "_is_gwp", value: "true" },
  required: ["_gwp_source", "_gwp_campaign"]
}

// Rule: Max 5 of any single item
{
  type: "quantity",
  name: "Per-Item Limit",
  max_per_item: 5
}

16 pre-built templates cover common scenarios.

Deep Dive: Network Panel

The Network Panel captures and lets you inspect all Shopify API requests.

Request Logging

Automatically captures:

Cart API (/cart/add.js, /cart/change.js, /cart/update.js)
Product API (/products/*.json)
Collection API (/collections/*.json)
Search API (/search/suggest.json)
Storefront GraphQL

Request Details

For each request, see:

Method, URL, status code
Request headers and body
Response headers and body
Timing information

Edit & Replay

Modify any captured request and resend it:

// Original request
POST /cart/add.js
{ "id": 12345, "quantity": 1 }

// Edit and replay with different quantity
POST /cart/add.js
{ "id": 12345, "quantity": 5 }

Cart State Diff

After cart mutations, see exactly what changed:

  item_count: 3 → 4
+ items[3]: { title: "New Item", quantity: 1 }
  total_price: 8997 → 11996

Export Options

Copy as cURL — For terminal debugging
Copy as Fetch — For browser console testing

Additional Panels

Metafields Viewer

Browse metafields across all resources:

product.metafields
├── custom
│   ├── care_instructions: "Machine wash cold"
│   ├── material: "100% Cotton"
│   └── sustainability_score: 8
└── reviews
    ├── rating: 4.5
    └── count: 127

shop.metafields
└── custom
    └── announcement: "Free shipping over $50!"

SEO Inspector

Validate your SEO implementation:

Meta Tags — title, description, canonical
Open Graph — og:title, og:image, og:description
Twitter Cards — twitter:card, twitter:title
JSON-LD — Product, Organization, BreadcrumbList schemas

Errors are highlighted with fix suggestions.

Localization Panel

For multi-market stores:

Current market, currency, language
Available markets with quick switcher
Country data and shipping zones

Analytics Viewer

Detects installed tracking:

Google Analytics (GA4, Universal)
Facebook Pixel
TikTok Pixel
Pinterest Tag
Custom scripts

Storage Inspector

Browse and edit:

localStorage
sessionStorage
Cookies (with expiration and flags)

Keyboard Shortcuts

Action	Mac	Windows
Toggle Panel	`Cmd+Shift+D`	`Ctrl+Shift+D`
Evaluate Expression	`Enter`	`Enter`
Autocomplete	`Tab`	`Tab`
Command History	`↑` / `↓`	`↑` / `↓`

Tab Customization

Like Chrome DevTools, you can customize your layout:

Right-click any tab to show/hide it
Drag tabs to reorder them
Hidden tabs are completely unloaded (saves memory)
"Reset to Defaults" restores original layout

Configuration Options

Local Development Mode

For development with hot reload:

{%- assign devtools_local = true -%}

Then run:

npm run dev  # Starts at localhost:9999

Self-Hosted Assets

If you prefer not to use the CDN:

npx shopify-theme-devtools init --local

This copies JS/CSS to your assets/ folder.

Metafields Schema

To show all defined metafields (not just ones with values), the CLI automatically detects your .shopify/metafields.json:

npx shopify-theme-devtools sync  # Update metafields schema

How It Works (Technical Details)

For the curious:

Context Extraction — The Liquid bridge renders theme objects as a JSON blob using | json filters
Async Data Loading — Product variants and cart data are fetched via Shopify's JSON APIs for live data
Expression Evaluation — Uses LiquidJS to evaluate expressions client-side
Shadow DOM Isolation — All styles are scoped to prevent theme CSS conflicts
Session Persistence — Logs, cart history, and preferences survive page navigations

Tech Stack

Lit — Lightweight Web Components (fast, no virtual DOM)
LiquidJS — Liquid template engine for expression evaluation
Vite — Fast build tooling

Browser Support

Chrome 90+
Firefox 90+
Safari 14+
Edge 90+

Real-World Use Cases

Debugging a Broken Product Page

> product
null

// Aha! Product object isn't available. Check your template assignment.

Testing Discount Logic

> cart.total_price | money
"$89.97"

> cart.total_discount | money
"$10.00"

> cart.items | map: 'line_level_discount_allocations' | flatten | size
2

Finding Available Metafields

Search "metafield" in Objects Inspector to see all metafields across every resource, with their current values.

Testing Cart Edge Cases

Save current cart as "Baseline" scenario
Clear cart
Add edge case items (subscription + one-time, quantity limits, etc.)
Test your theme
One-click restore to "Baseline"

Get Started

npx shopify-theme-devtools init --inject

Then press Cmd+Shift+D (or Ctrl+Shift+D) to open the panel.

Links:

Wrapping Up

If you're building Shopify themes, you deserve better debugging tools than {{ thing | json }}. Shopify Theme Devtools brings the debugging experience you're used to from other frameworks into the Liquid world.

Give it a try and let me know what you think. What features would you add? Drop a comment below or open an issue on GitHub.

Happy debugging! 🛠️

Tags: #shopify #webdev #javascript #opensource #devtools #ecommerce #liquidtemplating #debugging