Add --standard-events-inspector flag to theme preview.

.changeset/sweet-areas-live.md

@@ -0,0 +1,5 @@
+---
+'@shopify/theme': minor
+---
+
+Add a new `--standard-events-inspector` flag to the `shopify theme dev` command to inject the Standard Storefront Events inspector into storefront previews.

docs-shopify.dev/commands/interfaces/theme-dev.interface.ts

@@ -100,6 +100,12 @@ export interface themedev {
    */
   '--port <value>'?: string
 
+  /**
+   * Inject the standard events inspector into storefront HTML.
+   * @environment SHOPIFY_FLAG_STANDARD_EVENTS_INSPECTOR
+   */
+  '--standard-events-inspector'?: ''
+
   /**
    * Store URL. It can be the store prefix (example) or the full myshopify.com URL (example.myshopify.com, https://example.myshopify.com).
    * @environment SHOPIFY_FLAG_STORE

docs-shopify.dev/generated/generated_docs_data_v2.json

@@ -4739,6 +4739,15 @@
           "isOptional": true,
           "environmentValue": "SHOPIFY_FLAG_PORT"
         },
+        {
+          "filePath": "docs-shopify.dev/commands/interfaces/theme-dev.interface.ts",
+          "syntaxKind": "PropertySignature",
+          "name": "--standard-events-inspector",
+          "value": "''",
+          "description": "Inject the standard events inspector into storefront HTML.",
+          "isOptional": true,
+          "environmentValue": "SHOPIFY_FLAG_STANDARD_EVENTS_INSPECTOR"
+        },
         {
           "filePath": "docs-shopify.dev/commands/interfaces/theme-dev.interface.ts",
           "syntaxKind": "PropertySignature",
@@ -4830,7 +4839,7 @@
           "environmentValue": "SHOPIFY_FLAG_IGNORE"
         }
       ],
-      "value": "export interface themedev {\n  /**\n   * Allow development on a live theme.\n   * @environment SHOPIFY_FLAG_ALLOW_LIVE\n   */\n  '-a, --allow-live'?: ''\n\n  /**\n   * The environment to apply to the current command.\n   * @environment SHOPIFY_FLAG_ENVIRONMENT\n   */\n  '-e, --environment <value>'?: string\n\n  /**\n   * Controls the visibility of the error overlay when an theme asset upload fails:\n- silent Prevents the error overlay from appearing.\n- default Displays the error overlay.\n      \n   * @environment SHOPIFY_FLAG_ERROR_OVERLAY\n   */\n  '--error-overlay <value>'?: string\n\n  /**\n   * Set which network interface the web server listens on. The default value is 127.0.0.1.\n   * @environment SHOPIFY_FLAG_HOST\n   */\n  '--host <value>'?: string\n\n  /**\n   * Skip hot reloading any files that match the specified pattern.\n   * @environment SHOPIFY_FLAG_IGNORE\n   */\n  '-x, --ignore <value>'?: string\n\n  /**\n   * The listing preset to use for multi-preset themes. Applies preset files from listings/[preset-name] directory.\n   * @environment SHOPIFY_FLAG_LISTING\n   */\n  '--listing <value>'?: string\n\n  /**\n   * The live reload mode switches the server behavior when a file is modified:\n- hot-reload Hot reloads local changes to CSS and sections (default)\n- full-page  Always refreshes the entire page\n- off        Deactivate live reload\n   * @environment SHOPIFY_FLAG_LIVE_RELOAD\n   */\n  '--live-reload <value>'?: string\n\n  /**\n   * Disable color output.\n   * @environment SHOPIFY_FLAG_NO_COLOR\n   */\n  '--no-color'?: ''\n\n  /**\n   * Prevents files from being deleted in the remote theme when a file has been deleted locally. This applies to files that are deleted while the command is running, and files that have been deleted locally before the command is run.\n   * @environment SHOPIFY_FLAG_NODELETE\n   */\n  '-n, --nodelete'?: ''\n\n  /**\n   * The file path or URL. The file path is to a file that you want updated on idle. The URL path is where you want a webhook posted to report on file changes.\n   * @environment SHOPIFY_FLAG_NOTIFY\n   */\n  '--notify <value>'?: string\n\n  /**\n   * Hot reload only files that match the specified pattern.\n   * @environment SHOPIFY_FLAG_ONLY\n   */\n  '-o, --only <value>'?: string\n\n  /**\n   * Automatically launch the theme preview in your default web browser.\n   * @environment SHOPIFY_FLAG_OPEN\n   */\n  '--open'?: ''\n\n  /**\n   * Password generated from the Theme Access app or an Admin API token.\n   * @environment SHOPIFY_CLI_THEME_TOKEN\n   */\n  '--password <value>'?: string\n\n  /**\n   * The path where you want to run the command. Defaults to the current working directory.\n   * @environment SHOPIFY_FLAG_PATH\n   */\n  '--path <value>'?: string\n\n  /**\n   * Local port to serve theme preview from. Must be between 1 and 65535.\n   * @environment SHOPIFY_FLAG_PORT\n   */\n  '--port <value>'?: string\n\n  /**\n   * Store URL. It can be the store prefix (example) or the full myshopify.com URL (example.myshopify.com, https://example.myshopify.com).\n   * @environment SHOPIFY_FLAG_STORE\n   */\n  '-s, --store <value>'?: string\n\n  /**\n   * The password for storefronts with password protection.\n   * @environment SHOPIFY_FLAG_STORE_PASSWORD\n   */\n  '--store-password <value>'?: string\n\n  /**\n   * Theme ID or name of the remote theme.\n   * @environment SHOPIFY_FLAG_THEME_ID\n   */\n  '-t, --theme <value>'?: string\n\n  /**\n   * Synchronize Theme Editor updates in the local theme files.\n   * @environment SHOPIFY_FLAG_THEME_EDITOR_SYNC\n   */\n  '--theme-editor-sync'?: ''\n\n  /**\n   * Increase the verbosity of the output.\n   * @environment SHOPIFY_FLAG_VERBOSE\n   */\n  '--verbose'?: ''\n}"
+      "value": "export interface themedev {\n  /**\n   * Allow development on a live theme.\n   * @environment SHOPIFY_FLAG_ALLOW_LIVE\n   */\n  '-a, --allow-live'?: ''\n\n  /**\n   * The environment to apply to the current command.\n   * @environment SHOPIFY_FLAG_ENVIRONMENT\n   */\n  '-e, --environment <value>'?: string\n\n  /**\n   * Controls the visibility of the error overlay when an theme asset upload fails:\n- silent Prevents the error overlay from appearing.\n- default Displays the error overlay.\n      \n   * @environment SHOPIFY_FLAG_ERROR_OVERLAY\n   */\n  '--error-overlay <value>'?: string\n\n  /**\n   * Set which network interface the web server listens on. The default value is 127.0.0.1.\n   * @environment SHOPIFY_FLAG_HOST\n   */\n  '--host <value>'?: string\n\n  /**\n   * Skip hot reloading any files that match the specified pattern.\n   * @environment SHOPIFY_FLAG_IGNORE\n   */\n  '-x, --ignore <value>'?: string\n\n  /**\n   * The listing preset to use for multi-preset themes. Applies preset files from listings/[preset-name] directory.\n   * @environment SHOPIFY_FLAG_LISTING\n   */\n  '--listing <value>'?: string\n\n  /**\n   * The live reload mode switches the server behavior when a file is modified:\n- hot-reload Hot reloads local changes to CSS and sections (default)\n- full-page  Always refreshes the entire page\n- off        Deactivate live reload\n   * @environment SHOPIFY_FLAG_LIVE_RELOAD\n   */\n  '--live-reload <value>'?: string\n\n  /**\n   * Disable color output.\n   * @environment SHOPIFY_FLAG_NO_COLOR\n   */\n  '--no-color'?: ''\n\n  /**\n   * Prevents files from being deleted in the remote theme when a file has been deleted locally. This applies to files that are deleted while the command is running, and files that have been deleted locally before the command is run.\n   * @environment SHOPIFY_FLAG_NODELETE\n   */\n  '-n, --nodelete'?: ''\n\n  /**\n   * The file path or URL. The file path is to a file that you want updated on idle. The URL path is where you want a webhook posted to report on file changes.\n   * @environment SHOPIFY_FLAG_NOTIFY\n   */\n  '--notify <value>'?: string\n\n  /**\n   * Hot reload only files that match the specified pattern.\n   * @environment SHOPIFY_FLAG_ONLY\n   */\n  '-o, --only <value>'?: string\n\n  /**\n   * Automatically launch the theme preview in your default web browser.\n   * @environment SHOPIFY_FLAG_OPEN\n   */\n  '--open'?: ''\n\n  /**\n   * Password generated from the Theme Access app or an Admin API token.\n   * @environment SHOPIFY_CLI_THEME_TOKEN\n   */\n  '--password <value>'?: string\n\n  /**\n   * The path where you want to run the command. Defaults to the current working directory.\n   * @environment SHOPIFY_FLAG_PATH\n   */\n  '--path <value>'?: string\n\n  /**\n   * Local port to serve theme preview from. Must be between 1 and 65535.\n   * @environment SHOPIFY_FLAG_PORT\n   */\n  '--port <value>'?: string\n\n  /**\n   * Inject the standard events inspector into storefront HTML.\n   * @environment SHOPIFY_FLAG_STANDARD_EVENTS_INSPECTOR\n   */\n  '--standard-events-inspector'?: ''\n\n  /**\n   * Store URL. It can be the store prefix (example) or the full myshopify.com URL (example.myshopify.com, https://example.myshopify.com).\n   * @environment SHOPIFY_FLAG_STORE\n   */\n  '-s, --store <value>'?: string\n\n  /**\n   * The password for storefronts with password protection.\n   * @environment SHOPIFY_FLAG_STORE_PASSWORD\n   */\n  '--store-password <value>'?: string\n\n  /**\n   * Theme ID or name of the remote theme.\n   * @environment SHOPIFY_FLAG_THEME_ID\n   */\n  '-t, --theme <value>'?: string\n\n  /**\n   * Synchronize Theme Editor updates in the local theme files.\n   * @environment SHOPIFY_FLAG_THEME_EDITOR_SYNC\n   */\n  '--theme-editor-sync'?: ''\n\n  /**\n   * Increase the verbosity of the output.\n   * @environment SHOPIFY_FLAG_VERBOSE\n   */\n  '--verbose'?: ''\n}"
     }
   },
   "themeduplicate": {

packages/cli/README.md

@@ -2321,8 +2321,8 @@ Uploads the current theme as a development theme to the connected store, then pr
 USAGE
   $ shopify theme dev [-a] [-e <value>...] [--error-overlay silent|default] [--host <value>] [-x <value>...]
     [--listing <value>] [--live-reload hot-reload|full-page|off] [--no-color] [-n] [--notify <value>] [-o <value>...]
-    [--open] [--password <value>] [--path <value>] [--port <value>] [-s <value>] [--store-password <value>] [-t <value>]
-    [--theme-editor-sync] [--verbose]
+    [--open] [--password <value>] [--path <value>] [--port <value>] [--standard-events-inspector] [-s <value>]
+    [--store-password <value>] [-t <value>] [--theme-editor-sync] [--verbose]
 
 FLAGS
   -a, --allow-live
@@ -2391,6 +2391,9 @@ FLAGS
   --port=<value>
       [env: SHOPIFY_FLAG_PORT] Local port to serve theme preview from. Must be between 1 and 65535.
 
+  --standard-events-inspector
+      [env: SHOPIFY_FLAG_STANDARD_EVENTS_INSPECTOR] Inject the standard events inspector into storefront HTML.
+
   --store-password=<value>
       [env: SHOPIFY_FLAG_STORE_PASSWORD] The password for storefronts with password protection.
 

packages/cli/oclif.manifest.json

@@ -6503,6 +6503,13 @@
           "name": "port",
           "type": "option"
         },
