source() handling different between cli and vite

[hyperknot]

What version of Tailwind CSS are you using?

For example: v4.0.6

What build tool (or framework if it abstracts the build tool) are you using?

tailwindcss 4.1.12
@tailwindcss/vite 4.1.12

What version of Node.js are you using?
v22.13.1

What browser are you using?

What operating system are you using?

macOS

Describe your issue

The same line

@import "tailwindcss" source("../../components");

works with cli but not with the Vite plugin. Vite says directory doesn't exist.

I'm trying to figure out what is the base directory in Vite plugin, but it's impossible. I enabled DEBUG, but it shows nothing meaningful.

transforming (1) src/index.tsx
[78.23ms] [@tailwindcss/vite] Generate CSS (build)
[77.96ms]   ↳ Setup compiler

✓ 6 modules transformed.
✗ Build failed in 142ms
error during build:
[@tailwindcss/vite:generate:build] The `source(../../components)` does not exist 

Even when it works, it's really not showing anything. The most important information would be:

• base dir
• absolute path of the resolved scan target
• exact file list added by the scanner

Instead, I get this:

transforming (7) ../packages/shared/components/AppUI.tsx
[163.03ms] [@tailwindcss/vite] Generate CSS (build)
[ 81.87ms]   ↳ Setup compiler
[  3.72ms]   ↳ Setup scanner
[ 14.76ms]   ↳ Scan for candidates
[ 14.70ms]   ↳ Build CSS
[  0.00ms]   ↳ Build Source Map
[ 12.48ms] [@tailwindcss/vite] Optimize CSS

Right now, I'm at the step when I'm recompiling tailwind/vite to add these debug lines.

So please take this as both a bug report and a feature request.

1. Bug: cli can compile a file that vite cannot.
2. Feature request: allow users to see what's happening, otherwise configuring source() is totally walking in the dark.

[hyperknot]

OK, this is quite a puzzle. I've been able to recompile the vite plugin to finally show me debug lines about what's the base path. This way I was able to find out what's the resolved directory and fix the source import.

Please, add those debug lines, I guess that maybe 1 out of 100 users go as far as to recompile the library just to be able to see a debug line.

Now, to the actual bug:
This works correctly:

tailwind/_tailwind.css:

@import "tailwindcss" source("../../components");

CLI => 23k OK

 npx @tailwindcss/cli -i tailwind/_tailwind.css | wc -c
≈ tailwindcss v4.1.12

Done in 37ms
   23405

This way it's not finding the files:

_stylesheet.css:

@import "./tailwind/_tailwind.css";

tailwind/_tailwind.css:

@import "tailwindcss" source("../components");

CLI => 4k only

npx @tailwindcss/cli -i _stylesheet.css | wc -c
≈ tailwindcss v4.1.12

Done in 26ms
    4881

So I can conclude that the scanning logic is broken, if @import "tailwindcss" is not on the top level CSS file.

[wongjn]

I think for the second case, tailwind/_tailwind.css should be:

@import "tailwindcss" source("../../components");

So the same as the first case. This is because paths are relative to the CSS file they appear in.

[RobinMalfait]

Hey!

Can you share a minimal reproduction repo?

As @wongjn mentioned, the source(…) paths are relative to the CSS file you are in which will be the same for the CLI and the Vite or PostCSS setup.

[hyperknot]

OK, I managed to make a min repro repo:

https://github.com/hyperknot/bug_repro/tree/main/tailwind_source_bug

1. Inside tailwind_source_bug, pnpm i
2. pnpm vite build; grep bg- dist/assets/index-*.css
3. => should show exactly .bg-blue-800. NOT bg-red or empty line.
4. Then change the comment of these imports:

https://github.com/hyperknot/bug_repro/blob/main/tailwind_source_bug/web_app/src/index.tsx

as well as here:
https://github.com/hyperknot/bug_repro/blob/main/tailwind_source_bug/packages/shared/styles/tailwind/_tailwind.css

And you'll see it's broken. The dir resolution is buggy, the includes are buggy, basically importing is broken if @import "tailwindcss" isn't in the directly imported file.

Also, you'll see why adding those debug lines is super needed here, as it's kind of impossible to figure out what's someone is trying to import.

[wongjn]

Thank you! Note, there should be a step 1.5, where one should cd web_app before pnpm vite build.

