Notify users when Liquid files are rewritten remotely

aswamy · aswamy · commit fa04b0c6424d · 2026-01-02T16:15:26.000-05:00
diff --git a/.changeset/sour-boats-grab.md b/.changeset/sour-boats-grab.md
@@ -0,0 +1,6 @@
+---
+'@shopify/cli-kit': minor
+'@shopify/theme': minor
+---
+
+Add ability to notify user when Liquid files are rewritten remotely
diff --git a/packages/cli-kit/src/cli/api/graphql/admin/generated/theme_files_upsert.ts b/packages/cli-kit/src/cli/api/graphql/admin/generated/theme_files_upsert.ts
@@ -10,7 +10,7 @@ export type ThemeFilesUpsertMutationVariables = Types.Exact<{
 
 export type ThemeFilesUpsertMutation = {
   themeFilesUpsert?: {
-    upsertedThemeFiles?: {filename: string}[] | null
+    upsertedThemeFiles?: {filename: string; checksumMd5?: string | null}[] | null
     userErrors: {filename?: string | null; message: string}[]
   } | null
 }
@@ -71,6 +71,7 @@ export const ThemeFilesUpsert = {
                     kind: 'SelectionSet',
                     selections: [
                       {kind: 'Field', name: {kind: 'Name', value: 'filename'}},
+                      {kind: 'Field', name: {kind: 'Name', value: 'checksumMd5'}},
                       {kind: 'Field', name: {kind: 'Name', value: '__typename'}},
                     ],
                   },
diff --git a/packages/cli-kit/src/cli/api/graphql/admin/mutations/theme_files_upsert.graphql b/packages/cli-kit/src/cli/api/graphql/admin/mutations/theme_files_upsert.graphql
@@ -2,6 +2,7 @@ mutation themeFilesUpsert($files: [OnlineStoreThemeFilesUpsertFileInput!]!, $the
   themeFilesUpsert(files: $files, themeId: $themeId) {
     upsertedThemeFiles {
       filename
+      checksumMd5
     }
     userErrors {
       filename
diff --git a/packages/cli-kit/src/public/node/themes/api.test.ts b/packages/cli-kit/src/public/node/themes/api.test.ts
@@ -553,11 +553,19 @@ describe('bulkUploadThemeAssets', async () => {
         key: 'snippets/product-variant-picker.liquid',
         success: true,
         operation: Operation.Upload,
+        asset: {
+          checksum: '',
+          key: 'snippets/product-variant-picker.liquid',
+        },
       },
       {
         key: 'templates/404.json',
         success: true,
         operation: Operation.Upload,
+        asset: {
+          checksum: '',
+          key: 'templates/404.json',
+        },
       },
     ])
   })
diff --git a/packages/cli-kit/src/public/node/themes/api.ts b/packages/cli-kit/src/public/node/themes/api.ts
@@ -316,6 +316,10 @@ function processUploadResults(uploadResults: ThemeFilesUpsertMutation): Result[]
       key: file.filename,
       success: true,
       operation: Operation.Upload,
+      asset: {
+        key: file.filename,
+        checksum: file.checksumMd5 ?? '',
+      },
     })
   })
 
diff --git a/packages/theme/src/cli/services/dev.ts b/packages/theme/src/cli/services/dev.ts
@@ -120,7 +120,10 @@ export async function dev(options: DevOptions) {
     },
   }
 
-  const {serverStart, renderDevSetupProgress, backgroundJobPromise} = setupDevServer(options.theme, ctx)
+  const {serverStart, renderDevSetupProgress, backgroundJobPromise, syncRewrittenFilesPromise} = setupDevServer(
+    options.theme,
+    ctx,
+  )
 
   readline.emitKeypressEvents(process.stdin)
   if (process.stdin.isTTY) {
@@ -140,6 +143,7 @@ export async function dev(options: DevOptions) {
           openURLSafely(urls.local, 'development server')
         }
       }),
