---
title: theme preview JSON overrides file
description: >-
  Reference for the JSON overrides file format accepted by the --overrides flag
  of shopify theme preview.
source_url:
  html: >-
    https://shopify.dev/docs/storefronts/themes/tools/cli/theme-preview-overrides
  md: >-
    https://shopify.dev/docs/storefronts/themes/tools/cli/theme-preview-overrides.md
api_name: liquid
---

# `theme preview` JSON overrides file

The `--overrides` flag of [`shopify theme preview`](https://shopify.dev/docs/api/shopify-cli/theme/theme-preview) accepts a path to a JSON overrides file. When a JSON file is provided, its contents are applied as virtual, in-memory overrides on top of the remote theme. No files are permanently changed on Shopify.

***

## Top-level structure

```json
{
  "metadata": {
    "version": "0.1.0"
  },
  "theme_changes": { ... }
}
```

| Property | Type | Description |
| - | - | - |
| `metadata` | object | Optional metadata about the source payload. |
| `metadata.version` | string | A version identifier for the payload. |
| `theme_changes` | object | The set of changes to apply. Each key is either a theme file path or a special top-level key described below. |

***

## Operations

Each entry inside `theme_changes` is keyed by a theme file path (for example, `templates/index.json`) and contains one of the following operation objects. You can also provide a top-level `diffs` key to supply a full `git diff` output.

### `source`: full file replacement

Replaces the entire contents of a file with the given string. If the file doesn't exist in the theme, a virtual file is created. Virtual files behave like any other file in the theme — other overrides and existing theme files can reference or include them. For example, you can create a virtual snippet with `source` and then render it from another override using `{% render 'my-snippet' %}`.

```json
{
  "theme_changes": {
    "templates/product.liquid": {
      "source": "<div>{{ product.title }}</div>"
    }
  }
}
```

| Property | Type | Description |
| - | - | - |
| `source` | string | The complete new content for the file. |

### `merge`: deep merge into JSON files

Deep-merges the provided object into a JSON theme file. This is intended for settings and locale files.

```json
{
  "theme_changes": {
    "templates/index.json": {
      "merge": {
        "current": {
          "product_image_size": "large"
        }
      }
    }
  }
}
```

| Property | Type | Description |
| - | - | - |
| `merge` | object | A partial JSON object that's deep-merged into the existing file. |

### `diffs`: per-file patch string

Applies a diff (patch) to a single file. Both normal diff format (`diff`) and unified diff format (`diff -u` / `git diff`) are accepted and auto-detected.

```json
{
  "theme_changes": {
    "templates/price.liquid": {
      "diffs": "3a4,6\n {% render 'sale-badge' %}\n"
    }
  }
}
```

| Property | Type | Description |
| - | - | - |
| `diffs` | string | A diff string in normal or unified format to apply to the file. |

### Top-level `diffs`: full `git diff` output

Paste an entire `git diff` output as the value of a top-level `diffs` key. Shopify CLI extracts individual file paths from the `+++ b/<path>` lines and strips leading directory prefixes until a valid theme path is matched. This means you can copy the output of `git diff` from Dawn, Horizon, or any theme fork and send it directly.

**Note:**

A top-level `diffs` key can't be used in the same `theme_changes` object as per-file `diffs` operations.

```json
{
  "theme_changes": {
    "diffs": "diff --git a/templates/index.json b/templates/index.json\n..."
  }
}
```

| Property | Type | Description |
| - | - | - |
| `diffs` | string | A complete `git diff` output. File paths are inferred from `+++ b/<path>` lines. Can't be combined with per-file `diffs` operations. |

***

## Complete example

The following example uses per-file operations (`source`, `merge`, and per-file `diffs`):

```json
{
  "metadata": {
    "version": "0.1.0"
  },
  "theme_changes": {
    "templates/index.json": {
      "merge": {
        "current": {
          "product_image_size": "large"
        }
      }
    },
    "templates/product.liquid": {
      "source": "<div>{{ product.title }}</div>"
    },
    "templates/price.liquid": {
      "diffs": "3a4,6\n {% render 'sale-badge' %}\n"
    }
  }
}
```

***

## Related

* [`shopify theme preview`](https://shopify.dev/docs/api/shopify-cli/theme/theme-preview)

***