shopify-theme-devtools 2.1.0 → 2.2.1

package/README.md

@@ -6,6 +6,20 @@
 
 A powerful in-browser developer tools panel for Shopify theme development. Inspect Liquid objects, evaluate expressions, explore metafields, manipulate cart state, detect Liquid errors, and much more — all without leaving the browser.
 
+## Table of Contents
+
+- [Features](#features)
+- [Quick Start](#quick-start)
+- [Keyboard Shortcuts](#keyboard-shortcuts)
+- [Panel Reference](#panel-reference)
+- [Configuration](#configuration)
+- [Development](#development)
+- [How It Works](#how-it-works)
+- [Tech Stack](#tech-stack)
+- [Browser Support](#browser-support)
+- [Contributing](#contributing)
+- [License](#license)
+
 ## Features
 
 ### Core Panels
@@ -13,7 +27,7 @@ A powerful in-browser developer tools panel for Shopify theme development. Inspe
 - **Objects Inspector** — Browse `shop`, `product`, `collection`, `customer`, `cart` and more with deep search and collapsible tree view
 - **Metafields Viewer** — Explore metafields across all resources and namespaces with type labels
 - **Cart Panel** — Real-time cart state with add/remove/quantity controls, cart history with restore, and attribute editing
-- **Console** — Chrome DevTools-style console with Liquid expression evaluator, autocomplete, and log filtering
+- **Console** — Chrome DevTools-style console with Liquid expression evaluator, and autocomplete
 - **Localization** — Markets, currencies, languages, and country data with quick switcher
 - **SEO Inspector** — Meta tags, Open Graph, Twitter Cards, and structured data (JSON-LD) validation
 - **Analytics Viewer** — Detects Google Analytics, Facebook Pixel, and other tracking codes
@@ -29,10 +43,21 @@ Browse and search through all Liquid objects with a collapsible tree view. Click
 
 ### Console Panel
 
-Evaluate Liquid expressions in real-time with autocomplete, filter support, and command history.
+A powerful Liquid debugger combining error detection and expression evaluation.
 
 ![Console Panel](screenshots/console-panel.gif)
 
+**Liquid Error Detection:**
+- **Liquid Errors** — Detects `Liquid error:` and `Liquid syntax error:` messages in page content
+- **Drop Object Leaks** — Finds raw Drop objects rendered on page (`ProductDrop`, `#<ProductDrop:0x...>`)
+- **Asset Errors** — Missing snippets, images, and asset files
+- **Schema Errors** — Invalid JSON in section schemas
+- **JSON Filter Errors** — Detects `{"error":"..."}` output from failed `| json` filters
+- **Form Errors** — Missing product/customer objects for forms
+- **Smart Hints** — Context-aware fix suggestions for each error type
+
+**Expression Evaluator:**
+
 ### Cart Snapshots
 
 Track cart state changes over time and restore any previous snapshot with a single click.
@@ -82,38 +107,80 @@ Automatically scans the page for common Liquid issues:
 - Schema validation errors
 - Deprecation warnings
 
-### Network Monitor
+### Network Panel
 
-Captures failed HTTP requests with:
-- Status codes and response times
-- Request URLs with query parameters
-- Error categorization (4xx, 5xx, CORS, timeout)
+Captures and inspects Shopify API requests with powerful debugging tools:
 
-## Quick Start
+- **Request Logging** — Auto-captures cart, product, collection, search, and GraphQL requests
+- **Request Editor** — Edit and resend requests with modified method, URL, headers, and body
+- **Replay** — Re-execute any captured request with one click
+- **Cart State Diff** — See exactly what changed in the cart after mutations (items added/removed/changed)
+- **Copy as cURL/Fetch** — Export requests for debugging or sharing
+- **Persistence** — Last 32 requests are saved to localStorage and restored on reload
+- **GraphQL Prettifier** — Syntax-highlighted, formatted GraphQL queries
+- **Error Diagnosis** — Smart suggestions for common cart and API errors (out of stock, invalid variants, quantity limits)
 
-### 1. Add the snippet to your theme
+### Tab Customization
 
-Copy the Liquid bridge to your theme's snippets folder:
+Customize your devtools layout like Chrome DevTools:
+
+- **Right-click any tab** to show/hide it
+- **Drag tabs** to reorder them
+- **Preferences tab** cannot be hidden (ensures you can always restore tabs)
+- **"Reset to Defaults"** restores original tab order and visibility
+- Hidden tabs are completely unloaded from DOM (saves memory/CPU)
+
+## Quick Start
+
+### Option A: Using npm (Recommended)
 
 ```bash
-# Option A: Download directly
-curl -o snippets/theme-devtools-bridge.liquid \
-  https://raw.githubusercontent.com/user/shopify-theme-devtools/main/src/liquid/theme-devtools-bridge.liquid
+# Run directly with npx (no install needed)
+npx shopify-theme-devtools init
 
-# Option B: Install via npm
-npm install shopify-theme-devtools
-cp node_modules/shopify-theme-devtools/src/liquid/theme-devtools-bridge.liquid snippets/
+# Or install globally for repeated use
+npm install -g shopify-theme-devtools
+shopify-theme-devtools init
 ```
 
-### 2. Include in your layout
-
-Add this line to `layout/theme.liquid` just before `</body>`:
+This copies the Liquid snippet to your `snippets/` folder. Then add this line to `layout/theme.liquid` just before `</body>`:
 
 ```liquid
 {% render 'theme-devtools-bridge' %}
 ```
 
-### 3. You're done!
+Or use `--inject` to add it automatically:
+
+```bash
+npx shopify-theme-devtools init --inject
+```
+
+#### CLI Options
+
+| Option | Description |
+|--------|-------------|
+| `--local` | Copy JS/CSS to `assets/` folder instead of using CDN |
+| `--inject` | Automatically add render tag to `layout/theme.liquid` |
+| `--force` | Overwrite existing files without prompting |
+
+```bash
+# Examples
+npx shopify-theme-devtools init                    # Uses CDN (recommended)
+npx shopify-theme-devtools init --local            # Self-hosted assets
+npx shopify-theme-devtools init --local --inject   # Self-hosted + auto-inject
+```
+
+### Option B: Manual Download
+
+```bash
+# Download directly
+curl -o snippets/theme-devtools-bridge.liquid \
+  https://raw.githubusercontent.com/yakohere/shopify-theme-devtools/main/src/liquid/theme-devtools-bridge.liquid
+```
+
+Then add `{% render 'theme-devtools-bridge' %}` to `layout/theme.liquid` before `</body>`.
+
+### You're done!
 
 The devtools panel automatically appears on **unpublished/development themes only**. It's safe to commit — it won't render on your live published theme.
 
@@ -126,6 +193,8 @@ The devtools panel automatically appears on **unpublished/development themes onl
 | Evaluate Expression | `Enter` in Console input |
 | Autocomplete | `Tab` in Console input |
 | Command History | `↑` / `↓` in Console input |
+| Show/Hide Tabs | Right-click any tab |
+| Reorder Tabs | Drag and drop tabs |
 
 ## Panel Reference
 
@@ -138,6 +207,7 @@ The devtools panel automatically appears on **unpublished/development themes onl
 | **Analytics** | Detected tracking codes and analytics configuration |
 | **SEO** | Meta tags, Open Graph, Twitter Cards, JSON-LD structured data |
 | **Apps** | Installed Shopify apps detected on the page |
+| **Network** | API request monitor with edit/replay, cart diffs, and error diagnosis |
 | **Console** | Logs, errors, and Liquid expression evaluator |
 | **Cookies** | Browser cookies with expiration and flags |
 | **Storage** | localStorage and sessionStorage key-value pairs |
@@ -212,7 +282,7 @@ src/
 │   └── theme-devtools-bridge.liquid  # Liquid snippet for themes
 ├── scripts/
 │   ├── components/
-│   │   ├── theme-devtools.js         # Main component
+│   │   ├── theme-devtools.js         # Main component with tab management
 │   │   ├── object-inspector.js       # Tree view inspector
 │   │   └── panels/                   # Panel components
 │   ├── services/
@@ -220,6 +290,7 @@ src/
 │   │   ├── product.js                # Product API (variants/images)
 │   │   ├── context.js                # Liquid context parser
 │   │   ├── expression-evaluator.js   # Liquid expression engine
+│   │   ├── network-interceptor.js    # Fetch/XHR interceptor with persistence
 │   │   └── settings.js               # User preferences
 │   └── styles/
 │       └── theme.js                  # CSS variables and themes
@@ -247,7 +318,6 @@ src/
 - [Lit](https://lit.dev/) — Lightweight Web Components
 - [LiquidJS](https://liquidjs.com/) — Liquid template engine
 - [Vite](https://vitejs.dev/) — Fast build tooling
-- Single IIFE bundle (~55KB gzipped)
 
 ## Browser Support
 

package/bin/cli.js

@@ -0,0 +1,273 @@
+#!/usr/bin/env node
+
+import { existsSync, mkdirSync, copyFileSync, readFileSync, writeFileSync } from 'fs';
+import { dirname, join, resolve } from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const packageRoot = resolve(__dirname, '..');
+
+const COLORS = {
+  reset: '\x1b[0m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  red: '\x1b[31m',
+  dim: '\x1b[2m',
+  bold: '\x1b[1m'
+};
+
+function log(message, color = '') {
+  console.log(`${color}${message}${COLORS.reset}`);
+}
+
+function success(message) {
+  log(`✓ ${message}`, COLORS.green);
+}
+
+function warn(message) {
+  log(`⚠ ${message}`, COLORS.yellow);
+}
+
+function error(message) {
+  log(`✗ ${message}`, COLORS.red);
+}
+
+function info(message) {
+  log(`  ${message}`, COLORS.dim);
+}
+
+function printHelp() {
+  console.log(`
+${COLORS.bold}Shopify Theme Devtools CLI${COLORS.reset}
+
+${COLORS.bold}Usage:${COLORS.reset}
+  npx shopify-theme-devtools <command> [options]
+
+${COLORS.bold}Commands:${COLORS.reset}
+  init          Initialize devtools in your Shopify theme
+
+${COLORS.bold}Options for init:${COLORS.reset}
+  --local       Copy JS/CSS to assets folder instead of using CDN
+  --inject      Add render tag to layout/theme.liquid automatically
+  --force       Overwrite existing files without prompting
+  --help, -h    Show this help message
+
+${COLORS.bold}Examples:${COLORS.reset}
+  npx shopify-theme-devtools init
+  npx shopify-theme-devtools init --local
+  npx shopify-theme-devtools init --local --inject
+`);
+}
+
+function ensureDir(dir) {
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+}
+
+function copyFile(src, dest, force = false) {
+  if (existsSync(dest) && !force) {
+    warn(`File already exists: ${dest}`);
+    info('Use --force to overwrite');
+    return false;
+  }
+  copyFileSync(src, dest);
+  return true;
+}
+
+function patchLiquidForLocal(content) {
+  // Change CDN to asset_url
+  let patched = content.replace(
+    /{%- assign devtools_cdn_base = '[^']+' -%}/,
+    "{%- assign devtools_cdn_base = '' -%}"
+  );
+
+  // Replace the script loading section for local assets
+  patched = patched.replace(
+    /<script>\s*window\.__THEME_DEVTOOLS_CSS_URL__[^<]+<\/script>\s*<script src="{{ devtools_cdn_base }}\/theme-devtools\.js" defer><\/script>/s,
+    `<script>
+      window.__THEME_DEVTOOLS_CSS_URL__ = '{{ 'theme-devtools.css' | asset_url }}';
+    </script>
+    <script src="{{ 'theme-devtools.js' | asset_url }}" defer></script>`
+  );
+
+  return patched;
+}
+
+function injectRenderTag(themeLiquidPath) {
+  if (!existsSync(themeLiquidPath)) {
+    warn(`layout/theme.liquid not found at: ${themeLiquidPath}`);
+    return false;
+  }
+
+  let content = readFileSync(themeLiquidPath, 'utf-8');
+  const renderTag = "{% render 'theme-devtools-bridge' %}";
+
+  if (content.includes('theme-devtools-bridge')) {
+    info('Render tag already exists in theme.liquid');
+    return true;
+  }
+
+  // Insert before </body>
+  const bodyCloseRegex = /<\/body>/i;
+  if (!bodyCloseRegex.test(content)) {
+    warn('Could not find </body> tag in theme.liquid');
+    return false;
+  }
+
+  content = content.replace(bodyCloseRegex, `  ${renderTag}\n  </body>`);
+  writeFileSync(themeLiquidPath, content);
+  return true;
+}
+
+function detectThemeRoot(cwd) {
+  // Check if we're in a Shopify theme directory
+  const markers = ['layout', 'snippets', 'templates', 'config'];
+  const hasMarkers = markers.filter(dir => existsSync(join(cwd, dir)));
+
+  if (hasMarkers.length >= 2) {
+    return cwd;
+  }
+
+  // Check if there's a theme subdirectory
+  const possibleThemeDirs = ['theme', 'shopify', 'src'];
+  for (const dir of possibleThemeDirs) {
+    const themePath = join(cwd, dir);
+    if (existsSync(themePath)) {
+      const subMarkers = markers.filter(m => existsSync(join(themePath, m)));
+      if (subMarkers.length >= 2) {
+        return themePath;
+      }
+    }
+  }
+
+  return null;
+}
+
+async function init(args) {
+  const cwd = process.cwd();
+  const useLocal = args.includes('--local');
+  const shouldInject = args.includes('--inject');
+  const force = args.includes('--force');
+
+  console.log();
+  log('Shopify Theme Devtools', COLORS.bold);
+  console.log();
+
+  // Detect theme root
+  const themeRoot = detectThemeRoot(cwd);
+
+  if (!themeRoot) {
+    error('Could not detect Shopify theme directory');
+    info('Make sure you run this command from your theme root');
+    info('(should contain layout/, snippets/, templates/ folders)');
+    process.exit(1);
+  }
+
+  if (themeRoot !== cwd) {
+    info(`Detected theme root: ${themeRoot}`);
+  }
+
+  const snippetsDir = join(themeRoot, 'snippets');
+  const assetsDir = join(themeRoot, 'assets');
+  const layoutDir = join(themeRoot, 'layout');
+
+  // Ensure directories exist
+  ensureDir(snippetsDir);
+  if (useLocal) {
+    ensureDir(assetsDir);
+  }
+
+  // Source files
+  const liquidSrc = join(packageRoot, 'src', 'liquid', 'theme-devtools-bridge.liquid');
+  const jsSrc = join(packageRoot, 'dist', 'theme-devtools.js');
+  const cssSrc = join(packageRoot, 'dist', 'theme-devtools.css');
+
+  // Destination files
+  const liquidDest = join(snippetsDir, 'theme-devtools-bridge.liquid');
+  const jsDest = join(assetsDir, 'theme-devtools.js');
+  const cssDest = join(assetsDir, 'theme-devtools.css');
+
+  let liquidContent = readFileSync(liquidSrc, 'utf-8');
+
+  // Set devtools_local to false for production use
+  liquidContent = liquidContent.replace(
+    /{%- assign devtools_local = true -%}/,
+    '{%- assign devtools_local = false -%}'
+  );
+
+  if (useLocal) {
+    liquidContent = patchLiquidForLocal(liquidContent);
+  }
+
+  // Copy liquid snippet
+  if (existsSync(liquidDest) && !force) {
+    warn(`Snippet already exists: snippets/theme-devtools-bridge.liquid`);
+    info('Use --force to overwrite');
+  } else {
+    writeFileSync(liquidDest, liquidContent);
+    success('Created snippets/theme-devtools-bridge.liquid');
+  }
+
+  // Copy assets if --local
+  if (useLocal) {
+    if (!existsSync(jsSrc)) {
+      error('dist/theme-devtools.js not found. Run npm run build first.');
+      process.exit(1);
+    }
+
+    if (copyFile(jsSrc, jsDest, force)) {
+      success('Copied assets/theme-devtools.js');
+    }
+
+    if (existsSync(cssSrc)) {
+      if (copyFile(cssSrc, cssDest, force)) {
+        success('Copied assets/theme-devtools.css');
+      }
+    }
+  }
+
+  // Inject render tag if --inject
+  if (shouldInject) {
+    const themeLiquid = join(layoutDir, 'theme.liquid');
+    if (injectRenderTag(themeLiquid)) {
+      success('Added render tag to layout/theme.liquid');
+    }
+  }
+
+  console.log();
+  log('Setup complete!', COLORS.green + COLORS.bold);
+  console.log();
+
+  if (!shouldInject) {
+    log('Next step:', COLORS.bold);
+    info("Add this line to layout/theme.liquid before </body>:");
+    console.log();
+    log("  {% render 'theme-devtools-bridge' %}", COLORS.blue);
+    console.log();
+    info('Or run with --inject to do this automatically');
+  }
+
+  console.log();
+  info('The devtools panel will only appear on unpublished/development themes.');
+  console.log();
+}
+
+// Parse arguments
+const args = process.argv.slice(2);
+const command = args[0];
+
+if (!command || command === '--help' || command === '-h') {
+  printHelp();
+  process.exit(0);
+}
+
+if (command === 'init') {
+  init(args);
+} else {
+  error(`Unknown command: ${command}`);
+  printHelp();
+  process.exit(1);
+}