shopify-theme-devtools 1.1.3 → 2.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +238 -27
  2. package/dist/theme-devtools.js +6233 -3328
  3. package/package.json +2 -1
  4. package/src/liquid/theme-devtools-bridge.liquid +4 -4
package/README.md CHANGED
@@ -1,54 +1,265 @@
1
1
  # Shopify Theme Devtools
2
2
 
3
- In-browser devtools panel for Shopify theme development. Inspect Liquid context, metafields, theme settings, cart state, and sections.
3
+ [![npm version](https://img.shields.io/npm/v/shopify-theme-devtools.svg)](https://www.npmjs.com/package/shopify-theme-devtools)
4
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
5
+ [![jsDelivr hits](https://img.shields.io/jsdelivr/npm/hm/shopify-theme-devtools)](https://www.jsdelivr.com/package/npm/shopify-theme-devtools)
4
6
 
5
- ## Installation
7
+ 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.
8
+
9
+ ## Features
10
+
11
+ ### Core Panels
12
+
13
+ - **Objects Inspector** — Browse `shop`, `product`, `collection`, `customer`, `cart` and more with deep search and collapsible tree view
14
+ - **Metafields Viewer** — Explore metafields across all resources and namespaces with type labels
15
+ - **Cart Panel** — Real-time cart state with add/remove/quantity controls, cart history with restore, and attribute editing
16
+ - **Console** — Chrome DevTools-style console with Liquid expression evaluator, autocomplete, and log filtering
17
+ - **Localization** — Markets, currencies, languages, and country data with quick switcher
18
+ - **SEO Inspector** — Meta tags, Open Graph, Twitter Cards, and structured data (JSON-LD) validation
19
+ - **Analytics Viewer** — Detects Google Analytics, Facebook Pixel, and other tracking codes
20
+ - **Storage Inspector** — Browse and edit localStorage, sessionStorage, and cookies
21
+ - **Apps Panel** — Lists installed Shopify apps detected on the page
22
+ - **Info Panel** — Theme details, template info, and request metadata
23
+
24
+ ### Objects Inspector
25
+
26
+ Browse and search through all Liquid objects with a collapsible tree view. Click any key to copy its Liquid path.
27
+
28
+ ![Objects Inspector](screenshots/object-inspector.gif)
29
+
30
+ ### Console Panel
31
+
32
+ Evaluate Liquid expressions in real-time with autocomplete, filter support, and command history.
33
+
34
+ ![Console Panel](screenshots/console-panel.gif)
35
+
36
+ ### Cart Snapshots
37
+
38
+ Track cart state changes over time and restore any previous snapshot with a single click.
39
+
40
+ ![Cart Snapshots](screenshots/cart-snapshots.gif)
41
+
42
+ ### Console Expression Evaluator
43
+
44
+ The Console panel includes an interactive expression evaluator for testing Liquid paths:
45
+
46
+ ```
47
+ > product.title
48
+ "Classic Cotton T-Shirt"
49
+
50
+ > product.variants[0].price | money
51
+ "$29.99"
52
+
53
+ > cart.items | size
54
+ 3
55
+
56
+ > shop.name | upcase
57
+ "MY AWESOME STORE"
58
+ ```
59
+
60
+ **Features:**
61
+ - **Autocomplete** — Suggests paths as you type with Tab completion
62
+ - **Liquid Filters** — Supports `upcase`, `downcase`, `money`, `size`, `first`, `last`, and 50+ filters
63
+ - **Array Access** — Navigate arrays with bracket notation: `product.variants[0].title`
64
+ - **Live Data** — Uses current cart and product data, not stale page load values
65
+ - **Command History** — Use arrow keys to navigate previous expressions
66
+
67
+ ### Cart Panel
68
+
69
+ - **Live Updates** — Cart state updates in real-time as items are added/removed
70
+ - **Quantity Controls** — Adjust item quantities directly
71
+ - **Cart History** — View previous cart states with timestamps and restore any snapshot
72
+ - **Attribute Editor** — Modify cart attributes and notes
73
+ - **Diff View** — See what changed between cart states
74
+
75
+ ### Liquid Error Detection
76
+
77
+ Automatically scans the page for common Liquid issues:
78
+
79
+ - `Liquid error:` and `Liquid syntax error:` messages
80
+ - Drop object leaks (`#<ProductDrop:0x...>`)
81
+ - Missing snippets and assets
82
+ - Schema validation errors
83
+ - Deprecation warnings
84
+
85
+ ### Network Monitor
86
+
87
+ Captures failed HTTP requests with:
88
+ - Status codes and response times
89
+ - Request URLs with query parameters
90
+ - Error categorization (4xx, 5xx, CORS, timeout)
91
+
92
+ ## Quick Start
93
+
94
+ ### 1. Add the snippet to your theme
95
+
96
+ Copy the Liquid bridge to your theme's snippets folder:
6
97
 
7
98
  ```bash
99
+ # Option A: Download directly
100
+ curl -o snippets/theme-devtools-bridge.liquid \
101
+ https://raw.githubusercontent.com/user/shopify-theme-devtools/main/src/liquid/theme-devtools-bridge.liquid
102
+
103
+ # Option B: Install via npm
8
104
  npm install shopify-theme-devtools
105
+ cp node_modules/shopify-theme-devtools/src/liquid/theme-devtools-bridge.liquid snippets/
9
106
  ```
10
107
 
11
- ## Setup
108
+ ### 2. Include in your layout
12
109
 
13
- 1. Copy `src/liquid/theme-devtools-bridge.liquid` to your theme's `snippets/` folder
14
-
15
- 2. Add to `layout/theme.liquid` before `</body>`:
110
+ Add this line to `layout/theme.liquid` just before `</body>`:
16
111
 
17
112
  ```liquid
18
113
  {% render 'theme-devtools-bridge' %}
19
114
  ```
20
115
 
21
- Only renders on development/preview themes, safe to leave in production.
116
+ ### 3. You're done!
117
+
118
+ The devtools panel automatically appears on **unpublished/development themes only**. It's safe to commit — it won't render on your live published theme.
119
+
120
+ ## Keyboard Shortcuts
121
+
122
+ | Action | Shortcut |
123
+ |--------|----------|
124
+ | Toggle Panel | `Cmd+Shift+D` (Mac) / `Ctrl+Shift+D` (Windows) |
125
+ | Copy Liquid Path | Click any property key in Objects panel |
126
+ | Evaluate Expression | `Enter` in Console input |
127
+ | Autocomplete | `Tab` in Console input |
128
+ | Command History | `↑` / `↓` in Console input |
129
+
130
+ ## Panel Reference
131
+
132
+ | Panel | Description |
133
+ |-------|-------------|
134
+ | **Objects** | Inspect all Liquid objects with search and tree navigation |
135
+ | **Metafields** | Browse metafields by resource (product, collection, shop, etc.) |
136
+ | **Cart** | Live cart state, history snapshots, and manipulation tools |
137
+ | **Locale** | Markets, currencies, languages with locale switching |
138
+ | **Analytics** | Detected tracking codes and analytics configuration |
139
+ | **SEO** | Meta tags, Open Graph, Twitter Cards, JSON-LD structured data |
140
+ | **Apps** | Installed Shopify apps detected on the page |
141
+ | **Console** | Logs, errors, and Liquid expression evaluator |
142
+ | **Cookies** | Browser cookies with expiration and flags |
143
+ | **Storage** | localStorage and sessionStorage key-value pairs |
144
+ | **Info** | Theme info, template details, request metadata |
145
+ | **Preferences** | Panel position, theme (dark/light), font scale, shortcuts |
146
+
147
+ ## Configuration
148
+
149
+ ### Local Development
150
+
151
+ For local development with hot reload:
152
+
153
+ 1. Edit the bridge snippet to enable local mode:
154
+
155
+ ```liquid
156
+ {%- assign devtools_local = true -%}
157
+ ```
158
+
159
+ 2. Run the dev server:
22
160
 
23
- ## Usage
161
+ ```bash
162
+ npm run dev # Starts at localhost:9999
163
+ ```
24
164
 
25
- Toggle panel: `Cmd+Shift+D` (Mac) / `Ctrl+Shift+D` (Windows)
165
+ ### Metafields Schema
26
166
 
27
- **Panels:**
28
- - **Objects** — Inspect Liquid objects (shop, product, collection, customer, etc.)
29
- - **Metafields** — Browse metafields by resource
30
- - **Settings** — View theme and section settings
31
- - **Sections** — List and highlight rendered sections
32
- - **Cart** — Live cart state with actions
33
- - **Info** — Theme, template, and request info
34
- - **Analytics** — View analytics and tracking data
35
- - **Apps** — Installed apps information
36
- - **Cookies** — Browser cookies inspector
37
- - **Storage** — LocalStorage and SessionStorage viewer
38
- - **Localization** — Markets, currencies, and languages
39
- - **SEO** — Meta tags and SEO information
40
- - **Console** — Liquid debug console
167
+ To show all defined metafields (not just ones with values), paste your theme's `metafields.json` content into the bridge snippet:
41
168
 
42
- Click any property to copy its Liquid path.
169
+ ```liquid
170
+ {%- capture devtools_metafields_schema -%}
171
+ {
172
+ "product": [
173
+ { "namespace": "custom", "key": "care_instructions", "type": "single_line_text_field" }
174
+ ]
175
+ }
176
+ {%- endcapture -%}
177
+ ```
178
+
179
+ ### Theme Settings
180
+
181
+ Configure which theme settings to expose by editing the `devtools_settings_config` in the bridge snippet:
182
+
183
+ ```liquid
184
+ {%- capture devtools_settings_config -%}
185
+ colors_accent_1|color|Accent 1|colors
186
+ type_header_font|font_picker|Header font|typography
187
+ page_width|range|Page width|layout
188
+ {%- endcapture -%}
189
+ ```
43
190
 
44
191
  ## Development
45
192
 
46
193
  ```bash
194
+ # Install dependencies
47
195
  npm install
48
- npm run dev # Dev server at localhost:9999
49
- npm run build # Production build
196
+
197
+ # Start dev server with hot reload (localhost:9999)
198
+ npm run dev
199
+
200
+ # Build for production
201
+ npm run build
202
+
203
+ # Preview production build
204
+ npm run preview
50
205
  ```
51
206
 
207
+ ### Project Structure
208
+
209
+ ```
210
+ src/
211
+ ├── liquid/
212
+ │ └── theme-devtools-bridge.liquid # Liquid snippet for themes
213
+ ├── scripts/
214
+ │ ├── components/
215
+ │ │ ├── theme-devtools.js # Main component
216
+ │ │ ├── object-inspector.js # Tree view inspector
217
+ │ │ └── panels/ # Panel components
218
+ │ ├── services/
219
+ │ │ ├── cart.js # Cart API with history
220
+ │ │ ├── product.js # Product API (variants/images)
221
+ │ │ ├── context.js # Liquid context parser
222
+ │ │ ├── expression-evaluator.js # Liquid expression engine
223
+ │ │ └── settings.js # User preferences
224
+ │ └── styles/
225
+ │ └── theme.js # CSS variables and themes
226
+ └── styles/
227
+ └── main.css
228
+ ```
229
+
230
+ ## How It Works
231
+
232
+ 1. **Context Extraction** — The Liquid bridge renders theme objects, metafields, and settings as a JSON blob
233
+ 2. **Async Data Loading** — Product variants/images and cart data are fetched via Shopify's JSON APIs for live data
234
+ 3. **Expression Evaluation** — Uses [LiquidJS](https://liquidjs.com/) to evaluate Liquid expressions with Shopify-specific filters
235
+ 4. **Shadow DOM Isolation** — All styles are scoped to prevent conflicts with theme CSS
236
+ 5. **Session Persistence** — Logs, cart history, and preferences persist across page navigations
237
+
238
+ ### Security
239
+
240
+ - Only renders on unpublished themes (`theme.role != 'main'`)
241
+ - Customer emails are partially masked
242
+ - No data is sent to external servers
243
+ - All processing happens client-side
244
+
245
+ ## Tech Stack
246
+
247
+ - [Lit](https://lit.dev/) — Lightweight Web Components
248
+ - [LiquidJS](https://liquidjs.com/) — Liquid template engine
249
+ - [Vite](https://vitejs.dev/) — Fast build tooling
250
+ - Single IIFE bundle (~55KB gzipped)
251
+
252
+ ## Browser Support
253
+
254
+ - Chrome 90+
255
+ - Firefox 90+
256
+ - Safari 14+
257
+ - Edge 90+
258
+
259
+ ## Contributing
260
+
261
+ Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details.
262
+
52
263
  ## License
53
264
 
54
- [MIT](LICENSE)
265
+ [MIT](LICENSE) — Built by [@yakohere](https://github.com/yakohere)