Inspect Shopify Liquid sections, blocks, and snippets from the official Vite DevTools dock. Pick a rendered component, understand its Liquid/DOM hierarchy, and open its source in your editor without changing production builds.
Vite 8.3 or newer is required and must be a direct project dependency.
npm install -D vite@^8.3 @display-studio/vite-plugin-shopify-devtoolsConfigure the DevTools preset and plugin:
// vite.config.ts
import { defineConfig } from 'vite'
import shopify from 'vite-plugin-shopify'
import shopifyDevtools, { shopifyDevtoolsConfig } from '@display-studio/vite-plugin-shopify-devtools'
export default defineConfig({
devtools: shopifyDevtoolsConfig,
plugins: [
shopify(),
shopifyDevtools({
// Optional: override editor detection.
editor: 'zed',
}),
],
})Already have a theme with Vite? npx shopify-devtools init applies the configuration above, and npx shopify-devtools doctor checks the setup.
Run Vite alongside shopify theme dev as usual. The plugin works with vite-plugin-shopify and vite-plugin-shopify-theme. It runs only during vite serve; production builds and source Liquid files are unchanged in the default mode.
Shopify preview hosts and configured store domains are allowed automatically. Custom domains or tunnels must be added through the Vite DevTools allowedOrigins setting.
The browser client must be injected through a JavaScript entry. The plugin normally discovers one from Vite's build.input. If your theme has only CSS entries or discovery fails, add a small JavaScript/TypeScript entry or set shopifyDevtools({ entry: 'frontend/theme.ts' }).
Open Shopify Liquid in the Vite DevTools dock, then choose Inspect page to select a rendered component. The tree can be searched by component name, path, kind, or template metadata. Select an entry to inspect it; press Enter or use the details action to open its source. Paths, locations, and available Shopify IDs can also be copied. Hovering an entry highlights it on the page, and Open in Theme Editor opens the previewed theme in the Shopify admin. The details also offer a ready-to-paste Liquid tag, a collapsed Settings list shows the section or block settings from its {% schema %} with their current values, and Alt+Shift+L toggles the inspector.
On first connection, Vite DevTools may show Unauthorized while Vite prints a one-time code and authorization link. Authorize the browser, then reload the storefront if it does not reconnect. Trust is stored in that browser and may need to be renewed after clearing site data, changing hostname, updating DevTools, or revoking trust.
For controlled automation, configure clientAuthTokens and provide the same secret to the browser:
devtools: {
...shopifyDevtoolsConfig,
clientAuthTokens: [process.env.VITE_DEVTOOLS_AUTH_TOKEN!],
}Keep tokens out of source control and logs. Setting clientAuth: false disables authentication and gives any browser that can reach Vite access to DevTools server and filesystem capabilities; use it only in a fully trusted local environment.
| Mode | Setup | Result |
|---|---|---|
| Default | None | Exact sections and section groups; inferred blocks and static snippets. |
| Full | instrument: 'copy' (recommended), 'in-place', or the CLI wrapper |
Exact sections, theme blocks, static snippets, and nesting from markers. |
The same read-only inspection backend is available to coding agents through a DevFrame MCP server. Start it from the theme directory, or pass an explicit theme root:
shopify-devtools mcp
shopify-devtools mcp --theme-path /absolute/path/to/themeFor an MCP client, configure the installed binary and use an absolute theme path:
{
"mcpServers": {
"shopify-liquid-devtools": {
"command": "/absolute/path/to/node_modules/.bin/shopify-devtools",
"args": ["mcp", "--theme-path", "/absolute/path/to/theme"]
}
}
}The server exposes shopify-devtools_resolve-sections for mapping storefront section IDs to Liquid sources and shopify-devtools_schema for reading section or theme-block settings. Both tools are marked read-only. They only inspect the configured theme root; editor launching, instrumentation, arbitrary file reads, and writes are not exposed. MCP uses stdout for its protocol, so operational errors are written to stderr.
Shopify's rendered HTML does not preserve the source identity of most blocks and snippets. Default mode therefore matches distinctive static output such as tags, classes, IDs, and data-* attributes. Inferred entries include a confidence rating, and ambiguous or invisible components are omitted rather than guessed. Dynamic markup or DOM rewritten by JavaScript may not match. Use full mode when the exact tree matters.
The recommended option creates and maintains an ignored, instrumented theme mirror while leaving source files untouched:
shopifyDevtools({ instrument: 'copy' })Add .shopify-devtools/ to .gitignore, start Vite first, and point Shopify CLI at the mirror:
SHOPIFY_FLAG_PATH=.shopify-devtools/theme shopify theme devWith @display-studio/vite-plugin-shopify-theme, vite-shopify-theme dev starts Vite first and Shopify CLI once the dev server is ready, so the same variable goes in front of it: SHOPIFY_FLAG_PATH=.shopify-devtools/theme vite-shopify-theme dev. Use devtools 0.5.0 or later and theme plugin 0.7.1 or later: earlier devtools versions removed the mirror when the server started, and earlier theme plugin versions ended the process before the mirror could be removed after Ctrl+C.
You may instead configure that path in shopify.theme.toml, though an explicit --path or SHOPIFY_FLAG_PATH is more reliable across Shopify CLI versions.
Use instrument: 'in-place' only when Shopify CLI must serve the source directory. It temporarily rewrites Liquid and uses .shopify-devtools/in-place-journal.json to restore originals and recover after crashes. Do not delete that journal while recovery is pending; startup stops rather than overwriting a file changed independently.
The compatibility wrapper shopify-devtools dev is also available. It creates a temporary instrumented mirror, starts Shopify CLI and Vite, and forwards Shopify flags. For example: shopify-devtools dev --environment development.
Editor selection uses, in order: the editor plugin option, SHOPIFY_DEVTOOLS_EDITOR, EDITOR, then macOS detection of Zed, Cursor, or VS Code. Editors supported by launch-editor open at the component line. Terminal editors take over the Vite terminal until you quit them.
The plugin inspects Shopify Liquid, not Vue components. @vitejs/plugin-vue works normally. With Vue DevTools 8, set appendTo to the theme's JavaScript entry because Shopify serves the HTML:
vueDevTools({ appendTo: 'frontend/entrypoints/theme.ts' })Before 1.0, the supported package surface is deliberately small:
- default export:
shopifyDevtools - runtime presets:
shopifyDevtoolsConfigandshopifyDevtoolsBranding - type export:
ShopifyDevtoolsOptions
Other shipped helpers and renderer files are implementation details and may change without notice.
Run npx shopify-devtools doctor in the theme directory. It reports the Vite version, DevTools preset, theme root, entry, .gitignore and store configuration, and warns when an installed vite-plugin-shopify-theme is older than 0.7.1.
SHOPIFY_FLAG_PATH=.shopify-devtools/theme points at the mirror, and the mirror was not there when Shopify CLI started. Before 0.5.0 the plugin removed the mirror as soon as the dev server started, so update to 0.5.0 or later. Versions are 0.x, so a range such as ^0.4.0 never includes 0.5.0 and a plain bun update or npm update keeps the old one; install the new version explicitly, for example bun add -d @display-studio/vite-plugin-shopify-devtools@latest. If you use vite-shopify-theme dev, it prints a warning that names this cause when the folder is missing.
Confirm vite --version is 8.3 or newer, devtools: shopifyDevtoolsConfig is at the top level of defineConfig, and the storefront entry loads from the Vite origin shown in the error. Restart Vite and Shopify CLI after configuration changes.
Check the browser console for a failed entry script or RPC request. Confirm the page contains Shopify section wrappers, the active template JSON and matching Liquid files are under the resolved theme root, and a JavaScript entry exists in build.input or is set with entry. Default inference needs distinctive static output; switch to full mode for exact markers.
Use the one-time authorization link or code printed by Vite and reload. Repeat after hostname or trust changes. Never paste codes or tokens into issues; use matching clientAuthTokens only for controlled automation.