Merge pull request #110 from phoenixframework/sd-tailwind3to4

add notes for tailwind3/4 compatibility

Author: SteffenDE

CHANGELOG.md

@@ -1,5 +1,14 @@
 # CHANGELOG
 
+## v0.3.0
+
+Support Tailwind v4+. This release drops official support for Tailwind v3.
+If you want to continue using Tailwind v3, please pin the `tailwind` dependency to a 0.2 version:
+
+```elixir
+{:tailwind, "~> 0.2.0", only: :dev}`
+```
+
 ## v0.2.4 (2024-10-18)
 
 * Add version check flag

README.md

@@ -19,7 +19,7 @@ in dev:
 ```elixir
 def deps do
   [
-    {:tailwind, "~> 0.2", runtime: Mix.env() == :dev}
+    {:tailwind, "~> 0.3", runtime: Mix.env() == :dev}
   ]
 end
 ```
@@ -30,19 +30,27 @@ then it only needs to be a dev dependency:
 ```elixir
 def deps do
   [
-    {:tailwind, "~> 0.2", only: :dev}
+    {:tailwind, "~> 0.3", only: :dev}
   ]
 end
 ```
 
 Once installed, change your `config/config.exs` to pick your
-tailwind version of choice:
+Tailwind version of choice:
 
 ```elixir
 config :tailwind, version: "4.0.0"
 ```
 
-Now you can install tailwind by running:
+Note that `:tailwind` 0.3+ supports Tailwind v4+. If you need to use Tailwind v3, use
+
+```
+{:tailwind, "~> 0.2.0", only: :dev}
+```
+
+instead, and refer to [the README in the 0.2 branch](https://github.com/phoenixframework/tailwind/blob/v0.2/README.md).
+
+Now you can install Tailwind by running:
 
 ```bash
 $ mix tailwind.install
@@ -56,7 +64,7 @@ you can supply a third party path to the binary the installer wants
 $ mix tailwind.install https://people.freebsd.org/~dch/pub/tailwind/v3.2.6/tailwindcss-freebsd-x64
 ```
 
-And invoke tailwind with:
+And invoke Tailwind with:
 
 ```bash
 $ mix tailwind default
@@ -91,16 +99,18 @@ to the ones configured above. Note profiles must be configured in your
 
 ## Adding to Phoenix
 
-To add `tailwind` to an application using Phoenix, you will need Phoenix v1.6+
-and the following steps.
+Note that applications generated with Phoenix older than 1.8 still use Tailwind v3 by default.
+If you're using Tailwind v3 please refer to [the README in the v0.2 branch](https://github.com/phoenixframework/tailwind/blob/v0.2/README.md#adding-to-phoenix)
+instead.
 
-First add it as a dependency in your `mix.exs`:
+To add Tailwind v4 to an application using Phoenix, first add this package
+as a dependency in your `mix.exs`:
 
 ```elixir
 def deps do
   [
     {:phoenix, "~> 1.7"},
-    {:tailwind, "~> 0.2.4", runtime: Mix.env() == :dev}
+    {:tailwind, "~> 0.3", runtime: Mix.env() == :dev}
   ]
 end
 ```
@@ -165,6 +175,56 @@ right away. It also generates a default configuration file called
 when we configured `tailwind` in `config/config.exs`. See
 `mix help tailwind.install` to learn more.
 
+## Updating from Tailwind v3 to v4
+
+For a typical Phoenix application, updating from Tailwind v3 to v4 requires the following steps:
+
+1.  Update the `:tailwind` library to version 0.3+
+  
+    ```diff
+     defp deps do
+       [
+    -    {:tailwind, "~> 0.2", runtime: Mix.env() == :dev},
+    +    {:tailwind, "~> 0.3", runtime: Mix.env() == :dev},
+       ]
+     end
+    ```
+
+2.  Adjust the configuration to run Tailwind from the root of your repo (or the web app in an umbrella project):
+
+    ```diff
+     config :tailwind,
+    -   version: "3.4.13",
+    +   version: "4.0.0",
+        default: [
+          args: ~w(
+    -       --config=tailwind.config.js
+    -       --input=css/app.css
+    -       --output=../priv/static/assets/app.css
+    +       --config=assets/tailwind.config.js
+    +       --input=assets/css/app.css
+    +       --output=priv/static/assets/app.css
+         ),
+    -    cd: Path.expand("../assets", __DIR__)
+    +    cd: Path.expand("..", __DIR__)
+      ]
+    ```
+
+    This allows Tailwind to automatically pick up classes from your project. Tailwind v4 does not require explicit configuration of sources.
+
+3.  Adjust the Tailwind imports in your app.css
+
+    ```diff
+    -@import "tailwindcss/base";
+    -@import "tailwindcss/components";
+    -@import "tailwindcss/utilities";
+    +@import "tailwindcss";
+    ```
+
+4.  Follow the [Tailwind v4 upgrade guide](https://tailwindcss.com/docs/upgrade-guide) to address deprecations.
+
+5.  Optional: remove the `tailwind.config.js` and switch to the new CSS based configuration. For more information, see the previously mentioned upgrade guide and the [documentation on functions and directives](https://tailwindcss.com/docs/functions-and-directives).
+
 ## License
 
 Copyright (c) 2022 Chris McCord.