chore: bump version

Author: sonofmagic

.changeset/relative-config-base.md

@@ -0,0 +1,5 @@
+---
+'tailwindcss-patch': patch
+---
+
+Ensure Tailwind v4 CSS entries resolve `@config` paths relative to each CSS file when no explicit base is provided.

packages/tailwindcss-patch/src/options/normalize.ts

@@ -125,12 +125,14 @@ function normalizeTailwindV4Options(
   v4: TailwindV4UserOptions | undefined,
   fallbackBase: string,
 ): NormalizedTailwindV4Options {
-  const base = v4?.base ? path.resolve(v4.base) : fallbackBase
+  const configuredBase = v4?.base ? path.resolve(v4.base) : undefined
+  const base = configuredBase ?? fallbackBase
   const cssEntries = Array.isArray(v4?.cssEntries)
     ? v4!.cssEntries.filter((entry): entry is string => Boolean(entry)).map(entry => path.resolve(entry))
     : []
-  const sources = v4?.sources?.length
-    ? v4.sources
+  const hasUserDefinedSources = Boolean(v4?.sources?.length)
+  const sources = hasUserDefinedSources
+    ? v4!.sources
     : [
         {
           base,
@@ -141,9 +143,11 @@ function normalizeTailwindV4Options(
 
   return {
     base,
+    configuredBase,
     css: v4?.css,
     cssEntries,
     sources,
+    hasUserDefinedSources,
   }
 }
 

packages/tailwindcss-patch/src/options/types.ts

@@ -4,75 +4,140 @@ import type { ILengthUnitsPatchOptions } from '../types'
 
 export type CacheStrategy = 'merge' | 'overwrite'
 
+/**
+ * Configures how the Tailwind class cache is stored and where it lives on disk.
+ */
 export interface CacheUserOptions {
+  /** Whether caching is enabled. */
   enabled?: boolean
+  /** Working directory used when resolving cache paths. */
   cwd?: string
+  /** Directory where cache files are written. */
   dir?: string
+  /**
+   * Cache filename. Defaults to `class-cache.json` inside the derived cache folder
+   * when omitted.
+   */
   file?: string
+  /** Strategy used when merging new class lists with an existing cache. */
   strategy?: CacheStrategy
 }
 
+/**
+ * Controls how extracted class lists are written to disk.
+ */
 export interface OutputUserOptions {
+  /** Whether to produce an output file. */
   enabled?: boolean
+  /** Optional absolute or relative path to the output file. */
   file?: string
+  /** Output format, defaults to JSON when omitted. */
   format?: 'json' | 'lines'
+  /** Pretty-print spacing (truthy value enables indentation). */
   pretty?: number | boolean
+  /** Whether to strip the universal selector (`*`) from the final list. */
   removeUniversalSelector?: boolean
 }
 
+/**
+ * Options controlling how Tailwind contexts are exposed during runtime patching.
+ */
 export interface ExposeContextUserOptions {
+  /** Name of the property used to reference an exposed context. */
   refProperty?: string
 }
 
+/**
+ * Extends the built-in length-unit patch with custom defaults.
+ */
 export interface ExtendLengthUnitsUserOptions extends Partial<ILengthUnitsPatchOptions> {
+  /** Enables or disables the length-unit patch. */
   enabled?: boolean
 }
 
+/**
+ * Feature switches that toggle optional Tailwind patch capabilities.
+ */
 export interface FeatureUserOptions {
+  /** Whether to expose runtime Tailwind contexts (or configure how they are exposed). */
   exposeContext?: boolean | ExposeContextUserOptions
+  /** Extends the length-unit patch or disables it entirely. */
   extendLengthUnits?: false | ExtendLengthUnitsUserOptions
 }
 
+/**
+ * Shared configuration used for Tailwind v2/v3 patching flows.
+ */
 export interface TailwindConfigUserOptions {
+  /** Path to a Tailwind config file when auto-detection is insufficient. */
   config?: string
+  /** Custom working directory used when resolving config-relative paths. */
   cwd?: string
+  /** Optional PostCSS plugin name to use instead of the default. */
   postcssPlugin?: string
 }
 
+/**
+ * Additional configuration specific to Tailwind CSS v4 extraction.
+ */
 export interface TailwindV4UserOptions {
+  /** Base directory used when resolving v4 content sources and configs. */
   base?: string
+  /** Raw CSS passed directly to the v4 design system. */
   css?: string
+  /** Set of CSS entry files that should be scanned for `@config` directives. */
   cssEntries?: string[]
+  /** Overrides the content sources scanned by the oxide scanner. */
   sources?: SourceEntry[]
 }
 
+/**
+ * High-level Tailwind patch configuration shared across versions.
+ */
 export interface TailwindUserOptions extends TailwindConfigUserOptions {
   /**
    * Optional hint for picking the patch strategy.
    * When omitted we infer from the installed Tailwind CSS package version.
    */
   version?: 2 | 3 | 4
+  /** Tailwind package name if the project uses a fork. */
   packageName?: string
+  /** Package resolution options forwarded to `local-pkg`. */
   resolve?: PackageResolvingOptions
+  /** Overrides applied when patching Tailwind CSS v2. */
   v2?: TailwindConfigUserOptions
+  /** Overrides applied when patching Tailwind CSS v3. */
   v3?: TailwindConfigUserOptions
+  /** Options specific to Tailwind CSS v4 patching. */
   v4?: TailwindV4UserOptions
 }
 
+/**
+ * Root configuration consumed by the Tailwind CSS patch runner.
+ */
 export interface TailwindcssPatchOptions {
   /**
    * Base directory used when resolving Tailwind resources.
    * Defaults to `process.cwd()`.
    */
   cwd?: string
+  /** Whether to overwrite generated artifacts (e.g., caches, outputs). */
   overwrite?: boolean
+  /** Tailwind-specific configuration grouped by major version. */
   tailwind?: TailwindUserOptions
+  /** Feature toggles for optional helpers. */
   features?: FeatureUserOptions
+  /** Optional function that filters final class names. */
   filter?: (className: string) => boolean
+  /** Cache configuration or boolean to enable/disable quickly. */
   cache?: boolean | CacheUserOptions
+  /** Output configuration or boolean to inherits defaults. */
   output?: OutputUserOptions
 }
 
+/**
+ * Stable shape for output configuration after normalization.
+ */
 export interface NormalizedOutputOptions {
   enabled: boolean
   file?: string
@@ -81,6 +146,9 @@ export interface NormalizedOutputOptions {
   removeUniversalSelector: boolean
 }
 
+/**
+ * Stable cache configuration used internally after defaults are applied.
+ */
 export interface NormalizedCacheOptions {
   enabled: boolean
   cwd: string
@@ -90,22 +158,30 @@ export interface NormalizedCacheOptions {
   strategy: CacheStrategy
 }
 
+/** Tracks whether runtime contexts should be exposed and via which property. */
 export interface NormalizedExposeContextOptions {
   enabled: boolean
   refProperty: string
 }
 
+/** Normalized representation of the extend-length-units feature flag. */
 export interface NormalizedExtendLengthUnitsOptions extends ILengthUnitsPatchOptions {
   enabled: boolean
 }
 
+/** Normalized Tailwind v4 configuration consumed by runtime helpers. */
 export interface NormalizedTailwindV4Options {
   base: string
+  configuredBase?: string
   css?: string
   cssEntries: string[]
   sources: SourceEntry[]
+  hasUserDefinedSources: boolean
 }
 
+/**
+ * Tailwind configuration ready for consumption by the runtime after normalization.
+ */
 export interface NormalizedTailwindConfigOptions extends TailwindConfigUserOptions {
   packageName: string
   versionHint?: 2 | 3 | 4
@@ -115,11 +191,13 @@ export interface NormalizedTailwindConfigOptions extends TailwindConfigUserOptio
   v4?: NormalizedTailwindV4Options
 }
 
+/** Grouped normalized feature flags. */
 export interface NormalizedFeatureOptions {
   exposeContext: NormalizedExposeContextOptions
   extendLengthUnits: NormalizedExtendLengthUnitsOptions | null
 }
 
+/** Final normalized shape consumed throughout the patch runtime. */
 export interface NormalizedTailwindcssPatchOptions {
   projectRoot: string
   overwrite: boolean

packages/tailwindcss-patch/src/runtime/class-collector.ts

@@ -35,13 +35,33 @@ export async function collectClassesFromTailwindV4(
     return set
   }
 
-  const sources = v4Options.sources?.map((source) => {
-    return {
-      base: source.base ?? v4Options.base ?? process.cwd(),
+  const toAbsolute = (value: string | undefined) => {
+    if (!value) {
+      return undefined
+    }
+    return path.isAbsolute(value) ? value : path.resolve(options.projectRoot, value)
+  }
+  const resolvedConfiguredBase = toAbsolute(v4Options.configuredBase)
+  const resolvedDefaultBase = toAbsolute(v4Options.base) ?? process.cwd()
+  const resolveSources = (base: string) => {
+    if (!v4Options.sources?.length) {
+      return undefined
+    }
+
+    if (!v4Options.hasUserDefinedSources && !resolvedConfiguredBase) {
+      return v4Options.sources.map(source => ({
+        base,
+        pattern: source.pattern,
+        negated: source.negated,
+      }))
+    }
+
+    return v4Options.sources.map(source => ({
+      base: source.base ?? base,
       pattern: source.pattern,
       negated: source.negated,
-    }
-  })
+    }))
+  }
 
   if (v4Options.cssEntries.length > 0) {
     for (const entry of v4Options.cssEntries) {
@@ -50,9 +70,12 @@ export async function collectClassesFromTailwindV4(
         continue
       }
       const css = await fs.readFile(filePath, 'utf8')
+      const entryDir = path.dirname(filePath)
+      const baseForEntry = resolvedConfiguredBase ?? entryDir
+      const sources = resolveSources(baseForEntry)
       const candidates = await extractValidCandidates({
         cwd: options.projectRoot,
-        base: v4Options.base,
+        base: baseForEntry,
         css,
         sources,
       })
@@ -64,9 +87,11 @@ export async function collectClassesFromTailwindV4(
     }
   }
   else {
+    const baseForCss = resolvedConfiguredBase ?? resolvedDefaultBase
+    const sources = resolveSources(baseForCss)
     const candidates = await extractValidCandidates({
       cwd: options.projectRoot,
-      base: v4Options.base,
+      base: baseForCss,
       css: v4Options.css,
       sources,
     })

packages/tailwindcss-patch/test/runtime.class-collector.test.ts

@@ -1,5 +1,9 @@
+import os from 'node:os'
+import fs from 'fs-extra'
+import path from 'pathe'
 import { describe, expect, it } from 'vitest'
-import { collectClassesFromContexts } from '@/runtime/class-collector'
+import { collectClassesFromContexts, collectClassesFromTailwindV4 } from '@/runtime/class-collector'
+import { normalizeOptions } from '@/options/normalize'
 
 function createContext(classes: string[]) {
   const map = new Map()
@@ -20,3 +24,62 @@ describe('collectClassesFromContexts', () => {
     expect(result.has('*')).toBe(false)
   })
 })
+
+describe('collectClassesFromTailwindV4', () => {
+  it('resolves @config relative to the CSS entry directory', async () => {
+    const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'tw-v4-class-collector-'))
+    try {
+      const cssDir = path.join(tempDir, 'src')
+      await fs.ensureDir(cssDir)
+
+      const configPath = path.join(tempDir, 'tailwind.config.js')
+      await fs.writeFile(
+        configPath,
+        [
+          'module.exports = {',
+          '  content: [],',
+          '  theme: {',
+          '    extend: {',
+          '      colors: {',
+          "        brand: '#534312',",
+          '      },',
+          '    },',
+          '  },',
+          '};',
+        ].join('\n'),
+        'utf8',
+      )
+
+      const cssPath = path.join(cssDir, 'app.css')
+      await fs.writeFile(
+        cssPath,
+        [
+          '@config "../tailwind.config.js";',
+          '@utility bg-[#534312] {',
+          '  background-color: #534312;',
+          '}',
+        ].join('\n'),
+        'utf8',
+      )
+
+      const usageFile = path.join(cssDir, 'index.html')
+      await fs.writeFile(usageFile, '<div class="bg-[#534312]"></div>', 'utf8')
+
+      const normalized = normalizeOptions({
+        cwd: tempDir,
+        tailwind: {
+          version: 4,
+          v4: {
+            cssEntries: [cssPath],
+          },
+        },
+      })
+
+      const classes = await collectClassesFromTailwindV4(normalized)
+      expect(classes.has('bg-[#534312]')).toBe(true)
+    }
+    finally {
+      await fs.remove(tempDir)
+    }
+  })
+})