+    syncRewrittenFilesPromise(),
   ])
 }
 
diff --git a/packages/theme/src/cli/services/push.test.ts b/packages/theme/src/cli/services/push.test.ts
@@ -49,6 +49,7 @@ describe('push', () => {
       workPromise: Promise.resolve(),
       uploadResults: new Map(),
       renderThemeSyncProgress: () => Promise.resolve(),
+      syncRewrittenFilesPromise: Promise.resolve(),
     })
     vi.mocked(ensureThemeStore).mockReturnValue('example.myshopify.com')
     vi.mocked(ensureAuthenticatedThemes).mockResolvedValue(adminSession)
@@ -93,6 +94,7 @@ describe('push', () => {
       workPromise: Promise.resolve(),
       uploadResults,
       renderThemeSyncProgress: () => Promise.resolve(),
+      syncRewrittenFilesPromise: Promise.resolve(),
     })
 
     // When
diff --git a/packages/theme/src/cli/services/push.ts b/packages/theme/src/cli/services/push.ts
@@ -205,16 +205,20 @@ async function executePush(
   const themeFileSystem = mountThemeFileSystem(options.path, {filters: options})
   recordTiming('theme-service:push:file-system')
 
-  const {uploadResults, renderThemeSyncProgress} = uploadTheme(
+  const {uploadResults, renderThemeSyncProgress, syncRewrittenFilesPromise} = uploadTheme(
     theme,
     session,
     themeChecksums,
     themeFileSystem,
-    options,
+    {
+      ...options,
+      handleRewrittenFiles: 'warn',
+    },
     context,
   )
 
   await renderThemeSyncProgress()
+  await syncRewrittenFilesPromise
 
   if (options.publish) {
     await themePublish(theme.id, session)
diff --git a/packages/theme/src/cli/utilities/asset-checksum.ts b/packages/theme/src/cli/utilities/asset-checksum.ts
@@ -2,24 +2,34 @@ import {isTextFile} from './theme-fs.js'
 import {Checksum} from '@shopify/cli-kit/node/themes/types'
 import {fileHash} from '@shopify/cli-kit/node/crypto'
 
-export function calculateChecksum(fileKey: string, fileContent: string | Buffer | undefined) {
+export function calculateChecksum(
+  fileKey: string,
+  fileContent: string | Buffer | undefined,
+  options?: {replaceNewlines: boolean},
+) {
   if (!fileContent) {
     return ''
   }
 
-  if (Buffer.isBuffer(fileContent)) {
-    return md5(fileContent)
+  let filteredContent = fileContent
+
+  if (options?.replaceNewlines) {
+    filteredContent = fileContent.toString().replace(/\r\n/g, '\n')
+  }
+
+  if (Buffer.isBuffer(filteredContent)) {
+    return md5(filteredContent)
   }
 
   /**
    * Settings data files are always minified before persistence, so their
    * checksum calculation accounts for that minification.
    */
   if (isSettingsData(fileKey)) {
-    return minifiedJSONFileChecksum(fileContent)
+    return minifiedJSONFileChecksum(filteredContent)
   }
 
-  return regularFileChecksum(fileKey, fileContent)
+  return regularFileChecksum(fileKey, filteredContent)
 }
 
 function minifiedJSONFileChecksum(fileContent: string) {
diff --git a/packages/theme/src/cli/utilities/theme-downloader.ts b/packages/theme/src/cli/utilities/theme-downloader.ts
@@ -86,7 +86,12 @@ function buildDownloadTasks(
   return batches
 }
 
-async function downloadFiles(theme: Theme, fileSystem: ThemeFileSystem, filenames: string[], session: AdminSession) {
+export async function downloadFiles(
+  theme: Theme,
+  fileSystem: ThemeFileSystem,
+  filenames: string[],
+  session: AdminSession,
+) {
   const assets = await fetchThemeAssets(theme.id, filenames, session)
   if (!assets) return
 
diff --git a/packages/theme/src/cli/utilities/theme-environment/theme-environment.test.ts b/packages/theme/src/cli/utilities/theme-environment/theme-environment.test.ts
@@ -35,7 +35,12 @@ vi.mock('../theme-uploader.js', async () => {
 })
 beforeEach(() => {
   vi.mocked(uploadTheme).mockImplementation(() => {
-    return {workPromise: Promise.resolve(), uploadResults: new Map(), renderThemeSyncProgress: () => Promise.resolve()}
+    return {
+      workPromise: Promise.resolve(),
+      uploadResults: new Map(),
+      renderThemeSyncProgress: () => Promise.resolve(),
+      syncRewrittenFilesPromise: Promise.resolve(),
+    }
   })
 })
 
@@ -127,6 +132,7 @@ describe('setupDevServer', () => {
       nodelete: true,
       deferPartialWork: true,
       backgroundWorkCatch: expect.any(Function),
+      handleRewrittenFiles: 'fix',
     })
   })
 
@@ -185,6 +191,7 @@ describe('setupDevServer', () => {
       nodelete: true,
       deferPartialWork: true,
       backgroundWorkCatch: expect.any(Function),
+      handleRewrittenFiles: 'fix',
     })
   })
 
diff --git a/packages/theme/src/cli/utilities/theme-environment/theme-environment.ts b/packages/theme/src/cli/utilities/theme-environment/theme-environment.ts
@@ -29,6 +29,7 @@ export function setupDevServer(theme: Theme, ctx: DevServerContext) {
     dispatchEvent: server.dispatch,
     renderDevSetupProgress: envSetup.renderProgress,
     backgroundJobPromise,
+    syncRewrittenFilesPromise: () => envSetup.syncRewrittenFilesPromise,
   }
 }
 
@@ -58,6 +59,7 @@ function ensureThemeEnvironmentSetup(
       nodelete: ctx.options.noDelete,
       deferPartialWork: true,
       backgroundWorkCatch: abort,
+      handleRewrittenFiles: 'fix',
     })
   })
 
