CLI: Emit comment when source maps are saved to files (#19447)

See
https://github.com/tailwindlabs/tailwindcss/issues/19362#issuecomment-3654376948

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
 

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...',
       })
     },
   )

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

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,
   }
 }