[Feature] Add Theme previews via JSON by dengjeffrey · Pull Request #6890 · Shopify/cli

dengjeffrey · 2026-02-24T18:54:24Z

WHY are these changes introduced?

Resolves https://github.com/shop/issues-growth-activation/issues/1902

WHAT is this pull request doing?

Adds additional flags to theme dev to support temporarily overriding a theme via JSON and being able to preview it

More internal context: https://docs.google.com/document/d/13sa0iRs_DSgyPHbx9IIF64rvhh_KZCDLfJgwpSIxP4A/edit?usp=sharing

--source allows for either a theme directory or a JSON. We will document the JSON schema on shopify.dev
--preview-id specifies an existing preview session to be updated with the JSON value in source

How to test your changes?

https://docs.google.com/document/d/13sa0iRs_DSgyPHbx9IIF64rvhh_KZCDLfJgwpSIxP4A/edit?tab=t.0#bookmark=id.rhjcmeq18hn7

Post-release steps

[] Add documentation on shopify.dev

Measuring impact

How do we know this change was effective? Please choose one:

n/a - this doesn't need measurement, e.g. a linting rule or a bug-fix
Existing analytics will cater for this addition
PR includes analytics changes to measure impact

Checklist

I've considered possible cross-platform impacts (Mac, Linux, Windows)
I've considered possible documentation changes

github-actions · 2026-02-24T19:01:05Z

Coverage report

St.^❔	Category	Percentage	Covered / Total
🟡	Statements	78.94%	14578/18468
🟡	Branches	73.24%	7251/9900
🟡	Functions	79.09%	3699/4677
🟡	Lines	79.28%	13785/17387

Test suite run success

3807 tests passing in 1457 suites.

Report generated by 🧪jest coverage report action from 86501e1

dengjeffrey · 2026-02-25T17:56:40Z

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

+        devFlags.path = resolvedSource
+      } else {
+        recordEvent('theme-command:dev:override-session')
+        await createOverrideDevSession(resolvedSource, devFlags, adminSession)


Using this same pattern here to "create" a dev session even if we don't have a long running process yet. This will make it trivial to add hot reloading.

karreiro

Thank you for this PR, @dengjeffrey!

This feature is going to be really useful for developers — it feels like something they could use as a building block to create interesting things on top of.

I've left some comments. Once we tophat this, I'll revisit the review, try things end-to-end, and approve.

Thanks again!

karreiro · 2026-02-26T13:42:25Z

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

+  }
+
+  const fileContent = await readFile(options.overrideJson)
+  const overrides = JSON.parse(fileContent) as ThemeOverrides


May we handle JSON parser errors here?

karreiro · 2026-02-26T13:48:14Z

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

+      description:
+        'The source for the dev server. Can be a directory or a JSON overrides file. When a directory is provided, it is used as the theme directory. When a JSON file is provided, overrides are applied to the theme specified by --theme.',
+      env: 'SHOPIFY_FLAG_SOURCE',
+    }),


While reviewing the flags for this command, I noticed we already have --path, so there are two options:

When --source is empty, document that the command uses the file system as the source and relies on --path.

Remove --source in favor of --path, allowing you to pass either a --path or an override file as a parameter.

I think option 2 is the cleaner approach. What do you think?

karreiro · 2026-02-26T13:49:34Z

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

+    'preview-id': Flags.string({
+      description:
+        'An existing preview identifier to update instead of creating a new preview. Used with --source when pointing to a JSON overrides file.',
+      env: 'SHOPIFY_FLAG_PREVIEW_ID',
+    }),


When reading this as a user, I immediately wondered how I would get a --preview-id. I think we could mention that --preview-id is an optional field that you may get from previous preview runs.

karreiro · 2026-02-26T13:50:58Z

packages/cli-kit/src/private/node/session.ts

 /**
 * A scope supported by the Storefront Renderer API.
 */
-export type StorefrontRendererScope = 'devtools'


Deferring review of this line to the @Shopify/app-inner-loop team, as they implemented the storefront renderer scopes and have more context on this area.