@@ -82,6 +84,7 @@ function ensureThemeEnvironmentSetup(
 
       await renderThemeSyncProgress()
     },
+    syncRewrittenFilesPromise: uploadPromise.then((result) => result.syncRewrittenFilesPromise).catch(abort),
   }
 }
 
diff --git a/packages/theme/src/cli/utilities/theme-ext-environment/theme-ext-fs.ts b/packages/theme/src/cli/utilities/theme-ext-environment/theme-ext-fs.ts
@@ -31,7 +31,7 @@ export function mountThemeExtensionFileSystem(root: string): ThemeExtensionFileS
 
   const read = async (key: string) => {
     const fileContent = await readThemeFile(root, key)
-    const checksum = calculateChecksum(key, fileContent)
+    const checksum = calculateChecksum(key, fileContent, {replaceNewlines: true})
     const value = typeof fileContent === 'string' ? fileContent : ''
     const attachment = Buffer.isBuffer(fileContent) ? fileContent.toString('base64') : ''
 
diff --git a/packages/theme/src/cli/utilities/theme-fs.test.ts b/packages/theme/src/cli/utilities/theme-fs.test.ts
@@ -39,6 +39,12 @@ beforeEach(async () => {
   vi.mocked(applyIgnoreFilters).mockImplementation(realModule.applyIgnoreFilters)
 })
 
+interface FileContent {
+  value?: string
+  attachment?: string
+  checksum: string
+}
+
 describe('theme-fs', () => {
   const locationOfThisFile = dirname(fileURLToPath(import.meta.url))
 
@@ -700,6 +706,7 @@ describe('theme-fs', () => {
     const adminSession = {token: 'token'} as AdminSession
     let unsyncedFileKeys: Set<string>
     let uploadErrors: Map<string, string[]>
+    const write = vi.fn()
 
     beforeEach(() => {
       unsyncedFileKeys = new Set([fileKey])
@@ -710,45 +717,79 @@ describe('theme-fs', () => {
     test('returns false if file is not in unsyncedFileKeys', async () => {
       // Given
       unsyncedFileKeys = new Set()
-      const handler = handleSyncUpdate(unsyncedFileKeys, uploadErrors, fileKey, themeId, adminSession)
+      const handler = handleSyncUpdate(unsyncedFileKeys, uploadErrors, fileKey, themeId, adminSession, write)
 
       // When
-      const result = await handler({value: 'content'})
+      const result = await handler({value: 'content', checksum: '123'})
 
       // Then
       expect(result).toBe(false)
       expect(bulkUploadThemeAssets).not.toHaveBeenCalled()
       expect(triggerBrowserFullReload).not.toHaveBeenCalled()
     })
 
-    Object.entries({
-      text: {value: 'content'},
-      image: {attachment: 'content'},
-    }).forEach(([fileType, fileContent]) => {
-      test(`uploads ${fileType} file and returns true on successful sync`, async () => {
-        // Given
-        vi.mocked(bulkUploadThemeAssets).mockResolvedValue([
-          {
-            key: fileKey,
-            success: true,
-            operation: Operation.Upload,
-          },
-        ])
-        const handler = handleSyncUpdate(unsyncedFileKeys, uploadErrors, fileKey, themeId, adminSession)
-
-        // When
-        const result = await handler(fileContent)
-
-        // Then
-        expect(result).toBe(true)
-        expect(bulkUploadThemeAssets).toHaveBeenCalledWith(
-          Number(themeId),
-          [{key: fileKey, ...fileContent}],
-          adminSession,
-        )
-        expect(unsyncedFileKeys.has(fileKey)).toBe(false)
-        expect(triggerBrowserFullReload).not.toHaveBeenCalled()
-      })
+    test.each<[string, FileContent]>([
+      ['text', {value: 'content', checksum: '123'}],
+      ['image', {attachment: 'content', checksum: '123'}],
+    ])('uploads %s file and returns true on successful sync', async (_fileType, fileContent) => {
+      // Given
+      vi.mocked(bulkUploadThemeAssets).mockResolvedValue([
+        {
+          key: fileKey,
+          success: true,
+          operation: Operation.Upload,
+        },
+      ])
+      vi.mocked(fetchThemeAssets).mockResolvedValue([])
+      const handler = handleSyncUpdate(unsyncedFileKeys, uploadErrors, fileKey, themeId, adminSession, write)
+
+      // When
+      const result = await handler(fileContent)
+
+      // Then
+      expect(result).toBe(true)
+      expect(bulkUploadThemeAssets).toHaveBeenCalledWith(
+        Number(themeId),
+        [{key: fileKey, ...fileContent}],
+        adminSession,
+      )
+      expect(unsyncedFileKeys.has(fileKey)).toBe(false)
+      expect(triggerBrowserFullReload).not.toHaveBeenCalled()
+    })
+
+    test('updates the file locally if an unsyncedFile is pushed up but rewritten remotely', async () => {
+      const liquidFileKey = 'snippets/new-file.liquid'
+      const originalFileContent = {
+        key: liquidFileKey,
+        checksum: 'checksum',
+        value: 'content',
+      }
+      const rewrittenFileContent = {
+        key: liquidFileKey,
+        checksum: 'rewritten-checksum',
+        value: 'rewritten content',
+      }
+      unsyncedFileKeys = new Set([liquidFileKey])
+      // Given
+      vi.mocked(bulkUploadThemeAssets).mockResolvedValue([
+        {
+          key: liquidFileKey,
+          success: true,
+          operation: Operation.Upload,
+          asset: rewrittenFileContent,
+        },
+      ])
+      vi.mocked(fetchThemeAssets).mockResolvedValue([rewrittenFileContent])
+      const handler = handleSyncUpdate(unsyncedFileKeys, uploadErrors, liquidFileKey, themeId, adminSession, write)
+
+      // When
+      const result = await handler({value: originalFileContent.value, checksum: originalFileContent.checksum})
+
+      // Then
+      expect(result).toBe(true)
+      expect(bulkUploadThemeAssets).toHaveBeenCalledWith(Number(themeId), [originalFileContent], adminSession)
+      expect(unsyncedFileKeys.has(liquidFileKey)).toBe(false)
+      expect(write).toHaveBeenCalledWith(rewrittenFileContent)
     })
 
     test('throws error and sets uploadErrors on failed sync', async () => {
@@ -762,10 +803,10 @@ describe('theme-fs', () => {
           errors: {asset: errors},
         },
       ])
-      const handler = handleSyncUpdate(unsyncedFileKeys, uploadErrors, fileKey, themeId, adminSession)
+      const handler = handleSyncUpdate(unsyncedFileKeys, uploadErrors, fileKey, themeId, adminSession, write)
 
       // When/Then
-      await expect(handler({value: 'content'})).rejects.toThrow('{{ broken liquid file')
+      await expect(handler({value: 'content', checksum: '123'})).rejects.toThrow('{{ broken liquid file')
       expect(uploadErrors.get(fileKey)).toEqual(errors)
       expect(unsyncedFileKeys.has(fileKey)).toBe(true)
       expect(triggerBrowserFullReload).toHaveBeenCalledWith(themeId, fileKey)
@@ -781,10 +822,11 @@ describe('theme-fs', () => {
           operation: Operation.Upload,
         },
       ])
-      const handler = handleSyncUpdate(unsyncedFileKeys, uploadErrors, fileKey, themeId, adminSession)
+      vi.mocked(fetchThemeAssets).mockResolvedValue([])
+      const handler = handleSyncUpdate(unsyncedFileKeys, uploadErrors, fileKey, themeId, adminSession, write)
 
       // When
-      await handler({value: 'content'})
+      await handler({value: 'content', checksum: '123'})
 
       // Then
       expect(uploadErrors.has(fileKey)).toBe(false)
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-uploader.test.ts b/packages/theme/src/cli/utilities/theme-uploader.test.ts
diff --git a/packages/theme/src/cli/utilities/theme-uploader.ts b/packages/theme/src/cli/utilities/theme-uploader.ts

Original file line number	Diff line number	Diff line change
`@@ -2,6 +2,7 @@ mutation themeFilesUpsert($files: [OnlineStoreThemeFilesUpsertFileInput!]!, $the`
`2`	`2`	`themeFilesUpsert(files: $files, themeId: $themeId) {`
`3`	`3`	`upsertedThemeFiles {`
`4`	`4`	`filename`
	`5`	`+ checksumMd5`
`5`	`6`	`}`
`6`	`7`	`userErrors {`
`7`	`8`	`filename`
Original file line number	Diff line number	Diff line change
`@@ -120,7 +120,10 @@ export async function dev(options: DevOptions) {`
`120`	`120`	`},`
`121`	`121`	`}`
`122`	`122`
`123`		`- const {serverStart, renderDevSetupProgress, backgroundJobPromise} = setupDevServer(options.theme, ctx)`
	`123`	`+ const {serverStart, renderDevSetupProgress, backgroundJobPromise, syncRewrittenFilesPromise} = setupDevServer(`
	`124`	`+ options.theme,`
	`125`	`+ ctx,`
	`126`	`+ )`
`124`	`127`
`125`	`128`	`readline.emitKeypressEvents(process.stdin)`
`126`	`129`	`if (process.stdin.isTTY) {`
`@@ -140,6 +143,7 @@ export async function dev(options: DevOptions) {`
`140`	`143`	`openURLSafely(urls.local, 'development server')`
`141`	`144`	`}`
`142`	`145`	`}),`
	`146`	`+ syncRewrittenFilesPromise(),`
`143`	`147`	`])`
`144`	`148`	`}`
`145`	`149`