Add listing flag to dev, push, and share commands

chrisberthe · chrisberthe · commit 5d0dcaf62ce8 · 2025-06-27T09:22:52.000-04:00
diff --git a/.changeset/polite-eyes-warn.md b/.changeset/polite-eyes-warn.md
@@ -0,0 +1,7 @@
+---
+'@shopify/cli-kit': patch
+'@shopify/theme': patch
+'@shopify/cli': patch
+---
+
+Add --listing flag to theme dev, push, and share commands
diff --git a/docs-shopify.dev/commands/interfaces/theme-dev.interface.ts b/docs-shopify.dev/commands/interfaces/theme-dev.interface.ts
@@ -10,7 +10,7 @@ export interface themedev {
    * Controls the visibility of the error overlay when an theme asset upload fails:
 - silent Prevents the error overlay from appearing.
 - default Displays the error overlay.
-      
+
    * @environment SHOPIFY_FLAG_ERROR_OVERLAY
    */
   '--error-overlay <value>'?: string
@@ -27,6 +27,12 @@ export interface themedev {
    */
   '-x, --ignore <value>'?: string
 
+  /**
+   * The listing preset to use for multi-preset themes. Applies preset files from listings/[preset-name] directory.
+   * @environment SHOPIFY_FLAG_LISTING
+   */
+  '--listing <value>'?: string
+
   /**
    * The live reload mode switches the server behavior when a file is modified:
 - hot-reload Hot reloads local changes to CSS and sections (default)
diff --git a/docs-shopify.dev/commands/interfaces/theme-push.interface.ts b/docs-shopify.dev/commands/interfaces/theme-push.interface.ts
@@ -30,6 +30,12 @@ export interface themepush {
    */
   '-j, --json'?: ''
 
+  /**
+   * The listing preset to use for multi-preset themes. Applies preset files from listings/[preset-name] directory.
+   * @environment SHOPIFY_FLAG_LISTING
+   */
+  '--listing <value>'?: string
+
   /**
    * Push theme files from your remote live theme.
    * @environment SHOPIFY_FLAG_LIVE
diff --git a/docs-shopify.dev/commands/interfaces/theme-share.interface.ts b/docs-shopify.dev/commands/interfaces/theme-share.interface.ts
@@ -6,6 +6,12 @@ export interface themeshare {
    */
   '-e, --environment <value>'?: string
 
+  /**
+   * The listing preset to use for multi-preset themes. Applies preset files from listings/[preset-name] directory.
+   * @environment SHOPIFY_FLAG_LISTING
+   */
+  '--listing <value>'?: string
+
   /**
    * Disable color output.
    * @environment SHOPIFY_FLAG_NO_COLOR
diff --git a/docs-shopify.dev/generated/generated_docs_data.json b/docs-shopify.dev/generated/generated_docs_data.json
diff --git a/packages/cli-kit/src/public/node/themes/types.ts b/packages/cli-kit/src/public/node/themes/types.ts
@@ -27,8 +27,9 @@ export type ThemeFSEventPayload<T extends ThemeFSEventName = 'add'> = (ThemeFSEv
 
 export interface ThemeFileSystemOptions {
   filters?: {ignore?: string[]; only?: string[]}
-  notify?: string
+  listing?: string
   noDelete?: boolean
+  notify?: string
 }
 
 /**
diff --git a/packages/cli/README.md b/packages/cli/README.md
@@ -1822,9 +1822,9 @@ Uploads the current theme as a development theme to the connected store, then pr
 
 ```
 USAGE
-  $ shopify theme dev [-e <value>] [--error-overlay silent|default] [--host <value>] [-x <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>]
+  $ shopify theme dev [-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]
 
 FLAGS
@@ -1858,6 +1858,10 @@ FLAGS
   --host=<value>
       Set which network interface the web server listens on. The default value is 127.0.0.1.
 
+  --listing=<value>
+      The listing preset to use for multi-preset themes. Applies preset files from listings/[preset-name]
+      directory.
+
   --live-reload=<option>
       [default: hot-reload] The live reload mode switches the server behavior when a file is modified:
       - hot-reload Hot reloads local changes to CSS and sections (default)
@@ -2238,6 +2242,8 @@ FLAGS
   -t, --theme=<value>           Theme ID or name of the remote theme.
   -u, --unpublished             Create a new unpublished theme and push to it.
   -x, --ignore=<value>...       Skip uploading the specified files (Multiple flags allowed).
+      --listing=<value>         The listing preset to use for multi-preset themes. Applies preset files from
+                                listings/[preset-name] directory.
       --no-color                Disable color output.
       --password=<value>        Password generated from the Theme Access app.
       --path=<value>            The path to your theme directory.
@@ -2317,12 +2323,15 @@ Creates a shareable, unpublished, and new theme on your theme library with a ran
 
 ```
 USAGE
-  $ shopify theme share [-e <value>] [--no-color] [--password <value>] [--path <value>] [-s <value>] [--verbose]
+  $ shopify theme share [-e <value>] [--listing <value>] [--no-color] [--password <value>] [--path <value>] [-s
+    <value>] [--verbose]
 
 FLAGS
   -e, --environment=<value>...  The environment to apply to the current command.
   -s, --store=<value>           Store URL. It can be the store prefix (example) or the full myshopify.com URL
                                 (example.myshopify.com, https://example.myshopify.com).
+      --listing=<value>         The listing preset to use for multi-preset themes. Applies preset files from
+                                listings/[preset-name] directory.
       --no-color                Disable color output.
       --password=<value>        Password generated from the Theme Access app.
       --path=<value>            The path to your theme directory.
diff --git a/packages/cli/oclif.manifest.json b/packages/cli/oclif.manifest.json
@@ -5246,6 +5246,14 @@
           "name": "ignore",
           "type": "option"
         },
+        "listing": {
+          "description": "The listing preset to use for multi-preset themes. Applies preset files from listings/[preset-name] directory.",
+          "env": "SHOPIFY_FLAG_LISTING",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "name": "listing",
+          "type": "option"
+        },
         "live-reload": {
           "default": "hot-reload",
           "description": "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",
@@ -6274,6 +6282,14 @@
           "name": "json",
           "type": "boolean"
         },
+        "listing": {
+          "description": "The listing preset to use for multi-preset themes. Applies preset files from listings/[preset-name] directory.",
+          "env": "SHOPIFY_FLAG_LISTING",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "name": "listing",
+          "type": "option"
+        },
         "live": {
           "allowNo": false,
           "char": "l",
@@ -6542,6 +6558,14 @@
           "name": "ignore",
           "type": "option"
         },
+        "listing": {
+          "description": "The listing preset to use for multi-preset themes. Applies preset files from listings/[preset-name] directory.",
+          "env": "SHOPIFY_FLAG_LISTING",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "name": "listing",
+          "type": "option"
+        },
         "live-reload": {
           "default": "hot-reload",
           "description": "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",
@@ -6711,6 +6735,14 @@
           "name": "force",
           "type": "boolean"
         },
+        "listing": {
+          "description": "The listing preset to use for multi-preset themes. Applies preset files from listings/[preset-name] directory.",
+          "env": "SHOPIFY_FLAG_LISTING",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "name": "listing",
+          "type": "option"
+        },
         "no-color": {
           "allowNo": false,
           "description": "Disable color output.",
@@ -6940,4 +6972,4 @@
     }
   },
   "version": "3.81.1"
-}
+}
diff --git a/packages/theme/package.json b/packages/theme/package.json
@@ -46,6 +46,7 @@
     "@shopify/cli-kit": "3.81.1",
     "@shopify/theme-check-node": "3.17.0",
     "@shopify/theme-language-server-node": "2.15.2",
+    "change-case": "4.1.2",
     "chokidar": "3.6.0",
     "h3": "1.13.0",
     "yaml": "2.7.0"
diff --git a/packages/theme/src/cli/commands/theme/dev.ts b/packages/theme/src/cli/commands/theme/dev.ts
@@ -82,6 +82,11 @@ You can run this command only in a directory that matches the [default Shopify t
       description: 'Theme ID or name of the remote theme.',
       env: 'SHOPIFY_FLAG_THEME_ID',
     }),
+    listing: Flags.string({
+      description:
+        'The listing preset to use for multi-preset themes. Applies preset files from listings/[preset-name] directory.',
+      env: 'SHOPIFY_FLAG_LISTING',
+    }),
     nodelete: Flags.boolean({
       char: 'n',
       description:
@@ -153,6 +158,7 @@ You can run this command only in a directory that matches the [default Shopify t
       password: flags.password,
       storePassword: flags['store-password'],
       theme,
+      listing: flags.listing,
       host: flags.host,
       port: flags.port,
       'live-reload': flags['live-reload'] as LiveReload,
diff --git a/packages/theme/src/cli/commands/theme/push.ts b/packages/theme/src/cli/commands/theme/push.ts
@@ -81,6 +81,11 @@ export default class Push extends ThemeCommand {
       multiple: true,
       env: 'SHOPIFY_FLAG_IGNORE',
     }),
+    listing: Flags.string({
+      description:
+        'The listing preset to use for multi-preset themes. Applies preset files from listings/[preset-name] directory.',
+      env: 'SHOPIFY_FLAG_LISTING',
+    }),
     'allow-live': Flags.boolean({
       char: 'a',
       description: 'Allow push to a live theme.',
@@ -117,6 +122,7 @@ export default class Push extends ThemeCommand {
       nodelete: flags.nodelete,
       only: flags.only,
       ignore: flags.ignore,
+      listing: flags.listing,
       json: flags.json,
       allowLive: flags['allow-live'],
       publish: flags.publish,
diff --git a/packages/theme/src/cli/commands/theme/share.ts b/packages/theme/src/cli/commands/theme/share.ts
@@ -23,6 +23,11 @@ export default class Share extends ThemeCommand {
       description: 'Proceed without confirmation, if current directory does not seem to be theme directory.',
       env: 'SHOPIFY_FLAG_FORCE',
     }),
+    listing: Flags.string({
+      description:
+        'The listing preset to use for multi-preset themes. Applies preset files from listings/[preset-name] directory.',
+      env: 'SHOPIFY_FLAG_LISTING',
+    }),
   }
 
   static cli2Flags = ['force']
@@ -37,6 +42,7 @@ export default class Share extends ThemeCommand {
       store: flags.store,
       unpublished: true,
       theme: getRandomName('creative'),
+      listing: flags.listing,
     }
 
     await push(pushFlags)
diff --git a/packages/theme/src/cli/services/dev.ts b/packages/theme/src/cli/services/dev.ts
@@ -36,6 +36,7 @@ export interface DevOptions {
   ignore: string[]
   only: string[]
   notify?: string
+  listing?: string
 }
 
 export async function dev(options: DevOptions) {
@@ -50,8 +51,9 @@ export async function dev(options: DevOptions) {
   const localThemeExtensionFileSystem = emptyThemeExtFileSystem()
   const localThemeFileSystem = mountThemeFileSystem(options.directory, {
     filters: options,
-    notify: options.notify,
+    listing: options.listing,
     noDelete: options.noDelete,
+    notify: options.notify,
   })
 
   const host = options.host ?? DEFAULT_HOST
diff --git a/packages/theme/src/cli/services/push.test.ts b/packages/theme/src/cli/services/push.test.ts
@@ -5,31 +5,34 @@ import {uploadTheme} from '../utilities/theme-uploader.js'
 import {ensureThemeStore} from '../utilities/theme-store.js'
 import {findOrSelectTheme} from '../utilities/theme-selector.js'
 import {runThemeCheck} from '../commands/theme/check.js'
+import {mountThemeFileSystem} from '../utilities/theme-fs.js'
 import {buildTheme} from '@shopify/cli-kit/node/themes/factories'
 import {test, describe, vi, expect, beforeEach} from 'vitest'
 import {themeCreate, fetchTheme, themePublish} from '@shopify/cli-kit/node/themes/api'
 import {ensureAuthenticatedThemes} from '@shopify/cli-kit/node/session'
 import {
   DEVELOPMENT_THEME_ROLE,
   LIVE_THEME_ROLE,
-  promptThemeName,
   UNPUBLISHED_THEME_ROLE,
+  promptThemeName,
 } from '@shopify/cli-kit/node/themes/utils'
 import {renderConfirmationPrompt} from '@shopify/cli-kit/node/ui'
-import {AbortError} from '@shopify/cli-kit/node/error'
 import {Severity, SourceCodeType} from '@shopify/theme-check-node'
 import {outputResult} from '@shopify/cli-kit/node/output'
+import {AbortError} from '@shopify/cli-kit/node/error'
 
 vi.mock('../utilities/theme-uploader.js')
 vi.mock('../utilities/theme-store.js')
 vi.mock('../utilities/theme-selector.js')
 vi.mock('./local-storage.js')
+vi.mock('../utilities/theme-listing.js')
 vi.mock('@shopify/cli-kit/node/themes/utils')
 vi.mock('@shopify/cli-kit/node/session')
 vi.mock('@shopify/cli-kit/node/themes/api')
 vi.mock('@shopify/cli-kit/node/ui')
 vi.mock('../commands/theme/check.js')
 vi.mock('@shopify/cli-kit/node/output')
+vi.mock('../utilities/theme-fs.js')
 
 const path = '/my-theme'
 const defaultFlags: PullFlags = {
@@ -240,6 +243,23 @@ describe('push', () => {
       expect(runThemeCheck).toHaveBeenCalledWith(path, 'json')
     })
   })
+
+  test('passes listing flag to file system when provided', async () => {
+    // Given
+    const theme = buildTheme({id: 1, name: 'Theme', role: 'development'})!
+    vi.mocked(findOrSelectTheme).mockResolvedValue(theme)
+
+    // When
+    await push({...defaultFlags, listing: 'my-preset'})
+
+    // Then
+    expect(mountThemeFileSystem).toHaveBeenCalledWith(
+      path,
+      expect.objectContaining({
+        listing: 'my-preset',
+      }),
+    )
+  })
 })
 
 describe('createOrSelectTheme', async () => {
diff --git a/packages/theme/src/cli/services/push.ts b/packages/theme/src/cli/services/push.ts
@@ -32,6 +32,7 @@ interface PushOptions {
   publish?: boolean
   ignore?: string[]
   only?: string[]
+  listing?: string
 }
 
 interface JsonOutput {
@@ -98,6 +99,9 @@ export interface PushFlags {
 
   /** Require theme check to pass without errors before pushing. Warnings are allowed. */
   strict?: boolean
+
+  /** The listing preset to use for multi-preset themes. */
+  listing?: string
 }
 
 /**
@@ -148,6 +152,7 @@ export async function push(flags: PushFlags): Promise<void> {
     force,
     ignore: flags.ignore ?? [],
     only: flags.only ?? [],
+    listing: flags.listing,
   })
 }
 
@@ -160,7 +165,10 @@ export async function push(flags: PushFlags): Promise<void> {
  */
 async function executePush(theme: Theme, session: AdminSession, options: PushOptions) {
   const themeChecksums = await fetchChecksums(theme.id, session)
-  const themeFileSystem = mountThemeFileSystem(options.path, {filters: options})
+  const themeFileSystem = mountThemeFileSystem(options.path, {
+    filters: options,
+    listing: options.listing,
+  })
 
   const {uploadResults, renderThemeSyncProgress} = await uploadTheme(
     theme,
diff --git a/packages/theme/src/cli/utilities/theme-fs.test.ts b/packages/theme/src/cli/utilities/theme-fs.test.ts
diff --git a/packages/theme/src/cli/utilities/theme-fs.ts b/packages/theme/src/cli/utilities/theme-fs.ts
diff --git a/packages/theme/src/cli/utilities/theme-listing.test.ts b/packages/theme/src/cli/utilities/theme-listing.test.ts
diff --git a/packages/theme/src/cli/utilities/theme-listing.ts b/packages/theme/src/cli/utilities/theme-listing.ts
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml

Original file line number	Diff line number	Diff line change
`@@ -27,8 +27,9 @@ export type ThemeFSEventPayload<T extends ThemeFSEventName = 'add'> = (ThemeFSEv`
`27`	`27`
`28`	`28`	`export interface ThemeFileSystemOptions {`
`29`	`29`	`filters?: {ignore?: string[]; only?: string[]}`
`30`		`- notify?: string`
	`30`	`+ listing?: string`
`31`	`31`	`noDelete?: boolean`
	`32`	`+ notify?: string`
`32`	`33`	`}`
`33`	`34`
`34`	`35`	`/**`