Fix source map generation during when watching files on the CLI

[thecrypticace]

Fixes #19362

We were overwriting the source map with the "decoded" map returned by the compiler but didn't wrap it in the helper intended to help inline vs file maps. This resulted in two issues:

1. undefined being appended to the CSS file when using --map
2. undefined being passed to writeFile(…) when using --map <file>

This PR fixes both.

[coderabbitai]

Walkthrough

Replaces direct casting of compiler.buildSourceMap() with toSourceMap(compiler.buildSourceMap()) in the CLI build/rebuild paths to ensure proper SourceMap typing. Adds watch-mode tests covering inline and external source maps, validating initial builds, rebuilds after CSS edits, and parity between CLI and Standalone CLI. Updates CHANGELOG.md with a Fixed entry noting correct source map writing in CLI --watch mode.

Pre-merge checks

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main fix: correcting source map generation during watch mode on the CLI.
Description check	✅ Passed	The description clearly explains the root cause and the two issues being fixed, directly relating to the changeset.
Linked Issues check	✅ Passed	The PR comprehensively addresses both objectives from issue #19362: fixing 'undefined' appended to CSS with --map and TypeError with --map in watch mode.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to fixing source map generation in watch mode: CHANGELOG entry, tests validating the fix, and the core fix wrapping compiler output with toSourceMap().

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 068a1ec and 12c476d.

📒 Files selected for processing (2)

• CHANGELOG.md (1 hunks)
• integrations/cli/index.test.ts (2 hunks)

🚧 Files skipped from review as they are similar to previous changes (1)

• CHANGELOG.md

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (5)

• GitHub Check: Linux / postcss
• GitHub Check: Linux / vite
• GitHub Check: Linux / cli
• GitHub Check: Linux / upgrade
• GitHub Check: Linux

🔇 Additional comments (3)

integrations/cli/index.test.ts (3)

6-6: LGTM!

The retryAssertion import is correctly added and appropriately used in the new watch mode tests to handle asynchronous file system operations.

---

823-844: Good test coverage for the source map bug fix.

The new watch mode tests comprehensively validate both inline and separate source map scenarios, covering the exact issues reported in #19362:

• Initial build source map generation
• Source map updates after file changes
• Both --map (inline) and --map <file> (external) modes

Once the expectation values are corrected per the duplicate comments, these tests will properly prevent regression.

---

1000-1004: Unable to verify without test execution results.

The script confirms lines 1003 and 1027 match the snippet shown. However, determining whether these assertions are incorrect requires either:

1. Test execution output showing what map.at() actually returns, or
2. Understanding the code logic that generates these source map values

The current assertions show an inconsistent pattern: most map.at(4, 0) calls expect '}...', while a few expect expanded strings like '}\n.underli...' or '}\n.w-auto...'. Without CI test results or code analysis, I cannot confirm if lines 1003 and 1027 need adjustment.

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 3

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 28670a9 and 068a1ec.

📒 Files selected for processing (3)

• CHANGELOG.md (1 hunks)
• integrations/cli/index.test.ts (1 hunks)
• packages/@tailwindcss-cli/src/commands/build/index.ts (2 hunks)

🧰 Additional context used

🧬 Code graph analysis (1)

packages/@tailwindcss-cli/src/commands/build/index.ts (1)

packages/@tailwindcss-node/src/source-maps.ts (1)

• toSourceMap (44-59)

🪛 GitHub Check: Linux / cli

integrations/cli/index.test.ts

[failure] 1145-1145: cli/index.test.ts > Standalone CLI > watch mode + separate source maps
AssertionError: expected { source: null, …(2) } to match object { source: null, …(2) }

• Expected

• Received

  {

• "generated": "}
• .underli...",

• "generated": "}...",
  "original": "(none)",
  "source": null,
  }

❯ cli/index.test.ts:1145:28
❯ utils.ts:453:14

---

[failure] 919-919: cli/index.test.ts > Standalone CLI > watch mode + inline source maps
AssertionError: expected { source: null, …(2) } to match object { source: null, …(2) }

• Expected

• Received

  {

• "generated": "}
• .underli...",

• "generated": "}...",
  "original": "(none)",
  "source": null,
  }

❯ cli/index.test.ts:919:28
❯ utils.ts:453:14

---

[failure] 919-919: cli/index.test.ts > Standalone CLI > watch mode + inline source maps
AssertionError: expected { source: null, …(2) } to match object { source: null, …(2) }

• Expected

• Received

  {

• "generated": "}
• .underli...",

• "generated": "}...",
  "original": "(none)",
  "source": null,
  }

❯ cli/index.test.ts:919:28
❯ utils.ts:453:14

