Skip to content

Improve error message around invalid stylesheets and/or configs #369

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 4 commits into
base: main
Choose a base branch
from
+56 −24
Draft

Improve error message around invalid stylesheets and/or configs #369

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
410c3f3
Tweak error messages
thecrypticace May 30, 2025
c1a655f
Validate the path provided to `tailwindStylesheet`
thecrypticace May 30, 2025
4ca015e
Log when pointing to in invalid Tailwind CSS stylesheet or config
thecrypticace May 30, 2025
4d53841
Report on stylesheet parse errors
thecrypticace Jun 6, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
80 changes: 56 additions & 24 deletions src/config.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -123,12 +123,18 @@ async function loadTailwindConfig(
let pkgFile = resolveJsFrom(baseDir, `${pkgName}/package.json`)
let pkgDir = path.dirname(pkgFile)

// If the user doesn't define an entrypoint then we use the default theme
entryPoint = entryPoint ?? `${pkgDir}/theme.css`

try {
let v4 = await loadV4(baseDir, pkgDir, pkgName, entryPoint)
if (v4) {
return v4
}
} catch {}
let v4 = await loadV4(baseDir, pkgName, entryPoint)
if (v4) return v4
} catch (err) {
console.error(
`Unable to load your Tailwind CSS v4 stylesheet: ${entryPoint}`,
)
console.error(err)
}

resolveConfig = require(path.join(pkgDir, 'resolveConfig'))
createContext = require(
Expand All @@ -142,10 +148,18 @@ async function loadTailwindConfig(
loadConfig = require(path.join(pkgDir, 'loadConfig'))
} catch {}

if (tailwindConfigPath) {
clearModule(tailwindConfigPath)
const loadedConfig = loadConfig(tailwindConfigPath)
tailwindConfig = loadedConfig.default ?? loadedConfig
try {
if (tailwindConfigPath) {
clearModule(tailwindConfigPath)
const loadedConfig = loadConfig(tailwindConfigPath)
tailwindConfig = loadedConfig.default ?? loadedConfig
}
} catch (err) {
console.error(
`Unable to load your Tailwind CSS v3 config: ${tailwindConfigPath}`,
)

throw err
}

// suppress "empty content" warning
Expand Down Expand Up @@ -204,24 +218,14 @@ function createLoader<T>({
}
}

async function loadV4(
baseDir: string,
pkgDir: string,
pkgName: string,
entryPoint: string | null,
) {
async function loadV4(baseDir: string, pkgName: string, entryPoint: string) {
// Import Tailwind — if this is v4 it'll have APIs we can use directly
let pkgPath = resolveJsFrom(baseDir, pkgName)

let tw = await import(pathToFileURL(pkgPath).toString())

// This is not Tailwind v4
if (!tw.__unstable__loadDesignSystem) {
return null
}

// If the user doesn't define an entrypoint then we use the default theme
entryPoint = entryPoint ?? `${pkgDir}/theme.css`
if (!tw.__unstable__loadDesignSystem) return null

// Create a Jiti instance that can be used to load plugins and config files
let jiti = createJiti(import.meta.url, {
Expand All @@ -232,7 +236,9 @@ async function loadV4(
let importBasePath = path.dirname(entryPoint)

// Resolve imports in the entrypoint to a flat CSS tree
let css = await fs.readFile(entryPoint, 'utf-8')
let css: string

css = await fs.readFile(entryPoint, 'utf-8')

// Determine if the v4 API supports resolving `@import`
let supportsImports = false
Expand Down Expand Up @@ -354,20 +360,46 @@ function getConfigPath(options: ParserOptions, baseDir: string): string | null {

function getEntryPoint(options: ParserOptions, baseDir: string): string | null {
if (options.tailwindStylesheet) {
if (
options.tailwindStylesheet.endsWith('.js') ||
options.tailwindStylesheet.endsWith('.mjs') ||
options.tailwindStylesheet.endsWith('.cjs') ||
options.tailwindStylesheet.endsWith('.ts') ||
options.tailwindStylesheet.endsWith('.mts') ||
options.tailwindStylesheet.endsWith('.cts')
) {
console.error(
"Your `tailwindStylesheet` option points to a JS/TS config file. You must point to your project's `.css` file for v4 projects.",
)
} else if (
options.tailwindStylesheet.endsWith('.sass') ||
options.tailwindStylesheet.endsWith('.scss') ||
options.tailwindStylesheet.endsWith('.less') ||
options.tailwindStylesheet.endsWith('.styl')
) {
console.error(
'Your `tailwindStylesheet` option points to a preprocessor file. This is unsupported and you may get unexpected results.',
)
} else if (!options.tailwindStylesheet.endsWith('.css')) {
console.error(
'Your `tailwindStylesheet` option does not point to a CSS file. This is unsupported and you may get unexpected results.',
)
}

return path.resolve(baseDir, options.tailwindStylesheet)
}

if (options.tailwindEntryPoint) {
console.warn(
'Use the `tailwindStylesheet` option for v4 projects instead of `tailwindEntryPoint`.',
'Deprecated: Use the `tailwindStylesheet` option for v4 projects instead of `tailwindEntryPoint`.',
)

return path.resolve(baseDir, options.tailwindEntryPoint)
}

if (options.tailwindConfig && options.tailwindConfig.endsWith('.css')) {
console.warn(
'Use the `tailwindStylesheet` option for v4 projects instead of `tailwindConfig`.',
'Deprecated: Use the `tailwindStylesheet` option for v4 projects instead of `tailwindConfig`.',
)

return path.resolve(baseDir, options.tailwindConfig)
Expand Down