+        "standard-events-inspector": {
+          "allowNo": false,
+          "description": "Inject the standard events inspector into storefront HTML.",
+          "env": "SHOPIFY_FLAG_STANDARD_EVENTS_INSPECTOR",
+          "name": "standard-events-inspector",
+          "type": "boolean"
+        },
         "store": {
           "char": "s",
           "description": "Store URL. It can be the store prefix (example) or the full myshopify.com URL (example.myshopify.com, https://example.myshopify.com).",

packages/theme/src/cli/commands/theme/dev.ts

@@ -77,6 +77,11 @@ You can run this command only in a directory that matches the [default Shopify t
       description: 'Synchronize Theme Editor updates in the local theme files.',
       env: 'SHOPIFY_FLAG_THEME_EDITOR_SYNC',
     }),
+    'standard-events-inspector': Flags.boolean({
+      description: 'Inject the standard events inspector into storefront HTML.',
+      env: 'SHOPIFY_FLAG_STANDARD_EVENTS_INSPECTOR',
+      default: false,
+    }),
     port: portFlag({
       description: 'Local port to serve theme preview from.',
       env: 'SHOPIFY_FLAG_PORT',
@@ -180,6 +185,7 @@ You can run this command only in a directory that matches the [default Shopify t
       force: flags.force,
       open: flags.open,
       'theme-editor-sync': flags['theme-editor-sync'],
+      'standard-events-inspector': flags['standard-events-inspector'],
       noDelete: flags.nodelete,
       ignore,
       only,

packages/theme/src/cli/services/dev.test.ts

@@ -3,8 +3,8 @@ import {setupDevServer} from '../utilities/theme-environment/theme-environment.j
 import {hasRequiredThemeDirectories} from '../utilities/theme-fs.js'
 import {isStorefrontPasswordProtected} from '../utilities/theme-environment/storefront-session.js'
 import {initializeDevServerSession} from '../utilities/theme-environment/dev-server-session.js'
-import {describe, expect, test, vi, beforeEach, afterEach, type MockInstance} from 'vitest'
 import {buildTheme} from '@shopify/cli-kit/node/themes/factories'
+import {describe, expect, test, vi, beforeEach, afterEach, type MockInstance} from 'vitest'
 import {DEVELOPMENT_THEME_ROLE} from '@shopify/cli-kit/node/themes/utils'
 import {renderSuccess, renderWarning} from '@shopify/cli-kit/node/ui'
 import {openURL} from '@shopify/cli-kit/node/system'
@@ -284,6 +284,7 @@ describe('dev() Ctrl-C analytics', () => {
     open: false,
     theme,
     force: false,
+    'standard-events-inspector': false,
     'theme-editor-sync': false,
     'live-reload': 'hot-reload' as const,
     'error-overlay': 'default' as const,
@@ -351,6 +352,44 @@ describe('dev() Ctrl-C analytics', () => {
 
     expect(reportAnalyticsEvent).toHaveBeenCalledTimes(1)
   })
+
+  test('enables the standard events dev bundle by default', async () => {
+    const devPromise = dev({...baseOptions, 'standard-events-inspector': false})
+
+    await new Promise((resolve) => setImmediate(resolve))
+
+    resolveBackgroundJob()
+    await devPromise
+
+    expect(setupDevServer).toHaveBeenCalledWith(
+      theme,
+      expect.objectContaining({
+        options: expect.objectContaining({
+          standardEventsDevBundle: true,
+          standardEventsInspector: false,
+        }),
+      }),
+    )
+  })
+
+  test('propagates the inspector option to the dev server context', async () => {
+    const devPromise = dev({...baseOptions, 'standard-events-inspector': true})
+
+    await new Promise((resolve) => setImmediate(resolve))
+
+    resolveBackgroundJob()
+    await devPromise
+
+    expect(setupDevServer).toHaveBeenCalledWith(
+      theme,
+      expect.objectContaining({
+        options: expect.objectContaining({
+          standardEventsDevBundle: true,
+          standardEventsInspector: true,
+        }),
+      }),
+    )
+  })
 })
 
 describe('dev() port validation', () => {
@@ -368,6 +407,7 @@ describe('dev() port validation', () => {
     open: false,
     theme,
     force: false,
+    'standard-events-inspector': false,
     'theme-editor-sync': false,
     'live-reload': 'hot-reload' as const,
     'error-overlay': 'default' as const,

packages/theme/src/cli/services/dev.ts

@@ -39,6 +39,7 @@ interface DevOptions {
   host?: string
   port?: number
   force: boolean
+  'standard-events-inspector': boolean
   'theme-editor-sync': boolean
   'live-reload': LiveReload
   'error-overlay': ErrorOverlayMode
@@ -132,6 +133,8 @@ export async function dev(options: DevOptions) {
       port,
       open: options.open,
       liveReload: options['live-reload'],
+      standardEventsDevBundle: true,
+      standardEventsInspector: options['standard-events-inspector'],
       noDelete: options.noDelete,
       ignore: options.ignore,
       only: options.only,

packages/theme/src/cli/utilities/theme-environment/hot-reload/server.test.ts

@@ -557,6 +557,8 @@ function createTestContext(options?: {files?: [string, string][]}) {
       host: '',
       port: 9292,
       liveReload: 'hot-reload',
+      standardEventsDevBundle: false,
+      standardEventsInspector: false,
       open: false,
       themeEditorSync: false,
       errorOverlay: 'default',

packages/theme/src/cli/utilities/theme-environment/html.ts

@@ -2,6 +2,7 @@ import {getErrorPage} from './hot-reload/error-page.js'
 import {render} from './storefront-renderer.js'
 import {getInMemoryTemplates, handleHotReloadScriptInjection} from './hot-reload/server.js'
 import {getProxyStorefrontHeaders, patchRenderingResponse, proxyStorefrontRequest} from './proxy.js'
+import {injectStandardEventsInspector} from './standard-events.js'
 import {extractFetchErrorInfo} from '../errors.js'
 import {logRequestLine} from '../log-request-line.js'
 import {getExtensionInMemoryTemplates} from '../theme-ext-environment/theme-ext-server.js'
@@ -144,7 +145,8 @@ function createErrorPageResponse(
   responseInit: ResponseInit,
   options: Parameters<typeof getErrorPage>[0],
 ) {
-  const errorPageHtml = handleHotReloadScriptInjection(getErrorPage(options), ctx)
+  let errorPageHtml = handleHotReloadScriptInjection(getErrorPage(options), ctx)
+  if (ctx.options.standardEventsInspector) errorPageHtml = injectStandardEventsInspector(errorPageHtml)
 
   recordEvent('theme-service:error-page:rendered')
 
@@ -180,6 +182,14 @@ async function tryProxyRequest(event: H3Event, ctx: DevServerContext, response:
 
   if (proxyResponse.status < 400) {
     outputDebug(`Proxy status: ${proxyResponse.status}. Returning proxy response.`)
+
+    if (
+      ctx.options.standardEventsInspector &&
+      (proxyResponse.headers.get('content-type') ?? '').includes('text/html')
+    ) {
+      return patchRenderingResponse(ctx, proxyResponse)
+    }
+
     return proxyResponse
   } else {
     outputDebug(`Proxy status: ${proxyResponse.status}. Returning render error.`)

packages/theme/src/cli/utilities/theme-environment/local-assets.ts

@@ -235,7 +235,7 @@ function getTagContent(file: ThemeAsset, tag: 'javascript' | 'stylesheet') {
 
   const contents = [`/* ${file.key} */`]
 
-  const tagContent = getLiquidTagContent(file.value ?? '', tag)
+  const tagContent = getLiquidTagContent(file.value ?? '', tag)?.trimEnd()
   if (tagContent) {
     contents.push(tagContent)
   }