[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?

Requires https://app.graphite.com/github/pr/shop/world/448726/Add-ThemePreviewController-to-support-Shopify-CLI-theme-previews

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	79.6%	14499/18214
🟡	Branches	73.94%	7195/9731
🟡	Functions	79.78%	3693/4629
🟡	Lines	79.96%	13710/17146

Test suite run success

3731 tests passing in 1443 suites.

Report generated by 🧪jest coverage report action from fedff6f

…ews uisng an override json

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.

github-actions · 2026-02-25T18:17:34Z

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[];

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).

Add graphql to storefront scopes

8fa4e66

dengjeffrey force-pushed the jd/quick-preview branch 3 times, most recently from 2adb0f2 to 06454b5 Compare February 24, 2026 23:20

dengjeffrey added 3 commits February 24, 2026 18:47

Add functionality to POST overrides for a theme preview

37cb670

Add source and preview-id flags to theme dev to allow for theme previ…

f837ceb

…ews uisng an override json

Update README and manifests for new source flag in theme dev

f131575

dengjeffrey force-pushed the jd/quick-preview branch 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

Add analytics and metrics to track performance for theme overrides

2fe742b

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

Add changeset for the new --source and --preview-id flags on theme dev

fedff6f

karreiro reviewed Feb 26, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[Feature] Add Theme previews via JSON#6890

[Feature] Add Theme previews via JSON#6890
dengjeffrey wants to merge 6 commits intomainfrom
jd/quick-preview

dengjeffrey commented Feb 24, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Feb 24, 2026 •

edited

Loading

Uh oh!

dengjeffrey Feb 25, 2026

Uh oh!

This comment has been minimized.

github-actions bot commented Feb 25, 2026

Uh oh!

karreiro left a comment

Uh oh!

karreiro Feb 26, 2026

Uh oh!

karreiro Feb 26, 2026

Uh oh!

karreiro Feb 26, 2026

Uh oh!

karreiro Feb 26, 2026

Uh oh!

karreiro Feb 26, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

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!

dengjeffrey Feb 25, 2026

Choose a reason for hiding this comment

Uh oh!

This comment has been minimized.

github-actions bot commented Feb 25, 2026

Differences in type declarations

New type declarations

Existing type declarations

Uh oh!

karreiro left a comment

Choose a reason for hiding this comment

Uh oh!

karreiro Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

karreiro Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

karreiro Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

karreiro Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

karreiro Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

dengjeffrey commented Feb 24, 2026 •

edited

Loading

github-actions bot commented Feb 24, 2026 •

edited

Loading