fix(tailwindcss-patch): decouple runtime entry from cli bundle

Author: sonofmagic

.changeset/wise-lobsters-hunt.md

@@ -0,0 +1,5 @@
+---
+'tailwindcss-patch': patch
+---
+
+Fix the published CommonJS runtime entry so non-CLI APIs no longer eagerly load the ESM-only `cac` dependency. CLI code is now split into a separate lazy-loaded bundle, which keeps `require('tailwindcss-patch')` working in CommonJS config loaders while preserving CLI factory support.

packages/tailwindcss-patch/package.json

@@ -4,6 +4,9 @@
   "description": "patch tailwindcss for exposing context and extract classes",
   "author": "ice breaker <1324318532@qq.com>",
   "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
   "homepage": "https://mangle.icebreaker.top/",
   "repository": {
     "type": "git",

packages/tailwindcss-patch/src/cli.bundle.ts

@@ -0,0 +1,20 @@
+import process from 'node:process'
+import { createTailwindcssPatchCli, ValidateCommandError } from './index.bundle'
+import logger from './logger'
+
+async function main() {
+  const cli = createTailwindcssPatchCli()
+  cli.help()
+  cli.parse(process.argv, { run: false })
+  await cli.runMatchedCommand()
+}
+
+main().catch((error) => {
+  if (error instanceof ValidateCommandError) {
+    process.exitCode = error.exitCode
+    return
+  }
+  const message = error instanceof Error ? error.message : String(error)
+  logger.error(message)
+  process.exitCode = 1
+})

packages/tailwindcss-patch/src/index.bundle.ts

@@ -0,0 +1,105 @@
+import type { TailwindcssMangleConfig } from '@tailwindcss-mangle/config'
+import type { CAC } from 'cac'
+import type { TailwindcssPatchCliMountOptions, TailwindcssPatchCliOptions } from './commands/types'
+
+import { createRequire } from 'node:module'
+import { TailwindcssPatcher } from './api/tailwindcss-patcher'
+import { CacheStore } from './cache/store'
+import {
+  migrateConfigFiles,
+  MIGRATION_REPORT_KIND,
+  MIGRATION_REPORT_SCHEMA_VERSION,
+  restoreConfigFiles,
+} from './commands/migrate-config'
+import { tailwindcssPatchCommands } from './commands/types'
+import {
+  VALIDATE_EXIT_CODES,
+  VALIDATE_FAILURE_REASONS,
+  ValidateCommandError,
+} from './commands/validate'
+import { normalizeOptions } from './config'
+import {
+  extractProjectCandidatesWithPositions,
+  extractRawCandidates,
+  extractRawCandidatesWithPositions,
+  extractValidCandidates,
+  groupTokensByFile,
+} from './extraction/candidate-extractor'
+import {
+  collectClassesFromContexts,
+  collectClassesFromTailwindV4,
+  getPatchStatusReport,
+  loadRuntimeContexts,
+  runTailwindBuild,
+} from './install'
+import logger from './logger'
+
+const require = createRequire(import.meta.url)
+
+type CliModule = typeof import('./commands/cli')
+
+function loadCliModule(): CliModule {
+  return require('./commands/cli-runtime.js') as CliModule
+}
+
+export {
+  CacheStore,
+  collectClassesFromContexts,
+  collectClassesFromTailwindV4,
+  extractProjectCandidatesWithPositions,
+  extractRawCandidates,
+  extractRawCandidatesWithPositions,
+  extractValidCandidates,
+  getPatchStatusReport,
+  groupTokensByFile,
+  loadRuntimeContexts,
+  logger,
+  migrateConfigFiles,
+  MIGRATION_REPORT_KIND,
+  MIGRATION_REPORT_SCHEMA_VERSION,
+  normalizeOptions,
+  restoreConfigFiles,
+  runTailwindBuild,
+  tailwindcssPatchCommands,
+  TailwindcssPatcher,
+  VALIDATE_EXIT_CODES,
+  VALIDATE_FAILURE_REASONS,
+  ValidateCommandError,
+}
+export type {
+  ConfigFileMigrationEntry,
+  ConfigFileMigrationReport,
+  MigrateConfigFilesOptions,
+  RestoreConfigFilesOptions,
+  RestoreConfigFilesResult,
+} from './commands/migrate-config'
+export type {
+  TailwindcssPatchCliMountOptions,
+  TailwindcssPatchCliOptions,
+  TailwindcssPatchCommand,
+  TailwindcssPatchCommandContext,
+  TailwindcssPatchCommandHandler,
+  TailwindcssPatchCommandHandlerMap,
+  TailwindcssPatchCommandOptionDefinition,
+  TailwindcssPatchCommandOptions,
+} from './commands/types'
+export type {
+  ValidateFailureReason,
+  ValidateFailureSummary,
+  ValidateJsonFailurePayload,
+  ValidateJsonSuccessPayload,
+} from './commands/validate'
+export type { TailwindCssPatchOptions } from './config'
+export * from './types'
+
+export function mountTailwindcssPatchCommands(cli: CAC, options: TailwindcssPatchCliMountOptions = {}) {
+  return loadCliModule().mountTailwindcssPatchCommands(cli, options)
+}
+
+export function createTailwindcssPatchCli(options: TailwindcssPatchCliOptions = {}) {
+  return loadCliModule().createTailwindcssPatchCli(options)
+}
+
+export function defineConfig<T extends TailwindcssMangleConfig>(config: T): T {
+  return config
+}

packages/tailwindcss-patch/test/published-cjs-runtime.test.ts

@@ -0,0 +1,62 @@
+import { execFileSync } from 'node:child_process'
+import path from 'pathe'
+import { describe, expect, it } from 'vitest'
+
+const packageDir = path.resolve(__dirname, '..')
+const distEntry = path.join(packageDir, 'dist/index.js')
+
+function runCommonJs(script: string) {
+  return execFileSync(process.execPath, ['-e', script], {
+    cwd: packageDir,
+    encoding: 'utf8',
+  }).trim()
+}
+
+describe('published CommonJS runtime entry', () => {
+  it('requires non-CLI runtime APIs without triggering ERR_REQUIRE_ESM', () => {
+    const output = runCommonJs(`
+      ;(async () => {
+        const patch = require(${JSON.stringify(distEntry)})
+        const normalized = patch.normalizeOptions({ cache: false })
+        const extracted = await patch.extractRawCandidatesWithPositions('<div class="text-red-500"></div>', 'html')
+        console.log(JSON.stringify({
+          normalizedCacheEnabled: normalized.cache.enabled,
+          containsUtilityCandidate: extracted.some(entry => entry.rawCandidate === 'text-red-500'),
+          hasPatcher: typeof patch.TailwindcssPatcher,
+          hasExtractValidCandidates: typeof patch.extractValidCandidates,
+        }))
+      })().catch((error) => {
+        console.error(error)
+        process.exit(1)
+      })
+    `)
+
+    expect(JSON.parse(output)).toEqual({
+      normalizedCacheEnabled: false,
+      containsUtilityCandidate: true,
+      hasPatcher: 'function',
+      hasExtractValidCandidates: 'function',
+    })
+  })
+
+  it('creates the CLI on demand from the CommonJS entry', () => {
+    const output = runCommonJs(`
+      const patch = require(${JSON.stringify(distEntry)})
+      const cli = patch.createTailwindcssPatchCli({
+        name: 'embedded',
+        mountOptions: {
+          commands: ['status'],
+        },
+      })
+      console.log(JSON.stringify({
+        name: cli.name,
+        commands: cli.commands.map(command => command.name),
+      }))
+    `)
+
+    expect(JSON.parse(output)).toEqual({
+      name: 'embedded',
+      commands: ['status'],
+    })
+  })
+})

packages/tailwindcss-patch/tsup.config.ts

@@ -1,12 +1,17 @@
 import { defineConfig } from 'tsup'
 
 export default defineConfig({
-  entry: ['src/index.ts', 'src/cli.ts'],
+  entry: {
+    'index': 'src/index.bundle.ts',
+    'cli': 'src/cli.bundle.ts',
+    'commands/cli-runtime': 'src/commands/cli.ts',
+  },
   shims: true,
   clean: true,
   format: ['cjs', 'esm'], // , 'esm'
   dts: true,
   cjsInterop: true,
   splitting: true,
+  noExternal: ['cac'],
   external: ['tailwindcss', '@tailwindcss/node', '@tailwindcss/oxide'],
 })