karreiro · 2026-02-26T14:00:24Z

packages/theme/src/cli/utilities/theme-previews/preview.ts

+  overridesContent,
+}: CreateThemePreviewOptions): Promise<ThemePreviewResult> {
+  recordTiming('theme-preview:create')
+  const baseUrl = buildBaseStorefrontUrl(session)


Did you have a chance to tophat this using the Theme Access app?

I wonder if changes will be required there to support the new API call. I think it should work out of the box, but worth double-checking (specially from scopes perspective).

Will do! Now that everything required to test this has been merged, I will give it a go tomorrow.

binks-code-reviewer · 2026-02-26T19:54:07Z

packages/theme/src/cli/utilities/theme-previews/preview.ts

+      ...defaultHeaders(),
+      Authorization: `Bearer ${storefrontToken}`,
+      'Content-Type': 'application/json',
+    },


Cookies are incorrectly spread into headers instead of being sent as a Cookie header

The code spreads cookie key/values directly into headers:

headers: { ...session.sessionCookies, ...defaultHeaders(), Authorization: `Bearer ${storefrontToken}`, 'Content-Type': 'application/json', }

If session.sessionCookies is shaped like { storefront_digest: '...', _shopify_essential: '...' }, this produces custom headers named storefront_digest and _shopify_essential rather than a valid Cookie header. Servers may ignore these, causing preview creation/update to fail with auth/session errors.

binks-code-reviewer · 2026-02-26T19:54:08Z

🤖 Code Review · #projects-dev-ai for questions
React with 👍/👎 or reply — all feedback helps improve the agent.

✅ Complete - No issues

📋 History

✅ 1 findings → ✅ 2 findings → ✅ No issues → ✅ No issues

binks-code-reviewer · 2026-02-26T20:38:42Z

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

+      recordEvent('theme-command:dev:override-session')
+      await createOverrideDevSession(devFlags.path, devFlags, adminSession)
+      return
+    }


--path non-directory values are treated as JSON mode (breaks existing usage when path is missing/invalid)

The command switches to override-preview mode whenever isDirectorySync(devFlags.path) is false:

if (!isDirectorySync(devFlags.path)) { recordEvent('theme-command:dev:override-session') await createOverrideDevSession(devFlags.path, devFlags, adminSession) return }

This will also be true for non-existent directories, non-JSON file paths, and possibly undefined/empty values depending on defaults. In those cases, the command incorrectly requires --theme and attempts JSON parsing, producing confusing errors instead of the existing “directory not found” / “not a theme directory” behavior.

binks-code-reviewer · 2026-02-26T20:38:43Z

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

+    metadata: {
+      ...existingMetadata,
+      theme_id: themeId,
+    },


constructOverrides may throw or behave unexpectedly if metadata is not an object

constructOverrides assumes overrides.metadata is object-like:

const existingMetadata = (overrides.metadata ?? {}) as ThemeOverrides // ... metadata: { ...existingMetadata, theme_id: themeId, }

If the override JSON has "metadata": "v1" or "metadata": [], spreading can throw or produce odd results (arrays spread into numeric keys).

isaacroldan · 2026-02-27T12:52:37Z

packages/cli-kit/src/private/node/session/scopes.ts

      return ['graphql', 'themes', 'collaborator']
    case 'storefront-renderer':
-      return ['devtools']
+      return ['devtools', 'graphql']


have you updated the identity app to support this? reach out to me in slack for more details if not.

isaacroldan · 2026-02-27T12:56:00Z

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

+    path: {
+      ...themeFlags.path,
+      description:
+        'The path for the dev server. It can be a directory or a JSON overrides file. When a directory is provided, it is used as the theme directory. When a JSON file is provided, overrides are applied to the theme specified by --theme. Defaults to the current working directory.',
+    } as typeof themeFlags.path,


path is a globally used flag and should keep its behaviour consistent over all commands (apps, theme...).
path means: execute the command in the given path instead of in the current directory.
It's not in globalFlags because not all commands are executed in a specific path, but maybe it should.

Anyway, I don't think we should change how path works in this specific command only. It'd be better to have a new flag

