Merge pull request #15560 from filamentphp/tailwind-v4

Add notes about incompatibility with Tailwind v4

packages/actions/docs/01-installation.md

@@ -11,6 +11,7 @@ Filament requires the following to run:
 - PHP 8.1+
 - Laravel v10.0+
 - Livewire v3.0+
+- Tailwind v3.0+ [(Using Tailwind v4?)](#installing-tailwind-css)
 
 ## Installation
 
@@ -44,6 +45,8 @@ php artisan filament:install --actions
 
 ### Installing Tailwind CSS
 
+> Filament uses Tailwind CSS v3 for styling. If your project uses Tailwind CSS v4, you will unfortunately need to downgrade it to v3 to use Filament. Filament v3 can't support Tailwind CSS v4 since it introduces breaking changes. Filament v4 will support Tailwind CSS v4.
+
 Run the following command to install Tailwind CSS with the Tailwind Forms and Typography plugins:
 
 ```bash

packages/forms/docs/01-installation.md

@@ -11,6 +11,7 @@ Filament requires the following to run:
 - PHP 8.1+
 - Laravel v10.0+
 - Livewire v3.0+
+- Tailwind v3.0+ [(Using Tailwind v4?)](#installing-tailwind-css)
 
 ## Installation
 
@@ -44,6 +45,8 @@ php artisan filament:install --forms
 
 ### Installing Tailwind CSS
 
+> Filament uses Tailwind CSS v3 for styling. If your project uses Tailwind CSS v4, you will unfortunately need to downgrade it to v3 to use Filament. Filament v3 can't support Tailwind CSS v4 since it introduces breaking changes. Filament v4 will support Tailwind CSS v4.
+
 Run the following command to install Tailwind CSS with the Tailwind Forms and Typography plugins:
 
 ```bash

packages/infolists/docs/01-installation.md

@@ -11,6 +11,7 @@ Filament requires the following to run:
 - PHP 8.1+
 - Laravel v10.0+
 - Livewire v3.0+
+- Tailwind v3.0+ [(Using Tailwind v4?)](#installing-tailwind-css)
 
 ## Installation
 
@@ -44,6 +45,8 @@ php artisan filament:install --infolists
 
 ### Installing Tailwind CSS
 
+> Filament uses Tailwind CSS v3 for styling. If your project uses Tailwind CSS v4, you will unfortunately need to downgrade it to v3 to use Filament. Filament v3 can't support Tailwind CSS v4 since it introduces breaking changes. Filament v4 will support Tailwind CSS v4.
+
 Run the following command to install Tailwind CSS with the Tailwind Forms and Typography plugins:
 
 ```bash

packages/notifications/docs/01-installation.md

@@ -11,6 +11,7 @@ Filament requires the following to run:
 - PHP 8.1+
 - Laravel v10.0+
 - Livewire v3.0+
+- Tailwind v3.0+ [(Using Tailwind v4?)](#installing-tailwind-css)
 
 Require the Notifications package using Composer:
 
@@ -42,6 +43,8 @@ php artisan filament:install --notifications
 
 ### Installing Tailwind CSS
 
+> Filament uses Tailwind CSS v3 for styling. If your project uses Tailwind CSS v4, you will unfortunately need to downgrade it to v3 to use Filament. Filament v3 can't support Tailwind CSS v4 since it introduces breaking changes. Filament v4 will support Tailwind CSS v4.
+
 Run the following command to install Tailwind CSS with the Tailwind Forms and Typography plugins:
 
 ```bash

packages/panels/docs/12-themes.md

@@ -111,6 +111,10 @@ Filament allows you to change the CSS used to render the UI by compiling a custo
 
 Themes use [Tailwind CSS](https://tailwindcss.com), the Tailwind Forms plugin, the Tailwind Typography plugin, the [PostCSS Nesting plugin](https://www.npmjs.com/package/postcss-nesting), and [Autoprefixer](https://github.com/postcss/autoprefixer).
 
+> Filament v3 uses Tailwind CSS v3 for styling. As such, when creating a theme, you need to use Tailwind CSS v3. The `php artisan make:filament-theme` command will install Tailwind CSS v3 if you do not have it installed already. If you have Tailwind CSS v4 installed, it will not fully install the necessary Vite configuration to compile the theme. We suggest that you either use the Tailwind CLI to compile the theme, or downgrade your project to Tailwind CSS v3. The command to compile the theme with the Tailwind CLI will be output when you run the `make:filament-theme` command. You could save this command into a script in `package.json` for easy use.
+> 
+> Filament v4 will support Tailwind CSS v4.
+
 To create a custom theme for a panel, you can use the `php artisan make:filament-theme` command:
 
 ```bash
@@ -139,6 +143,14 @@ The command will create a CSS file and Tailwind Configuration file in the `/reso
 
 Please reference the command to see the exact file names that you need to register, they may not be `admin/theme.css`.
 
+If you have Tailwind v4 installed, the output may look like this:
+
+```
+⇂ It looks like you have Tailwind v4 installed. Filament uses Tailwind v3. You should downgrade your project and re-run this command with `--force`, or use the following command to compile the theme with the Tailwind v3 CLI:
+⇂ npx tailwindcss@3 --input ./resources/css/filament/admin/theme.css --output ./public/css/filament/admin/theme.css --config ./resources/css/filament/admin/tailwind.config.js --minify
+⇂ Make sure to register the theme in the admin panel provider using `->theme(asset('css/filament/admin/theme.css'))`
+```
+
 ## Disabling dark mode
 
 To disable dark mode switching, you can use the [configuration](configuration) file:

packages/panels/src/Commands/MakeThemeCommand.php

@@ -23,24 +23,33 @@ class MakeThemeCommand extends Command
 
     public function handle(): int
     {
-        $pm = $this->option('pm') ?? 'npm';
+        $packageJson = file_get_contents(base_path('package.json')) ?: '';
 
-        exec("{$pm} -v", $pmVersion, $pmVersionExistCode);
+        $isTailwindV4Installed = str_contains($packageJson, '"@tailwindcss/postcss": "^4')
+            || str_contains($packageJson, '"@tailwindcss/postcss": "4')
+            || str_contains($packageJson, '"tailwindcss": "^4')
+            || str_contains($packageJson, '"tailwindcss": "4');
 
-        if ($pmVersionExistCode !== 0) {
-            $this->error('Node.js is not installed. Please install before continuing.');
+        if (! $isTailwindV4Installed) {
+            $pm = $this->option('pm') ?? 'npm';
 
-            return static::FAILURE;
-        }
+            exec("{$pm} -v", $pmVersion, $pmVersionExistCode);
+
+            if ($pmVersionExistCode !== 0) {
+                $this->error('Node.js is not installed. Please install before continuing.');
+
+                return static::FAILURE;
+            }
 
-        $this->info("Using {$pm} v{$pmVersion[0]}");
+            $this->info("Using {$pm} v{$pmVersion[0]}");
 
-        $installCommand = match ($pm) {
-            'yarn' => 'yarn add',
-            default => "{$pm} install",
-        };
+            $installCommand = match ($pm) {
+                'yarn' => 'yarn add',
+                default => "{$pm} install",
+            };
 
-        exec("{$installCommand} tailwindcss@3 @tailwindcss/forms @tailwindcss/typography postcss postcss-nesting autoprefixer --save-dev");
+            exec("{$installCommand} tailwindcss@3 @tailwindcss/forms @tailwindcss/typography postcss postcss-nesting autoprefixer --save-dev");
+        }
 
         $panel = $this->argument('panel');
 
@@ -93,12 +102,23 @@ public function handle(): int
 
         $this->components->info("Filament theme [resources/css/filament/{$panelId}/theme.css] and [resources/css/filament/{$panelId}/tailwind.config.js] created successfully.");
 
+        if ($isTailwindV4Installed) {
+            $this->components->warn('Action is required to complete the theme setup:');
+            $this->components->bulletList([
+                'It looks like you have Tailwind v4 installed. Filament uses Tailwind v3. You should downgrade your project and re-run this command with `--force`, or use the following command to compile the theme with the Tailwind v3 CLI:',
+                "npx tailwindcss@3 --input ./resources/css/filament/{$panelId}/theme.css --output ./public/css/filament/{$panelId}/theme.css --config ./resources/css/filament/{$panelId}/tailwind.config.js --minify",
+                "Make sure to register the theme in the {$panelId} panel provider using `->theme(asset('css/filament/{$panelId}/theme.css'))`",
+            ]);
+
+            return static::SUCCESS;
+        }
+
         if (empty(glob(base_path('vite.config.*s')))) {
             $this->components->warn('Action is required to complete the theme setup:');
             $this->components->bulletList([
                 "It looks like you don't have Vite installed. Please use your asset bundling system of choice to compile `resources/css/filament/{$panelId}/theme.css` into `public/css/filament/{$panelId}/theme.css`.",
                 "If you're not currently using a bundler, we recommend using Vite. Alternatively, you can use the Tailwind CLI with the following command:",
-                "npx tailwindcss --input ./resources/css/filament/{$panelId}/theme.css --output ./public/css/filament/{$panelId}/theme.css --config ./resources/css/filament/{$panelId}/tailwind.config.js --minify",
+                "npx tailwindcss@3 --input ./resources/css/filament/{$panelId}/theme.css --output ./public/css/filament/{$panelId}/theme.css --config ./resources/css/filament/{$panelId}/tailwind.config.js --minify",
                 "Make sure to register the theme in the {$panelId} panel provider using `->theme(asset('css/filament/{$panelId}/theme.css'))`",
             ]);
 

packages/panels/stubs/ThemeCss.stub

@@ -1,3 +1,3 @@
-@import '/vendor/filament/filament/resources/css/theme.css';
+@import '../../../../vendor/filament/filament/resources/css/theme.css';
 
 @config 'tailwind.config.js';

packages/support/src/Commands/InstallCommand.php

@@ -139,6 +139,7 @@ protected static function updateNpmPackageArray(array $packages): array
             'postcss-nesting' => '^13.0.0',
             'tailwindcss' => '^3.1',
             ...Arr::except($packages, [
+                '@tailwindcss/postcss',
                 'axios',
                 'lodash',
             ]),

packages/tables/docs/01-installation.md

@@ -11,6 +11,7 @@ Filament requires the following to run:
 - PHP 8.1+
 - Laravel v10.0+
 - Livewire v3.0+
+- Tailwind v3.0+ [(Using Tailwind v4?)](#installing-tailwind-css)
 
 ## Installation
 
@@ -44,6 +45,8 @@ php artisan filament:install --tables
 
 ### Installing Tailwind CSS
 
+> Filament uses Tailwind CSS v3 for styling. If your project uses Tailwind CSS v4, you will unfortunately need to downgrade it to v3 to use Filament. Filament v3 can't support Tailwind CSS v4 since it introduces breaking changes. Filament v4 will support Tailwind CSS v4.
+
 Run the following command to install Tailwind CSS with the Tailwind Forms and Typography plugins:
 
 ```bash

packages/widgets/docs/01-installation.md

@@ -11,6 +11,7 @@ Filament requires the following to run:
 - PHP 8.1+
 - Laravel v10.0+
 - Livewire v3.0+
+- Tailwind v3.0+ [(Using Tailwind v4?)](#installing-tailwind-css)
 
 ## Installation
 
@@ -44,6 +45,8 @@ php artisan filament:install --widgets
 
 ### Installing Tailwind CSS
 
+> Filament uses Tailwind CSS v3 for styling. If your project uses Tailwind CSS v4, you will unfortunately need to downgrade it to v3 to use Filament. Filament v3 can't support Tailwind CSS v4 since it introduces breaking changes. Filament v4 will support Tailwind CSS v4.
+
 Run the following command to install Tailwind CSS with the Tailwind Forms and Typography plugins:
 
 ```bash