Improve DEBUG flag (#6797)

* improve DEBUG flag

* update changelog

CHANGELOG.md

@@ -7,7 +7,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-- Nothing yet!
+### Fixed
+
+- Improve `DEBUG` flag ([#6797](https://github.com/tailwindlabs/tailwindcss/pull/6797))
 
 ## [3.0.8] - 2021-12-28
 

src/lib/sharedState.js

@@ -1,10 +1,49 @@
 export const env = {
   TAILWIND_MODE: process.env.TAILWIND_MODE,
   NODE_ENV: process.env.NODE_ENV,
-  DEBUG: process.env.DEBUG !== undefined && process.env.DEBUG !== '0',
+  DEBUG: resolveDebug(process.env.DEBUG),
   TAILWIND_DISABLE_TOUCH: process.env.TAILWIND_DISABLE_TOUCH !== undefined,
   TAILWIND_TOUCH_DIR: process.env.TAILWIND_TOUCH_DIR,
 }
 export const contextMap = new Map()
 export const configContextMap = new Map()
 export const contextSourcesMap = new Map()
+
+export function resolveDebug(debug) {
+  if (debug === undefined) {
+    return false
+  }
+
+  // Environment variables are strings, so convert to boolean
+  if (debug === 'true' || debug === '1') {
+    return true
+  }
+
+  if (debug === 'false' || debug === '0') {
+    return false
+  }
+
+  // Keep the debug convention into account:
+  // DEBUG=* -> This enables all debug modes
+  // DEBUG=projectA,projectB,projectC -> This enables debug for projectA, projectB and projectC
+  // DEBUG=projectA:* -> This enables all debug modes for projectA (if you have sub-types)
+  // DEBUG=projectA,-projectB -> This enables debug for projectA and explicitly disables it for projectB
+
+  if (debug === '*') {
+    return true
+  }
+
+  let debuggers = debug.split(',').map((d) => d.split(':')[0])
+
+  // Ignoring tailwind / tailwindcss
+  if (debuggers.includes('-tailwindcss') || debuggers.includes('-tailwind')) {
+    return false
+  }
+
+  // Definitely including tailwind / tailwindcss
+  if (debuggers.includes('tailwindcss') || debuggers.includes('tailwind')) {
+    return true
+  }
+
+  return false
+}

tests/shared-state.test.js

@@ -0,0 +1,28 @@
+import { resolveDebug } from '../src/lib/sharedState'
+
+it.each`
+  value                     | expected
+  ${'true'}                 | ${true}
+  ${'1'}                    | ${true}
+  ${'false'}                | ${false}
+  ${'0'}                    | ${false}
+  ${'*'}                    | ${true}
+  ${'tailwind'}             | ${true}
+  ${'tailwind:*'}           | ${true}
+  ${'tailwindcss'}          | ${true}
+  ${'tailwindcss:*'}        | ${true}
+  ${'other,tailwind'}       | ${true}
+  ${'other,tailwind:*'}     | ${true}
+  ${'other,tailwindcss'}    | ${true}
+  ${'other,tailwindcss:*'}  | ${true}
+  ${'other,-tailwind'}      | ${false}
+  ${'other,-tailwind:*'}    | ${false}
+  ${'other,-tailwindcss'}   | ${false}
+  ${'other,-tailwindcss:*'} | ${false}
+  ${'-tailwind'}            | ${false}
+  ${'-tailwind:*'}          | ${false}
+  ${'-tailwindcss'}         | ${false}
+  ${'-tailwindcss:*'}       | ${false}
+`('should resolve the debug ($value) flag correctly ($expected)', ({ value, expected }) => {
+  expect(resolveDebug(value)).toBe(expected)
+})