I'll move it out to an --overrides flag

…eme previews uisng an override json

…eme dev

github-actions · 2026-02-27T23:52:54Z

Differences in type declarations

We detected differences in the type declarations generated by Typescript for this branch compared to the baseline ('main' branch). Please, review them to ensure they are backward-compatible. Here are some important things to keep in mind:

Some seemingly private modules might be re-exported through public modules.
If the branch is behind main you might see odd diffs, rebase main into this branch.

New type declarations

We found no new type declarations in this PR

Existing type declarations

packages/cli-kit/dist/private/node/session.d.ts

@@ -31,7 +31,7 @@ interface AppManagementAPIOauthOptions {
 /**
  * A scope supported by the Storefront Renderer API.
  */
-export type StorefrontRendererScope = 'devtools';
+export type StorefrontRendererScope = 'devtools' | 'graphql';
 interface StorefrontRendererAPIOAuthOptions {
     /** List of scopes to request permissions for. */
     scopes: StorefrontRendererScope[];

dengjeffrey force-pushed the jd/quick-preview branch 4 times, most recently from 06454b5 to f131575 Compare February 25, 2026 02:47

dengjeffrey changed the title ~~Jd/quick preview~~ [Feature] Add Theme previews via JSON Feb 25, 2026

dengjeffrey commented Feb 25, 2026

View reviewed changes

dengjeffrey requested a review from karreiro February 25, 2026 17:57

dengjeffrey marked this pull request as ready for review February 25, 2026 18:03

dengjeffrey requested review from a team as code owners February 25, 2026 18:03

This comment has been minimized.

Sign in to view

karreiro reviewed Feb 26, 2026

View reviewed changes

dengjeffrey force-pushed the jd/quick-preview branch from fedff6f to d9a45af Compare February 26, 2026 19:04

binks-code-reviewer bot reviewed Feb 26, 2026

View reviewed changes

dengjeffrey force-pushed the jd/quick-preview branch from 8d7b77c to d94cecb Compare February 26, 2026 20:05

binks-code-reviewer bot reviewed Feb 26, 2026

View reviewed changes

dengjeffrey requested a review from karreiro February 27, 2026 02:23

isaacroldan reviewed Feb 27, 2026

View reviewed changes

dengjeffrey force-pushed the jd/quick-preview branch from d94cecb to 22537f4 Compare February 27, 2026 22:43

dengjeffrey added 7 commits February 27, 2026 14:44

Add graphql to storefront scopes

5787c07

Add functionality to POST overrides for a theme preview

f082fff

Add preview-id flag and update path flag on theme dev to allow for th…

cbe7200

…eme previews uisng an override json

Update README and manifests for new flag changes in theme dev

a7b6722

Add analytics and metrics to track performance for theme overrides

448ada0

Add changeset for the updated --path and new --preview-id flags on th…

2dda43d

…eme dev

Updated dev docs

71aa578

dengjeffrey force-pushed the jd/quick-preview branch 2 times, most recently from 65a7479 to c9446c1 Compare February 27, 2026 23:14

dengjeffrey requested a review from isaacroldan February 27, 2026 23:19

Change override flag from --path to --override

86501e1

dengjeffrey force-pushed the jd/quick-preview branch from c9446c1 to 86501e1 Compare February 27, 2026 23:51

Conversation

dengjeffrey commented Feb 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

WHY are these changes introduced?

WHAT is this pull request doing?

How to test your changes?

Post-release steps

Measuring impact

Checklist

Uh oh!

github-actions bot commented Feb 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Coverage report

Test suite run success

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This comment has been minimized.

karreiro left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

binks-code-reviewer bot Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

binks-code-reviewer bot commented Feb 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

binks-code-reviewer bot Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

binks-code-reviewer bot Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Feb 27, 2026

Differences in type declarations

New type declarations

Existing type declarations

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

dengjeffrey commented Feb 24, 2026 •

edited

Loading

github-actions bot commented Feb 24, 2026 •

edited

Loading

binks-code-reviewer bot commented Feb 26, 2026 •

edited

Loading