shopify-theme-devtools 1.0.0 → 1.1.1

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 +25 -145
  2. package/dist/theme-devtools.js +3889 -690
  3. package/package.json +3 -3
  4. package/src/liquid/theme-devtools-bridge.liquid +87 -17
package/README.md CHANGED
@@ -1,174 +1,54 @@
1
1
  # Shopify Theme Devtools
2
2
 
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-yellow.svg)](https://opensource.org/licenses/MIT)
5
-
6
- In-browser devtools panel for Shopify theme development. Inspect Liquid context, metafields, theme settings, cart state, and sections while working on storefront previews.
7
-
8
- ![Theme Devtools Screenshot](https://via.placeholder.com/800x400?text=Theme+Devtools+Screenshot)
9
-
10
- ## Features
11
-
12
- - đŸ“Ļ **Object Inspector** — Tree-based viewer for Liquid objects (`cart`, `product`, `customer`, `shop`, etc.)
13
- - 🏷ī¸ **Metafields Explorer** — Browse product, collection, shop metafields with type indicators
14
- - 🎨 **Theme Settings** — View all theme settings organized by group with validation
15
- - 📐 **Section Highlighter** — List all sections, click to highlight and scroll into view
16
- - 🛒 **Cart Toolkit** — Live cart state, change tracking, diff visualization, and actions
17
- - 📋 **Copy as Liquid** — Click any property to copy its Liquid access path
18
- - ⌨ī¸ **Keyboard Shortcut** — `Cmd+Shift+D` to toggle panel
3
+ In-browser devtools panel for Shopify theme development. Inspect Liquid context, metafields, theme settings, cart state, and sections.
19
4
 
20
5
  ## Installation
21
6
 
22
- ### Option 1: npm + CDN (Recommended)
23
-
24
7
  ```bash
25
8
  npm install shopify-theme-devtools
26
9
  ```
27
10
 
28
- After building, the JS bundle is available at:
29
- - jsDelivr: `https://cdn.jsdelivr.net/npm/shopify-theme-devtools@latest/dist/theme-devtools.js`
30
- - unpkg: `https://unpkg.com/shopify-theme-devtools@latest/dist/theme-devtools.js`
31
-
32
- ### Option 2: Manual Download
33
-
34
- Download the latest release from [GitHub Releases](https://github.com/yourusername/shopify-theme-devtools/releases) and upload to your CDN.
35
-
36
- ## Setup in Shopify Theme
37
-
38
- ### 1. Add the Liquid Snippet
39
-
40
- Copy the snippet to your theme's `snippets/` folder:
41
-
42
- ```bash
43
- # From npm package
44
- cp node_modules/shopify-theme-devtools/src/liquid/theme-devtools-bridge.liquid snippets/
45
- ```
11
+ ## Setup
46
12
 
47
- Or copy manually from `src/liquid/theme-devtools-bridge.liquid`.
13
+ 1. Copy `src/liquid/theme-devtools-bridge.liquid` to your theme's `snippets/` folder
48
14
 
49
- ### 2. Configure the Snippet
50
-
51
- Edit `snippets/theme-devtools-bridge.liquid`:
52
-
53
- ```liquid
54
- {%- assign devtools_local = false -%} {# Set to true for local development #}
55
- {%- assign devtools_cdn_base = 'https://cdn.jsdelivr.net/npm/shopify-theme-devtools@latest/dist' -%}
56
- ```
57
-
58
- **Optional:** Configure metafield namespaces and theme settings to expose:
59
-
60
- ```liquid
61
- {%- assign devtools_metafield_namespaces = 'custom,global,my_fields' | split: ',' -%}
62
- ```
63
-
64
- ### 3. Render in Theme
65
-
66
- Add to `layout/theme.liquid` before `</body>`:
15
+ 2. Add to `layout/theme.liquid` before `</body>`:
67
16
 
68
17
  ```liquid
69
18
  {% render 'theme-devtools-bridge' %}
70
19
  ```
71
20
 
72
- The devtools **only render on development/preview themes** (`theme.role == 'development'` or `theme.role == 'unpublished'`), so it's safe to leave in production code.
21
+ Only renders on development/preview themes, safe to leave in production.
73
22
 
74
23
  ## Usage
75
24
 
76
- ### Keyboard Shortcut
77
-
78
- `Cmd+Shift+D` (Mac) / `Ctrl+Shift+D` (Windows) — Toggle panel visibility
79
-
80
- ### Tabs
25
+ Toggle panel: `Cmd+Shift+D` (Mac) / `Ctrl+Shift+D` (Windows)
81
26
 
82
- | Tab | Description |
83
- |-----|-------------|
84
- | đŸ“Ļ **Objects** | Inspect Liquid objects (shop, product, collection, customer, etc.) |
85
- | 🏷ī¸ **Metafields** | Browse metafields by resource → namespace → key |
86
- | 🎨 **Settings** | View theme settings and section settings |
87
- | 📐 **Sections** | List and highlight rendered sections |
88
- | 🛒 **Cart** | Live cart state with edit capabilities |
89
- | ℹī¸ **Info** | Theme, template, request, and localization info |
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
90
41
 
91
- ### Copying Liquid Paths
42
+ Click any property to copy its Liquid path.
92
43
 
93
- Click any property key to copy its Liquid path:
94
- - Object property → `{{ product.title }}`
95
- - Metafield → `{{ product.metafields.custom.sizing_chart }}`
96
- - Setting → `{{ settings.colors_accent_1 }}`
97
-
98
- ## Local Development
99
-
100
- ### Prerequisites
101
-
102
- - Node.js 18+
103
- - npm
104
-
105
- ### Setup
44
+ ## Development
106
45
 
107
46
  ```bash
108
- git clone https://github.com/yourusername/shopify-theme-devtools.git
109
- cd shopify-theme-devtools
110
47
  npm install
48
+ npm run dev # Dev server at localhost:9999
49
+ npm run build # Production build
111
50
  ```
112
51
 
113
- ### Commands
114
-
115
- ```bash
116
- # Development server with HMR (http://localhost:9999)
117
- npm run dev
118
-
119
- # Production build
120
- npm run build
121
-
122
- # Preview production build
123
- npm run preview
124
- ```
125
-
126
- ### Local Development Workflow
127
-
128
- 1. Run `npm run dev` to start Vite dev server
129
- 2. Set `devtools_local = true` in your theme's snippet
130
- 3. Run `shopify theme dev` in your theme directory
131
- 4. Changes to JS files hot-reload automatically
132
-
133
- ## Project Structure
134
-
135
- ```
136
- src/
137
- ├── scripts/
138
- │ ├── components/ # Lit web components
139
- │ │ ├── panels/ # Panel components (objects, metafields, settings, etc.)
140
- │ │ ├── object-inspector.js
141
- │ │ └── theme-devtools.js
142
- │ ├── services/ # Context parser, Cart API, Section highlighter
143
- │ └── main.js # Entry point
144
- ├── styles/
145
- │ └── main.css
146
- └── liquid/
147
- └── theme-devtools-bridge.liquid
148
- ```
149
-
150
- ## Technical Details
151
-
152
- - **Lit Web Components** — Modern, reactive UI components
153
- - **Shadow DOM** — Isolates devtools CSS from theme styles
154
- - **Cart Tracking** — Ajax interception + polling fallback
155
- - **Section Detection** — `[id^="shopify-section-"]` + `[data-section-id]`
156
- - **~50KB** — Minified bundle size
157
-
158
- ## Browser Support
159
-
160
- Chrome 80+, Firefox 78+, Safari 14+, Edge 80+
161
-
162
- ## Contributing
163
-
164
- Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details.
165
-
166
52
  ## License
167
53
 
168
- [MIT](LICENSE) Š Your Name
169
-
170
- ## Related
171
-
172
- - [Shopify Theme Development](https://shopify.dev/themes)
173
- - [Liquid Reference](https://shopify.dev/docs/api/liquid)
174
- - [Theme Check](https://github.com/Shopify/theme-check)
54
+ [MIT](LICENSE)