From 219e019b2458a5441bf7e3cf54884ed8b888f3cc Mon Sep 17 00:00:00 2001
From: Jordan Pittman <jordan@cryptica.me>
Date: Thu, 18 Dec 2025 15:02:27 -0500
Subject: [PATCH] CLI: Emit comment when source maps are saved to files
 (#19447)

See
https://github.com/tailwindlabs/tailwindcss/issues/19362#issuecomment-3654376948
---
 CHANGELOG.md                                      |  1 +
 integrations/cli/index.test.ts                    | 10 +++++-----
 .../@tailwindcss-cli/src/commands/build/index.ts  | 12 ++++++++++++
 packages/@tailwindcss-node/src/source-maps.ts     | 15 ++++++++-------
 4 files changed, 26 insertions(+), 12 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index be8ec9aef..b776a93e5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Do not wrap `color-mix` in a `@supports` rule if one already exists ([#19450](https://github.com/tailwindlabs/tailwindcss/pull/19450))
 - Allow whitespace around `@source inline()` argument ([#19461](https://github.com/tailwindlabs/tailwindcss/pull/19461))
+- CLI: Emit comment when source maps are saved to files ([#19447](https://github.com/tailwindlabs/tailwindcss/pull/19447))
 
 ### Added
 
diff --git a/integrations/cli/index.test.ts b/integrations/cli/index.test.ts
index 870a1baec..409a9de7c 100644
--- a/integrations/cli/index.test.ts
+++ b/integrations/cli/index.test.ts
@@ -752,7 +752,7 @@ describe.each([
       expect(map.at(4, 0)).toMatchObject({
         source: null,
         original: '(none)',
-        generated: '}...',
+        generated: '}\n\n/*# sou...',
       })
     },
   )
@@ -815,7 +815,7 @@ describe.each([
       expect(map.at(4, 0)).toMatchObject({
         source: null,
         original: '(none)',
-        generated: '}...',
+        generated: '}\n\n/*# sou...',
       })
     },
   )
@@ -1118,7 +1118,7 @@ describe.each([
       expect(map.at(4, 0)).toMatchObject({
         source: null,
         original: '(none)',
-        generated: '}...',
+        generated: '}\n\n/*# sou...',
       })
 
       // Write to project source files
@@ -1190,7 +1190,7 @@ describe.each([
       expect(map.at(7, 0)).toMatchObject({
         source: null,
         original: '(none)',
-        generated: '}...',
+        generated: '}\n\n/*# sou...',
       })
 
       // Write to the main CSS file
@@ -1290,7 +1290,7 @@ describe.each([
       expect(map.at(10, 0)).toMatchObject({
         source: null,
         original: '(none)',
-        generated: '}...',
+        generated: '}\n\n/*# sou...',
       })
     },
   )
diff --git a/packages/@tailwindcss-cli/src/commands/build/index.ts b/packages/@tailwindcss-cli/src/commands/build/index.ts
index f0d441fe2..eabd2a1de 100644
--- a/packages/@tailwindcss-cli/src/commands/build/index.ts
+++ b/packages/@tailwindcss-cli/src/commands/build/index.ts
@@ -182,6 +182,18 @@ export async function handle(args: Result<ReturnType<typeof options>>) {
         output += `\n`
         output += map.inline
       } else if (typeof args['--map'] === 'string') {
+        let basePath =
+          args['--output'] && args['--output'] !== '-'
+            ? path.dirname(path.resolve(args['--output']))
+            : process.cwd()
+
+        let mapPath = path.resolve(args['--map'])
+
+        let relativePath = path.relative(basePath, mapPath)
+
+        output += `\n`
+        output += map.comment(relativePath)
+
         DEBUG && I.start('Write source map')
         await outputFile(args['--map'], map.raw)
         DEBUG && I.end('Write source map')
diff --git a/packages/@tailwindcss-node/src/source-maps.ts b/packages/@tailwindcss-node/src/source-maps.ts
index 3f02efb24..8810b106c 100644
--- a/packages/@tailwindcss-node/src/source-maps.ts
+++ b/packages/@tailwindcss-node/src/source-maps.ts
@@ -6,6 +6,7 @@ export type { DecodedSource, DecodedSourceMap }
 export interface SourceMap {
   readonly raw: string
   readonly inline: string
+  comment(url: string): string
 }
 
 function serializeSourceMap(map: DecodedSourceMap): string {
@@ -44,16 +45,16 @@ function serializeSourceMap(map: DecodedSourceMap): string {
 export function toSourceMap(map: DecodedSourceMap | string): SourceMap {
   let raw = typeof map === 'string' ? map : serializeSourceMap(map)
 
+  function comment(url: string) {
+    return `/*# sourceMappingURL=${url} */\n`
+  }
+
   return {
     raw,
     get inline() {
-      let tmp = ''
-
-      tmp += '/*# sourceMappingURL=data:application/json;base64,'
-      tmp += Buffer.from(raw, 'utf-8').toString('base64')
-      tmp += ' */\n'
-
-      return tmp
+      let inlined = Buffer.from(raw, 'utf-8').toString('base64')
+      return comment(`data:application/json;base64,${inlined}`)
     },
+    comment,
   }
 }