With the files in the broken case, editing _tailwind.css to:

@import "tailwindcss" source("../../");

And then running with DEBUG=* produces:

2025-08-30T22:18:15.365672Z  INFO tailwindcss_oxide::scanner: Provided sources:
2025-08-30T22:18:15.365715Z  INFO tailwindcss_oxide::scanner: Source: PublicSourceEntry { base: "/home/justin/projects/test/tailwind_source_bug/packages/shared/styles/tailwind", pattern: "../../", negated: false }
2025-08-30T22:18:15.365766Z  INFO tailwindcss_oxide::scanner: Optimized sources:
2025-08-30T22:18:15.365780Z  INFO tailwindcss_oxide::scanner: Source: Auto { base: "/home/justin/projects/test/tailwind_source_bug/packages/shared" }
2025-08-30T22:18:15.366554Z  INFO scan_sources: tailwindcss_oxide::scanner: enter
2025-08-30T22:18:15.366813Z  INFO scan_sources: tailwindcss_oxide::scanner: Discovering "/home/justin/projects/test/tailwind_source_bug/packages/shared/components"
2025-08-30T22:18:15.366877Z  INFO scan_sources: tailwindcss_oxide::scanner: Discovering "/home/justin/projects/test/tailwind_source_bug/packages/shared/components/AppUI.tsx"
2025-08-30T22:18:15.366943Z  INFO scan_sources: tailwindcss_oxide::scanner: Discovering "/home/justin/projects/test/tailwind_source_bug/packages/shared/package.json"
2025-08-30T22:18:15.366973Z  INFO scan_sources: tailwindcss_oxide::scanner: Discovering "/home/justin/projects/test/tailwind_source_bug/packages/shared/styles"
2025-08-30T22:18:15.367015Z  INFO scan_sources: tailwindcss_oxide::scanner: Discovering "/home/justin/projects/test/tailwind_source_bug/packages/shared/styles/tailwind"
2025-08-30T22:18:15.367057Z  INFO scan_sources: tailwindcss_oxide::scanner: Discovering "/home/justin/projects/test/tailwind_source_bug/packages/shared/styles/tailwind/_tailwind.css"
2025-08-30T22:18:15.367086Z  INFO scan_sources: tailwindcss_oxide::scanner: Discovering "/home/justin/projects/test/tailwind_source_bug/packages/shared/styles/_stylesheet.css"
2025-08-30T22:18:15.367127Z  INFO scan_sources: tailwindcss_oxide::scanner: Discovering "/home/justin/projects/test/tailwind_source_bug/packages/shared/non-components"
2025-08-30T22:18:15.367170Z  INFO scan_sources: tailwindcss_oxide::scanner: Discovering "/home/justin/projects/test/tailwind_source_bug/packages/shared/non-components/AppUI.tsx"

So it seems like the scanning resolution is correct and relative to the _tailwind.css file. Thus we could presume that source("../../components"); should work. However, it seems like a mismatch with the verification code here:

tailwindcss/packages/@tailwindcss-node/src/compile.ts

Lines 66 to 91 in 5e2a160

	async function ensureSourceDetectionRootExists(
	compiler: { root: Awaited<ReturnType<typeof compile>>['root'] },
	base: string,
	) {
	// Verify if the `source(…)` path exists (until the glob pattern starts)
	if (compiler.root && compiler.root !== 'none') {
	let globSymbols = /[*{]/
	let basePath = []
	for (let segment of compiler.root.pattern.split('/')) {
	if (globSymbols.test(segment)) {
	break
	}
	basePath.push(segment)
	}
	let exists = await fsPromises
	.stat(path.resolve(base, basePath.join('/')))
	.then((stat) => stat.isDirectory())
	.catch(() => false)
	if (!exists) {
	throw new Error(`The \`source(${compiler.root.pattern})\` does not exist`)
	}
	}
	}

Seems like slightly different logic, perhaps source() in this validation function is checked relative to the "root" CSS file?

[hyperknot]

Yes, @import "tailwindcss" source("../../") works, but it picks up the wrong file as well with the bg-red.

That's why grep bg- should be used for verification.

[wongjn]

Yep, that was to test the file resolution when scanning. Thus, we could presume that source("../../components"); should work, if not for the validation error beforehand.