[v4] Docs on tailwind.config.js and @config

[DrLightman]

Hi, I'm pretty new to the tool and I'm using tailwindcss/cli as watcher.

Where I can find the docs about the popular tailwind.config.js configuration file and how to use it? I'm interested in configuring the cli utility to watch specific paths in my project.

Also, PhpStorm complains that @import directive must be at the top of the file, therefore I'd have to put @config for last, is that correct?

@import "tailwindcss";
@import "./my-base.css";
@config "../tailwind.config.js";

...

Thank you.

[wongjn]

Using tailwind.config.js won't help you in configuring specific watch paths in your project. The CLI should automatically watch your project paths for you.

[DrLightman]

How it decides? From where I launch it, it scans every files and dirs recursively?

[wongjn]

As per the documentation:

Which files are scanned

Tailwind will scan every file in your project for class names, except in the following cases:

• Files that are in your .gitignore file
• Binary files like images, videos, or zip files
• CSS files
• Common package manager lock files

If you need to scan any files that Tailwind is ignoring by default, you can explicitly register those sources.

[DrLightman]

does it also supports .git/info/exclude ?

[wongjn]

Yes, I think so. Tailwind uses the ignore crate under the hood for file matching. In the source code for ignore, there seems to be a test for .git/info/exclude.

[robaetem]

You can still use the tailwind.config.js file in tailwindcss v4. I had to configure it because tailwindcss did not take all my files automatically.

For me it looked like this:

/** @type {import('tailwindcss').Config} */
export default {
  content: [
    "./src/**/*.{js,ts,jsx,tsx}",
    "TYPE YOUR CUSTOM PATH HERE"
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}
```

[alex-x-x-x-x]

@DrLightman I had the same issue a few days ago. If you REALLY need a tailwind.config.js file but don't want to create it manually there's a workaround by downgrading to v3 and then upgrading back to v4.

npm uninstall tailwindcss 
npm install -D tailwindcss@3
npx tailwindcss init -p
# then upgrade to the latest version
npm install -D tailwindcss@latest

This way, you get the default tailwind.config.js file generated for you, and you can still use it in Tailwind v4.

On a similar note, as @wongjn mentioned, Tailwind has moved towards a CSS-first configuration approach. By default, Tailwind will still work without a config file. It assumes the default settings and scans files based on its built-in logic, and if you need a config file (and you're not running the above commands I shared), you'll have to manually create one.

For some reason the documentation doesn't really specify this, but I think the assumption is that most users that use TailwindCSS in their projects are familiar enough to know this and are upgrading from previous versions.

Also, the new @theme directive lets you configure Tailwind styles directly in CSS without extra files.

TL;DR

• Tailwind v4 doesn’t auto-generate tailwind.config.js because it favors a CSS-first approach.
• If you don’t have a config file, Tailwind still works—using its defaults.
• You only need tailwind.config.js for advanced customization (plugins, themes, content paths, etc.).
• If you want one generated for you, downgrade to v3, run npx tailwindcss init -p, then upgrade back to v4.

Also, PhpStorm complains that https://github.com/import directive must be at the top of the file, therefore I'd have to put https://github.com/config for last, is that correct?

No, you should not put @config last, Tailwind requires @config to be at the top of your CSS file before any @import statements or it won't apply your configuration correctly. To fix the PhpStorm's warning while keeping the correct Tailwind order, you can disable the warning in PhpStorm and it'll still work.

[theDeal]

Hey Guys,

most of you have this Issue because you are using a library or some files Tailwind is not watching.
Tailwind by default now especially with the V4 @tailwind/vite Plugin just watches files in your directory who are not mentioned inside the .gitignore.

But you can use this to still watch these Files.

@source "../node_modules/@my-company/ui-lib";

e.g. if you are using the UI Libary @vonreyher-media/cvrocket to create a stepper form and installed it via npm or pnpm add @vonreyher-media/cvrocket , you can just add this:

@source "../node_modules/@vonreyher-media/cvrocket";

to your CSS and it should work.

[abumalick]

thanks a lot 👍🏻