shopify-theme-devtools 2.2.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
@@ -118,29 +132,55 @@ Customize your devtools layout like Chrome DevTools:
 
 ## Quick Start
 
-### 1. Add the snippet to your theme
-
-Copy the Liquid bridge to your theme's snippets folder:
+### Option A: Using npm (Recommended)
 
 ```bash
-# Option A: Download directly
-curl -o snippets/theme-devtools-bridge.liquid \
-  https://raw.githubusercontent.com/yakohere/shopify-theme-devtools/main/src/liquid/theme-devtools-bridge.liquid
+# Run directly with npx (no install needed)
+npx shopify-theme-devtools init
 
-# Option B: Copy manually from GitHub
-# Visit: https://github.com/yakohere/shopify-theme-devtools/blob/main/src/liquid/theme-devtools-bridge.liquid
-# Click "Raw" and save the file to your theme's snippets/ folder
+# 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.
 
@@ -278,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);
+}

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "shopify-theme-devtools",
-  "version": "2.2.0",
+  "version": "2.2.1",
   "description": "In-browser devtools panel for Shopify theme development - inspect Liquid context, metafields, settings, sections, and cart state",
   "type": "module",
   "main": "dist/theme-devtools.js",
   "module": "dist/theme-devtools.js",
+  "bin": {
+    "shopify-theme-devtools": "./bin/cli.js"
+  },
   "exports": {
     ".": {
       "import": "./dist/theme-devtools.js",
@@ -14,6 +17,7 @@
     "./dist/*": "./dist/*"
   },
   "files": [
+    "bin",
     "dist",
     "src/liquid",
     "README.md",