You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This guide is a work in progress. Please check in later this week to see how you can help.
5
-
Thank you!
5
+
# TailwindCSS 4 Migration Guide
6
+
7
+
## Overview
8
+
With the upcoming release of Avo `3.19.0` in 1 April 2025 and no, this is not an April Fools' joke 😄, the framework will fully transition to TailwindCSS 4. To facilitate a smooth migration process, Avo `3.18.x` (which uses TailwindCSS 3) will continue to be maintained alongside a parallel version, `3.18.x.tw4`, which incorporates TailwindCSS 4.
9
+
10
+
**We strongly encourage you to utilize the `3.18.x.tw4` version as a testing ground for the migration. By doing so, you can identify potential issues, provide feedback, and ensure a seamless transition before the official release of Avo `3.19.0` in 1 April 2025.**
11
+
12
+
This guide outlines the necessary steps to migrate to TailwindCSS 4, addressing two distinct scenarios:
13
+
14
+
1.**Projects without a TailwindCSS pipeline**
15
+
- These setups do not have an existing TailwindCSS configuration
16
+
- This is the case for most projects
17
+
- There isn't much action to take
18
+
2.**Projects with an existing TailwindCSS pipeline**
19
+
- These projects already utilize TailwindCSS.
20
+
- Will need to adjust their configurations accordingly.
21
+
22
+
Each of these cases will be discussed in detail in their respective sections.
23
+
24
+
:::warning
25
+
Additionally, a dedicated section highlights [breaking changes](#tailwindcss-4-breaking-changes) that apply universally, regardless of your current TailwindCSS setup. Understanding these changes is crucial to ensure compatibility and avoid disruptions.
6
26
:::
7
27
8
-
## You don't have a TailwindCSS pipeline
28
+
Proceed to the following sections to determine the appropriate migration path for your project.
29
+
30
+
## Use the `3.18.x.tw4` version
31
+
32
+
:::info
33
+
`x` is the patch version, it can be `0`, `1`, `2`, etc., depending on the number of patch releases in the `3.18` minor version.
34
+
35
+
Each patch release will have both the TailwindCSS 3 and the TailwindCSS 4 versions of the gem.
36
+
37
+
Example:
38
+
39
+
```bash
40
+
# 3.18.0
41
+
# TailwindCSS 3 version
42
+
gem "avo", "3.18.0"
43
+
# TailwindCSS 4 version
44
+
gem "avo", "3.18.0.tw4"
9
45
10
-
:::warning 🚧 This guide is still in progress, but here are the basics in order to test TailwindCSS 4.
46
+
# 3.18.1
47
+
# TailwindCSS 3 version
48
+
gem "avo", "3.18.1"
49
+
# TailwindCSS 4 version
50
+
gem "avo", "3.18.1.tw4"
51
+
```
11
52
:::
12
53
13
54
To test TailwindCSS 4, ensure you are using the following versions:
14
55
56
+
```bash
57
+
gem "avo", "3.18.x.tw4"
58
+
```
59
+
15
60
If you're utilizing `avo-rhino_field`, you must lock its version to `0.0.12.tw4`.
To report any issue please use [this PR](https://github.com/avo-hq/avo/pull/3632).
80
+
To report any issue please leave a comment [here](https://github.com/avo-hq/avo/pull/3632).
81
+
82
+
## Projects without a TailwindCSS pipeline
83
+
84
+
If you don't have a TailwindCSS pipeline, which should be the case for most cases, there isn't much to do besides following the steps in the [Use the `3.18.x.tw4` version](#use-the-3-18-x-tw4-version) section and address the [TailwindCSS 4 breaking changes](#tailwindcss-4-breaking-changes) below.
85
+
86
+
After, you can use the `3.18.x.tw4` version of the gem and it will work just fine and ready for the Avo `3.19.0` release.
87
+
36
88
37
89
## You do have a TailwindCSS pipeline
38
90
39
91
[WIP]
40
92
93
+
## TailwindCSS 4 breaking changes
41
94
95
+
TailwindCSS 4 introduces several breaking changes that might affect your application. While we highlight some common changes below, we strongly recommend reviewing the [official TailwindCSS 4 upgrade guide](https://tailwindcss.com/docs/upgrade-guide) for a comprehensive list of changes.
96
+
97
+
You need to apply this changes on all the Avo related custom components that you have in your application. That includes:
98
+
99
+
- Custom fields
100
+
- Resource tools
101
+
- Custom tools
102
+
- Custom cards
103
+
- Ejected components
104
+
105
+
### Renamed Utilities
106
+
107
+
TailwindCSS 4 has renamed several utilities to make them more consistent and predictable.
108
+
109
+
We'll highlight the most common use-case encountered in the Avo codebase, please refer to the whole [Renamed Utilities list](https://tailwindcss.com/docs/upgrade-guide#renamed-utilities) for more details.
If you're applying global search and bulk replace do the `rounded-sm` to `rounded-xs` transition first, then do the `rounded` to `rounded-sm` transition.
133
+
:::
134
+
135
+
### Default Border Color
136
+
137
+
In TailwindCSS 4, the default border color has changed from `gray-200` to `currentColor`. This affects both `border-*` and `divide-*` utilities. You'll need to explicitly specify border colors where you previously relied on the default.
Do a global search for `border` and `divide` and verify where they have any implicit color borders. Add the `border-gray-200` and `divide-gray-200` classes to the elements that don't have an explicit color.
0 commit comments