add notes for tailwind3/4 compatibility

CHANGELOG.md

@@ -1,5 +1,14 @@
 # CHANGELOG
 
+## v0.3.0
+
+Support tailwindcss v4+. This release drops official support for tailwindcss v3.
+If you want to continue using tailwindcss 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,7 +30,7 @@ then it only needs to be a dev dependency:
 ```elixir
 def deps do
   [
-    {:tailwind, "~> 0.2", only: :dev}
+    {:tailwind, "~> 0.3", only: :dev}
   ]
 end
 ```
@@ -42,6 +42,14 @@ tailwind version of choice:
 config :tailwind, version: "4.0.0"
 ```
 
+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
@@ -91,7 +99,11 @@ 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+
+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.
+
+To add Tailwind v4 to an application using Phoenix, you will need Phoenix v1.6+
 and the following steps.
 
 First add it as a dependency in your `mix.exs`:
@@ -100,7 +112,7 @@ First add it as a dependency in your `mix.exs`:
 def deps do
   [
     {:phoenix, "~> 1.7"},
-    {:tailwind, "~> 0.2.4", runtime: Mix.env() == :dev}
+    {:tailwind, "~> 0.3", runtime: Mix.env() == :dev}
   ]
 end
 ```
@@ -165,6 +177,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.