Skip to content

Add typed JSON output to theme preview #8645

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
gonzaloriestra wants to merge 5 commits into from
+659 −167
Open

Add typed JSON output to theme preview #8645

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
1945bb0
Add typed JSON output to theme preview
gonzaloriestra Sep 24, 2026
bd1ea8f
Normalize theme preview JSON and await browser diagnostics
gonzaloriestra Oct 6, 2026
6fff4c3
Refresh theme preview JSON schema documentation
gonzaloriestra Oct 6, 2026
9c74c3c
Refresh generated theme preview command docs
gonzaloriestra Oct 6, 2026
54365d9
Load required preview values from theme environments
gonzaloriestra Oct 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/theme-preview-json-contract.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
'@shopify/cli': major
---

Return theme preview JSON as a strict `preview` resource with an opaque string `id` and retain every requested environment.
22 changes: 12 additions & 10 deletions docs-shopify.dev/generated/generated_docs_data_v2.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9630,15 +9630,6 @@
"isOptional": true,
"environmentValue": "SHOPIFY_FLAG_AUTH_ALIAS"
},
{
"filePath": "docs-shopify.dev/commands/interfaces/theme-preview.interface.ts",
"syntaxKind": "PropertySignature",
"name": "--json",
"value": "''",
"description": "Output the preview URL and identifier as JSON.",
"isOptional": true,
"environmentValue": "SHOPIFY_FLAG_JSON"
},
{
"filePath": "docs-shopify.dev/commands/interfaces/theme-preview.interface.ts",
"syntaxKind": "PropertySignature",
Expand Down Expand Up @@ -9681,6 +9672,7 @@
"name": "--overrides <value>",
"value": "string",
"description": "Path to a JSON overrides file.",
"isOptional": true,
"environmentValue": "SHOPIFY_FLAG_OVERRIDES"
},
{
Expand Down Expand Up @@ -9728,6 +9720,15 @@
"isOptional": true,
"environmentValue": "SHOPIFY_FLAG_ENVIRONMENT"
},
{
"filePath": "docs-shopify.dev/commands/interfaces/theme-preview.interface.ts",
"syntaxKind": "PropertySignature",
"name": "-j, --json",
"value": "''",
"description": "Output the preview URL and identifier as JSON.",
"isOptional": true,
"environmentValue": "SHOPIFY_FLAG_JSON"
},
{
"filePath": "docs-shopify.dev/commands/interfaces/theme-preview.interface.ts",
"syntaxKind": "PropertySignature",
Expand All @@ -9743,10 +9744,11 @@
"name": "-t, --theme <value>",
"value": "string",
"description": "Theme ID or name of the remote theme.",
"isOptional": true,
"environmentValue": "SHOPIFY_FLAG_THEME_ID"
}
],
"value": "export interface themepreview {\n /**\n * Alias of the Shopify account to use for authentication.\n * @environment SHOPIFY_FLAG_AUTH_ALIAS\n */\n '--auth-alias <value>'?: string\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 * Output the preview URL and identifier as JSON.\n * @environment SHOPIFY_FLAG_JSON\n */\n '--json'?: ''\n\n /**\n * Print the command's JSON schemas.\n * @environment SHOPIFY_FLAG_JSON_SCHEMA\n */\n '--json-schema'?: ''\n\n /**\n * Disable color output.\n * @environment SHOPIFY_FLAG_NO_COLOR\n */\n '--no-color'?: ''\n\n /**\n * Disable interactive prompts and browser authentication.\n * @environment SHOPIFY_FLAG_NO_INPUT\n */\n '--no-input'?: ''\n\n /**\n * Automatically launch the theme preview in your default web browser.\n * @environment SHOPIFY_FLAG_OPEN\n */\n '--open'?: ''\n\n /**\n * Path to a JSON overrides file.\n * @environment SHOPIFY_FLAG_OVERRIDES\n */\n '--overrides <value>': string\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 * An existing preview identifier to update instead of creating a new preview.\n * @environment SHOPIFY_FLAG_PREVIEW_ID\n */\n '--preview-id <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 * Theme ID or name of the remote theme.\n * @environment SHOPIFY_FLAG_THEME_ID\n */\n '-t, --theme <value>': string\n\n /**\n * Increase the verbosity of the output. May include sensitive data.\n * @environment SHOPIFY_FLAG_VERBOSE\n */\n '--verbose'?: ''\n}"
"value": "export interface themepreview {\n /**\n * Alias of the Shopify account to use for authentication.\n * @environment SHOPIFY_FLAG_AUTH_ALIAS\n */\n '--auth-alias <value>'?: string\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 * Output the preview URL and identifier as JSON.\n * @environment SHOPIFY_FLAG_JSON\n */\n '-j, --json'?: ''\n\n /**\n * Print the command's JSON schemas.\n * @environment SHOPIFY_FLAG_JSON_SCHEMA\n */\n '--json-schema'?: ''\n\n /**\n * Disable color output.\n * @environment SHOPIFY_FLAG_NO_COLOR\n */\n '--no-color'?: ''\n\n /**\n * Disable interactive prompts and browser authentication.\n * @environment SHOPIFY_FLAG_NO_INPUT\n */\n '--no-input'?: ''\n\n /**\n * Automatically launch the theme preview in your default web browser.\n * @environment SHOPIFY_FLAG_OPEN\n */\n '--open'?: ''\n\n /**\n * Path to a JSON overrides file.\n * @environment SHOPIFY_FLAG_OVERRIDES\n */\n '--overrides <value>'?: string\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 * An existing preview identifier to update instead of creating a new preview.\n * @environment SHOPIFY_FLAG_PREVIEW_ID\n */\n '--preview-id <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 * Theme ID or name of the remote theme.\n * @environment SHOPIFY_FLAG_THEME_ID\n */\n '-t, --theme <value>'?: string\n\n /**\n * Increase the verbosity of the output. May include sensitive data.\n * @environment SHOPIFY_FLAG_VERBOSE\n */\n '--verbose'?: ''\n}"
}
},
"themeprofile": {
Expand Down
279 changes: 271 additions & 8 deletions packages/cli/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12785,32 +12785,32 @@ Applies JSON overrides to a theme and returns a preview URL.

```
USAGE
$ shopify theme preview --overrides <value> -t <value> [--auth-alias <value>] [-e <value>...] [--json]
[--json-schema] [--no-color] [--no-input] [--open] [--password <value>] [--path <value>] [--preview-id <value>] [-s
$ shopify theme preview [--auth-alias <value>] [-e <value>...] [-j] [--json-schema] [--no-color] [--no-input]
[--open] [--overrides <value>] [--password <value>] [--path <value>] [--preview-id <value>] [-s <value>] [-t
<value>] [--verbose]

FLAGS
-e, --environment=<value>...
The environment to apply to the current command.
[env: SHOPIFY_FLAG_ENVIRONMENT]

-j, --json
Output the preview URL and identifier as JSON.
[env: SHOPIFY_FLAG_JSON]

-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).
[env: SHOPIFY_FLAG_STORE]

-t, --theme=<value>
(required) Theme ID or name of the remote theme.
Theme ID or name of the remote theme.
[env: SHOPIFY_FLAG_THEME_ID]

--auth-alias=<value>
Alias of the Shopify account to use for authentication.
[env: SHOPIFY_FLAG_AUTH_ALIAS]

--json
Output the preview URL and identifier as JSON.
[env: SHOPIFY_FLAG_JSON]

--json-schema
Print the command's JSON schemas.
[env: SHOPIFY_FLAG_JSON_SCHEMA]
Expand All @@ -12828,7 +12828,7 @@ FLAGS
[env: SHOPIFY_FLAG_OPEN]

--overrides=<value>
(required) Path to a JSON overrides file.
Path to a JSON overrides file.
[env: SHOPIFY_FLAG_OVERRIDES]

--password=<value>
Expand All @@ -12854,6 +12854,269 @@ DESCRIPTION

The command returns a preview URL and a preview identifier. You can reuse the preview identifier with `--preview-id`
to update an existing preview instead of creating a new one.

Use `--json-schema` to print the result, error, and event schemas.

Output from `--json` conforms to the `ThemePreviewResult` schema.

```json
{
"anyOf": [
{
"$ref": "#/definitions/ThemeEnvironment/anyOf/0/properties/result"
},
{
"type": "object",
"properties": {
"environments": {
"type": "array",
"items": {
"$ref": "#/definitions/ThemeEnvironment"
}
}
},
"required": [
"environments"
],
"additionalProperties": false
}
],
"title": "ThemePreviewResult",
"definitions": {
"ThemePreview": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"description": "The opaque Storefront preview identifier, not a theme ID or Shopify GID."
},
"url": {
"type": "string",
"format": "uri"
}
},
"required": [
"id",
"url"
],
"additionalProperties": false
},
"ThemeEnvironment": {
"anyOf": [
{
"type": "object",
"properties": {
"environment": {
"type": "string"
},
"result": {
"anyOf": [
{
"type": "object",
"properties": {
"status": {
"type": "string",
"const": "success"
},
"preview": {
"$ref": "#/definitions/ThemePreview"
}
},
"required": [
"status",
"preview"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"status": {
"type": "string",
"const": "cancelled"
}
},
"required": [
"status"
],
"additionalProperties": false
}
]
}
},
"required": [
"environment",
"result"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"environment": {
"type": "string"
},
"error": {
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "abort"
},
"message": {
"type": "string"
},
"code": {
"type": "string",
"minLength": 1,
"description": "A stable error code, included only when known."
},
"tryMessage": {
"type": "string"
},
"nextSteps": {
"type": "array",
"items": {
"type": "string"
}
},
"customSections": {
"type": "array",
"items": {
"type": "object",
"properties": {
"title": {
"type": "string"
},
"body": {
"anyOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "array",
"items": {
"type": "string"
}
}
}
]
}
},
"required": [
"body"
],
"additionalProperties": false
}
},
"details": {
"description": "Selected domain details, preserving native API payloads such as GraphQL errors, extensions, and data."
}
},
"required": [
"type",
"message"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "bug"
},
"message": {
"$ref": "#/definitions/ThemeEnvironment/anyOf/1/properties/error/anyOf/0/properties/message"
},
"code": {
"$ref": "#/definitions/ThemeEnvironment/anyOf/1/properties/error/anyOf/0/properties/code"
},
"tryMessage": {
"$ref": "#/definitions/ThemeEnvironment/anyOf/1/properties/error/anyOf/0/properties/tryMessage"
},
"nextSteps": {
"$ref": "#/definitions/ThemeEnvironment/anyOf/1/properties/error/anyOf/0/properties/nextSteps"
},
"customSections": {
"$ref": "#/definitions/ThemeEnvironment/anyOf/1/properties/error/anyOf/0/properties/customSections"
},
"details": {
"$ref": "#/definitions/ThemeEnvironment/anyOf/1/properties/error/anyOf/0/properties/details"
},
"stack": {
"type": "string"
}
},
"required": [
"type",
"message"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "external"
},
"message": {
"$ref": "#/definitions/ThemeEnvironment/anyOf/1/properties/error/anyOf/0/properties/message"
},
"code": {
"$ref": "#/definitions/ThemeEnvironment/anyOf/1/properties/error/anyOf/0/properties/code"
},
"tryMessage": {
"$ref": "#/definitions/ThemeEnvironment/anyOf/1/properties/error/anyOf/0/properties/tryMessage"
},
"nextSteps": {
"$ref": "#/definitions/ThemeEnvironment/anyOf/1/properties/error/anyOf/0/properties/nextSteps"
},
"customSections": {
"$ref": "#/definitions/ThemeEnvironment/anyOf/1/properties/error/anyOf/0/properties/customSections"
},
"details": {
"$ref": "#/definitions/ThemeEnvironment/anyOf/1/properties/error/anyOf/0/properties/details"
},
"command": {
"type": "string"
},
"args": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"type",
"message",
"command",
"args"
],
"additionalProperties": false
}
]
}
},
"required": [
"environment",
"error"
],
"additionalProperties": false
}
]
}
},
"$schema": "http://json-schema.org/draft-07/schema#"
}
```
```

## `shopify theme profile`
Expand Down
Loading
Loading