feat: update documentation for tailwind v4

leafsphp · Jan 25, 2025 · 5dd181f · 5dd181f
1 parent 0930615
commit 5dd181f
Showing 1 changed file with 97 additions and 34 deletions.
diff --git a/src/docs/frontend/tailwind.md b/src/docs/frontend/tailwind.md
@@ -4,36 +4,119 @@ Tailwind is a utility-first CSS framework that provides a set of utility classes
 
 ## Using the CLI
 
-You can set up Tailwind CSS in your Leaf project using the Leaf CLI. To do this, run the following command:
+::: warning CLI Installation
+
+Tailwind 4 has been released, and it unfortunately breaks the current Leaf CLI installation. Leaf MVC works fine with Tailwind 4, but we are working on a fix for the CLI. For now, you can install Tailwind manually if you are not using Leaf MVC.
+
+:::
+
+You can set up Tailwind CSS in your Leaf MVC project using the php leaf console. To do this, run the following command:
 
 ::: code-group
 
-```bash:no-line-numbers [Leaf CLI]
+<!-- ```bash:no-line-numbers [Leaf CLI]
 leaf view:install --tailwind
-```
+``` -->
 
 ```bash:no-line-numbers [Leaf MVC CLI]
 php leaf view:install --tailwind
 ```
 
 :::
 
-This command will install Tailwind CSS and its dependencies, create a Tailwind configuration file, and set up your CSS file to import Tailwind CSS. It will also add your CSS file to Vite as an entry point.
+This command will install Tailwind CSS v4 and its dependencies, update your vite file, and set up your CSS file to import Tailwind CSS. It will also add your CSS file to Vite as an entry point. From there, you need to head over to your template file and make sure that you are including the CSS file.
+
+```blade:no-line-numbers
+@vite('css/app.css')
+```
+
+You can then restart your Leaf server and start using Tailwind CSS in your project.
+
+## Manual Installation for TW v4
+
+v4 is now the default version of Tailwind CSS, and it comes with a bunch of new features and improvements, but also has a different setup compared to v3. To get started, you need to install all your frontend dependencies:
+
+```bash:no-line-numbers
+npm install tailwindcss @tailwindcss/vite
+```
+
+And then configure Vite to include the Tailwind plugin:
+
+```js{2,6} [vite.config.js]
+import { defineConfig } from 'vite';
+import tailwindcss from '@tailwindcss/vite';
+
+export default defineConfig({
+  plugins: [
+    tailwindcss(),
+    // …
+  ],
+});
+```
+
+Finally, you need to import Tailwind in your CSS file:
+
+```css [app/views/css/app.css]
+@import "tailwindcss";
+@source "../";
+
+...
+
+```
+
+And then include your CSS file in your layout templates:
+
+```blade{7,12-14}
+<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+
+    @vite('resources/css/app.css')
+
+    ...
+  </head>
+  <body>
+    <h1 class="text-3xl font-bold underline">
+      Hello world!
+    </h1>
+  </body>
+</html>
+```
+
+## Migrating from v3 to v4
+
+If you want to migrate from Tailwind v3 to v4 in Leaf MVC, you can do so by following these steps:
+
+1. Update all your dependencies to the latest version:
+
+```bash:no-line-numbers
+composer update
+```
+
+2. Remove old tailwind config, autoprefixer, and postcss files
+
+3. Run the `view:install` command to install Tailwind v4:
 
-## Using Tailwind
+```bash:no-line-numbers
+php leaf view:install --tailwind
+```
 
-Once setup, Leaf will include all the Tailwind imports which means you can jump into your UI and start writing your components with Tailwind. It also includes the tailwind config in the root of your application. This allows you to define all the configuration for your project if it does not match what Leaf has generated for you.
+4. Update your CSS file to remove @tailwind directives:
 
-You can then go ahead to test out that your Tailwind install works fine:
+```css [app/views/css/app.css]
+@import "tailwindcss";
+@source "../";
 
-```html
-<body>
-  <h1 class="text-4xl text-blue-600">Welcome to Tailwind</h1>
-  <p class="text-center">Leaf is amazing!</p>
-</body>
+@tailwind base; [!code --]
+@tailwind components; [!code --]
+@tailwind utilities; [!code --]
 ```
 
-## Manual Installation
+That's it!
+
+## Manual Installation for TW v3
 
 Leaf MVC comes with Vite out of the box, which is a modern build tool that supports Tailwind CSS out of the box. To get started, you need to install Tailwind CSS and its dependencies:
 
@@ -101,24 +184,4 @@ The final step is to import your CSS file in your root layout file so that it ge
 
 That's it! You now have Tailwind CSS set up in your Leaf project. You can start using Tailwind utility classes in your views to style your UI.
 
-Be sure to start your vite server by running:
-
-::: code-group
-
-```bash:no-line-numbers [Leaf CLI]
-leaf view:dev
-```
-
-```bash:no-line-numbers [npm]
-npm i && npm run dev
-```
-
-```bash:no-line-numbers [pnpm]
-pnpm i && pnpm run dev
-```
-
-```bash:no-line-numbers [yarn]
-yarn && yarn dev
-```
-
-:::
+Be sure to restart your Leaf server so that Leaf can pick up on the new Vite configuration.