Tailwind Integration Architecture

In this file.

https://github.com/tailwindlabs/tailwindcss/blob/master/src/cli.js

Starting at line 784 is the beginning of the watchers.

The watching is managed by this library.

https://github.com/paulmillr/chokidar

watcher.on('change', async (file) => {
      if (contextDependencies.has(file)) {
        env.DEBUG && console.time('Resolve config')
        context = null
        config = refreshConfig(configPath)
        env.DEBUG && console.timeEnd('Resolve config')

        env.DEBUG && console.time('Watch new files')
        let globs = extractFileGlobs(config)
        watcher.add(configDependencies)
        watcher.add(globs)
        env.DEBUG && console.timeEnd('Watch new files')

        chain = chain.then(async () => {
          changedContent.push(...getChangedContent(config))
          await rebuild(config)
        })
      } else {
        chain = chain.then(async () => {
          changedContent.push({
            content: fs.readFileSync(path.resolve(file), 'utf8'),
            extension: path.extname(file).slice(1),
          })

          await rebuild(config)
        })
      }
    })

   watcher.on('add', async (file) => {
      chain = chain.then(async () => {
        changedContent.push({
          content: fs.readFileSync(path.resolve(file), 'utf8'),
          extension: path.extname(file).slice(1),
        })

        await rebuild(config)
      })
    })

    chain = chain.then(() => {
      changedContent.push(...getChangedContent(config))
      return rebuild(config)
    })
  }

When a file is added or changed the watcher triggers a chain execution.

I suspect the chain execution is responsible for altering the css rules that are included in the stylesheet.

The rebuild function seems to be the kickoff of where the magic happens.

   async function rebuild(config) {
      env.DEBUG && console.time('Finished in')

      let tailwindPlugin = () => {
        return {
          postcssPlugin: 'tailwindcss',
          Once(root, { result }) {
            env.DEBUG && console.time('Compiling CSS')
            tailwind(({ createContext }) => {
              console.error()
              console.error('Rebuilding...')

              return () => {
                if (context !== null) {
                  context.changedContent = changedContent.splice(0)
                  return context
                }

                env.DEBUG && console.time('Creating context')
                context = createContext(config, changedContent.splice(0))
                env.DEBUG && console.timeEnd('Creating context')
                return context
              }
            })(root, result)
            env.DEBUG && console.timeEnd('Compiling CSS')
          },
        }
      }

That leads us to here.

import tailwind from './processTailwindFeatures'

Functions re called that alter the context of the outer function. The context is used to maintain state between the pipeline of functions.

import normalizeTailwindDirectives from './lib/normalizeTailwindDirectives'
import expandTailwindAtRules from './lib/expandTailwindAtRules'
import expandApplyAtRules from './lib/expandApplyAtRules'
import evaluateTailwindFunctions from './lib/evaluateTailwindFunctions'
import substituteScreenAtRules from './lib/substituteScreenAtRules'
import resolveDefaultsAtRules from './lib/resolveDefaultsAtRules'
import collapseAdjacentRules from './lib/collapseAdjacentRules'
import collapseDuplicateDeclarations from './lib/collapseDuplicateDeclarations'
import partitionApplyAtRules from './lib/partitionApplyAtRules'
import detectNesting from './lib/detectNesting'
import { createContext } from './lib/setupContextUtils'
import { issueFlagNotices } from './featureFlags'

export default function processTailwindFeatures(setupContext) {
  return function (root, result) {
    let { tailwindDirectives, applyDirectives } = normalizeTailwindDirectives(root)

    detectNesting()(root, result)

    // Partition apply rules that are found in the css
    // itself.
    partitionApplyAtRules()(root, result)

    let context = setupContext({
      tailwindDirectives,
      applyDirectives,
      registerDependency(dependency) {
        result.messages.push({
          plugin: 'tailwindcss',
          parent: result.opts.from,
          ...dependency,
        })
      },
      createContext(tailwindConfig, changedContent) {
        return createContext(tailwindConfig, changedContent, root)
      },
    })(root, result)

    if (context.tailwindConfig.separator === '-') {
      throw new Error(
        "The '-' character cannot be used as a custom separator in JIT mode due to parsing ambiguity. Please use another character like '_' instead."
      )
    }

    issueFlagNotices(context.tailwindConfig)

    expandTailwindAtRules(context)(root, result)
    // Partition apply rules that are generated by
    // addComponents, addUtilities and so on.
    partitionApplyAtRules()(root, result)
    expandApplyAtRules(context)(root, result)
    evaluateTailwindFunctions(context)(root, result)
    substituteScreenAtRules(context)(root, result)
    resolveDefaultsAtRules(context)(root, result)
    collapseAdjacentRules(context)(root, result)
    collapseDuplicateDeclarations(context)(root, result)
  }
}

https://github.com/tailwindlabs/tailwindcss/blob/master/src/processTailwindFeatures.js

The bulk of the grunt work appears to be happening in these functions.

    issueFlagNotices(context.tailwindConfig)

    expandTailwindAtRules(context)(root, result)
    // Partition apply rules that are generated by
    // addComponents, addUtilities and so on.
    partitionApplyAtRules()(root, result)
    expandApplyAtRules(context)(root, result)
    evaluateTailwindFunctions(context)(root, result)
    substituteScreenAtRules(context)(root, result)
    resolveDefaultsAtRules(context)(root, result)
    collapseAdjacentRules(context)(root, result)
    collapseDuplicateDeclarations(context)(root, result)

I think root is the abstract css tree generated by post css. This process alters that tree through calling the above series of functions.

This is function that generates the css from file. Meaning parses the changed content and expands it into css rules apart of the abstract syntax tree.

https://github.com/tailwindlabs/tailwindcss/blob/f6eeed34a006ddc1ec12609b4f5f933c1f886e63/src/lib/expandTailwindAtRules.js#L133