@andsam/shopify-grab 0.1.0 → 0.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.
- package/README.md +78 -3
- package/dist/chunk-HF4K7MRY.cjs +45 -0
- package/dist/chunk-MB3RPJTR.js +45 -0
- package/dist/core/index.cjs +1 -1
- package/dist/core/index.d.cts +1 -1
- package/dist/core/index.d.ts +1 -1
- package/dist/core/index.js +1 -1
- package/dist/{index-uQ7Gd3eQ.d.cts → index-B8oMvRpa.d.cts} +121 -1
- package/dist/{index-uQ7Gd3eQ.d.ts → index-B8oMvRpa.d.ts} +121 -1
- package/dist/index.cjs +2 -2
- package/dist/index.d.cts +2 -2
- package/dist/index.d.ts +2 -2
- package/dist/index.global.js +26 -23
- package/dist/index.js +2 -2
- package/dist/styles.css +1 -1
- package/package.json +17 -9
- package/dist/chunk-EWJGBTPU.cjs +0 -42
- package/dist/chunk-RV3NLUST.js +0 -42
package/README.md
CHANGED
|
@@ -27,7 +27,7 @@ Add this to your `theme.liquid` layout file inside `<head>`:
|
|
|
27
27
|
|
|
28
28
|
```liquid
|
|
29
29
|
{% if request.design_mode or settings.enable_dev_tools %}
|
|
30
|
-
<script src="https://unpkg.com/shopify-grab/dist/index.global.js" crossorigin="anonymous"></script>
|
|
30
|
+
<script src="https://unpkg.com/@andsam/shopify-grab/dist/index.global.js" crossorigin="anonymous"></script>
|
|
31
31
|
{% endif %}
|
|
32
32
|
```
|
|
33
33
|
|
|
@@ -37,7 +37,7 @@ Create a snippet `snippets/shopify-grab.liquid`:
|
|
|
37
37
|
|
|
38
38
|
```liquid
|
|
39
39
|
{% if request.design_mode %}
|
|
40
|
-
<script src="https://unpkg.com/shopify-grab/dist/index.global.js" crossorigin="anonymous"></script>
|
|
40
|
+
<script src="https://unpkg.com/@andsam/shopify-grab/dist/index.global.js" crossorigin="anonymous"></script>
|
|
41
41
|
{% endif %}
|
|
42
42
|
```
|
|
43
43
|
|
|
@@ -48,7 +48,7 @@ Then render it in your layout: `{% render 'shopify-grab' %}`
|
|
|
48
48
|
If you're building a Shopify app, include the script in your theme app extension's block:
|
|
49
49
|
|
|
50
50
|
```liquid
|
|
51
|
-
<script src="https://unpkg.com/shopify-grab/dist/index.global.js" crossorigin="anonymous"></script>
|
|
51
|
+
<script src="https://unpkg.com/@andsam/shopify-grab/dist/index.global.js" crossorigin="anonymous"></script>
|
|
52
52
|
```
|
|
53
53
|
|
|
54
54
|
## Usage
|
|
@@ -78,9 +78,79 @@ Shopify Grab detects theme structure from:
|
|
|
78
78
|
|
|
79
79
|
These attributes are automatically present in the Shopify Theme Editor and on storefront preview pages.
|
|
80
80
|
|
|
81
|
+
## Liquid Profiler (Advanced)
|
|
82
|
+
|
|
83
|
+
Shopify Grab includes a built-in Liquid profiler that taps into the same profiling API used by Shopify's Theme Inspector Chrome extension. When enabled, it provides **file paths, line numbers, and render times** for every Liquid template, giving you bippy-level source introspection for Shopify themes.
|
|
84
|
+
|
|
85
|
+
### How it works
|
|
86
|
+
|
|
87
|
+
1. Authenticates with Shopify Identity (same OAuth flow as Theme Inspector)
|
|
88
|
+
2. Fetches Speedscope-format profiling data from Shopify's servers
|
|
89
|
+
3. Parses the profiling frames to build a source map
|
|
90
|
+
4. Maps DOM elements to their Liquid source files via section/block correlation
|
|
91
|
+
|
|
92
|
+
### Quick start
|
|
93
|
+
|
|
94
|
+
```javascript
|
|
95
|
+
const sg = window.__SHOPIFY_GRAB__;
|
|
96
|
+
|
|
97
|
+
// Sign in with your Shopify partner/staff account (opens popup)
|
|
98
|
+
await sg.profilerSignIn();
|
|
99
|
+
|
|
100
|
+
// Fetch profiling data for the current page
|
|
101
|
+
await sg.profilerProfile();
|
|
102
|
+
|
|
103
|
+
// Now hover + Cmd/Ctrl+C includes file:line info!
|
|
104
|
+
// Example output with profiler enabled:
|
|
105
|
+
//
|
|
106
|
+
// <div class="product-card">
|
|
107
|
+
// Premium Widget
|
|
108
|
+
// $29.99
|
|
109
|
+
// </div>
|
|
110
|
+
// in featured-collection (at sections/featured-collection.liquid:42) (15.2ms)
|
|
111
|
+
// in product-card (at snippets/product-card.liquid:3) (4.1ms)
|
|
112
|
+
// render: 19.3ms
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
### Profiler API
|
|
116
|
+
|
|
117
|
+
```javascript
|
|
118
|
+
const sg = window.__SHOPIFY_GRAB__;
|
|
119
|
+
|
|
120
|
+
// Authentication
|
|
121
|
+
await sg.profilerSignIn(); // Sign in (opens OAuth popup)
|
|
122
|
+
sg.profilerSignOut(); // Sign out and clear tokens
|
|
123
|
+
sg.profilerIsAuthenticated(); // Check if signed in
|
|
124
|
+
|
|
125
|
+
// Profiling
|
|
126
|
+
const profile = await sg.profilerProfile(); // Fetch profile for current page
|
|
127
|
+
sg.profilerHasProfile(); // Check if profile data loaded
|
|
128
|
+
sg.profilerClearCache(); // Clear cached profiles
|
|
129
|
+
|
|
130
|
+
// Element source resolution
|
|
131
|
+
sg.getSourceForElement(element); // Full source stack (layout -> template -> section -> snippet)
|
|
132
|
+
sg.getBestSourceForElement(element); // Most specific source location
|
|
133
|
+
sg.getRenderTimeForElement(element); // Section render time in ms
|
|
134
|
+
|
|
135
|
+
// Status monitoring
|
|
136
|
+
sg.profilerGetStatus(); // { state: "idle" | "authenticating" | "authenticated" | "fetching" | "ready" | "error" }
|
|
137
|
+
sg.profilerOnStatusChange((status) => console.log(status));
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
### Requirements
|
|
141
|
+
|
|
142
|
+
- A Shopify partner or staff account with access to the store
|
|
143
|
+
- The store must be accessible (live or via `shopify theme dev`)
|
|
144
|
+
- Profiling is read-only and does not affect store performance
|
|
145
|
+
|
|
146
|
+
### Without the profiler
|
|
147
|
+
|
|
148
|
+
Shopify Grab works without authentication, using DOM-based detection (data attributes, section IDs, class patterns). The profiler just adds richer source context.
|
|
149
|
+
|
|
81
150
|
## Features
|
|
82
151
|
|
|
83
152
|
- Same overlay UI as react-grab (crosshair, selection highlight, floating label)
|
|
153
|
+
- **Liquid profiler** for file:line source context (like bippy for React)
|
|
84
154
|
- Shopify green color scheme
|
|
85
155
|
- Canvas-based overlay for smooth 60fps animations
|
|
86
156
|
- Shadow DOM isolation (doesn't conflict with theme styles)
|
|
@@ -88,6 +158,7 @@ These attributes are automatically present in the Shopify Theme Editor and on st
|
|
|
88
158
|
- Right-click context menu with Copy, Copy HTML, Copy Screenshot
|
|
89
159
|
- Cursor IDE Lexical editor clipboard format support
|
|
90
160
|
- Plugin system for customization
|
|
161
|
+
- Render time display per section
|
|
91
162
|
|
|
92
163
|
## API
|
|
93
164
|
|
|
@@ -106,6 +177,10 @@ api.copyElement(document.querySelector('.product-card'));
|
|
|
106
177
|
|
|
107
178
|
// Get display name for an element
|
|
108
179
|
api.getDisplayName(element); // "featured-collection" or "header/menu"
|
|
180
|
+
|
|
181
|
+
// Get source info (uses profiler when available)
|
|
182
|
+
const source = await api.getSource(element);
|
|
183
|
+
// { filePath: "sections/header.liquid", lineNumber: 42, componentName: "header" }
|
|
109
184
|
```
|
|
110
185
|
|
|
111
186
|
## License
|