---

[failure] 919-919: cli/index.test.ts > Standalone CLI > watch mode + inline source maps
AssertionError: expected { source: null, …(2) } to match object { source: null, …(2) }

• Expected

• Received

  {

• "generated": "}
• .underli...",

• "generated": "}...",
  "original": "(none)",
  "source": null,
  }

❯ cli/index.test.ts:919:28
❯ utils.ts:453:14

---

[failure] 1145-1145: cli/index.test.ts > CLI > watch mode + separate source maps
AssertionError: expected { source: null, …(2) } to match object { source: null, …(2) }

• Expected

• Received

  {

• "generated": "}
• .underli...",

• "generated": "}...",
  "original": "(none)",
  "source": null,
  }

❯ cli/index.test.ts:1145:28
❯ utils.ts:453:14

---

[failure] 1145-1145: cli/index.test.ts > CLI > watch mode + separate source maps
AssertionError: expected { source: null, …(2) } to match object { source: null, …(2) }

• Expected

• Received

  {

• "generated": "}
• .underli...",

• "generated": "}...",
  "original": "(none)",
  "source": null,
  }

❯ cli/index.test.ts:1145:28
❯ utils.ts:453:14

---

[failure] 1145-1145: cli/index.test.ts > CLI > watch mode + separate source maps
AssertionError: expected { source: null, …(2) } to match object { source: null, …(2) }

• Expected

• Received

  {

• "generated": "}
• .underli...",

• "generated": "}...",
  "original": "(none)",
  "source": null,
  }

❯ cli/index.test.ts:1145:28
❯ utils.ts:453:14

---

[failure] 919-919: cli/index.test.ts > CLI > watch mode + inline source maps
AssertionError: expected { source: null, …(2) } to match object { source: null, …(2) }

• Expected

• Received

  {

• "generated": "}
• .underli...",

• "generated": "}...",
  "original": "(none)",
  "source": null,
  }

❯ cli/index.test.ts:919:28
❯ utils.ts:453:14

---

[failure] 919-919: cli/index.test.ts > CLI > watch mode + inline source maps
AssertionError: expected { source: null, …(2) } to match object { source: null, …(2) }

• Expected

• Received

  {

• "generated": "}
• .underli...",

• "generated": "}...",
  "original": "(none)",
  "source": null,
  }

❯ cli/index.test.ts:919:28
❯ utils.ts:453:14

---

[failure] 919-919: cli/index.test.ts > CLI > watch mode + inline source maps
AssertionError: expected { source: null, …(2) } to match object { source: null, …(2) }

• Expected

• Received

  {

• "generated": "}
• .underli...",

• "generated": "}...",
  "original": "(none)",
  "source": null,
  }

❯ cli/index.test.ts:919:28
❯ utils.ts:453:14

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)

• GitHub Check: Linux / upgrade
• GitHub Check: Linux

🔇 Additional comments (2)

packages/@tailwindcss-cli/src/commands/build/index.ts (2)

324-325: Use toSourceMap in watch rebuilds for consistent map handling

Wrapping compiler.buildSourceMap() with toSourceMap(…) in both full and incremental watch rebuilds aligns the watch paths with the expectations of write(…) (raw + inline) and with the initial-build behavior. This should prevent malformed or undefined map data from being appended inline or written to files during --watch rebuilds.

Also applies to: 349-350

---

392-395: Consistent toSourceMap usage for initial build source maps

Using toSourceMap(compiler.buildSourceMap()) inside handleError for the initial build ensures the source map always conforms to the SourceMap shape expected downstream, and keeps error handling behavior unchanged.

[RV7PR]

@thecrypticace It tried the @insiders but the problem still exists.

bun install tailwindcss@insiders @tailwindcss/cli@insiders @tailwindcss/typography@insiders                                      
bun add v1.3.4 (5eb2145b)

installed tailwindcss@0.0.0-insiders.164194d
installed @tailwindcss/cli@0.0.0-insiders.164194d with binaries:
 - tailwindcss
installed @tailwindcss/typography@0.0.0-insiders.3963dfe

[177.00ms] done

bunx @tailwindcss/cli -i ./_webblocks/css/input.css -o ./_webblocks/css/output.css --map  ./_webblocks/css/output.css.map --watch
≈ tailwindcss v4.1.17

Done in 125ms
TypeError [ERR_INVALID_ARG_TYPE]: The "data" argument must be of type string or an instance of Buffer, TypedArray, or DataView. Received undefined

[thecrypticace]

bunx @tailwindcss/cli … is running the latest stable version. It's not using the insiders build you installed.

If you run it with buns @tailwindcss/cli@insiders you'll see that it works.