[12.x] Updating the Pulse Card TailwindCSS v3 configuration to TailwindCSS v4

[rozsazoltan]

Instead of @tailwind, a single @import is used.

- @tailwind base;
- @tailwind components;
- @tailwind utilities;
+ @import "tailwindcss";

But because of the previous "important strategy" (v3), a long import was required (with CSS selector - v4). The "important strategy" has been removed; only an appropriate CSS selector is needed. For this reason, there is no need for a config file at all; instead, the longer import must be done in the CSS file:

- @import "tailwindcss";
+ @layer theme, base, components, utilities;
+ @import "tailwindcss/theme.css" layer(theme);
+ @import "tailwindcss/preflight.css" layer(base);
+ @layer utilities {
+   #top-sellers {
+     @tailwind utilities;
+   }
+ }

Example:

• https://play.tailwindcss.com/LSlrcFtTkK?file=css

Reference:

• https://v3.tailwindcss.com/docs/configuration#selector-strategy (v3)
• Tailwind v4 has no `important` option support tailwindlabs/tailwindcss#15866 (comment) (v4)

To disable Preflight, we simply need to omit importing Preflight:

  @layer theme, base, components, utilities;
  @import "tailwindcss/theme.css" layer(theme);
- @import "tailwindcss/preflight.css" layer(base);
  @layer utilities {
    #top-sellers {
      @tailwind utilities;
    }
  }

Reference:

• https://tailwindcss.com/docs/preflight#disabling-preflight

For many developers, it might be unusual to work without a config file, so I would like to mention @theme.

Also, although TailwindCSS automatically discovers the necessary files, you can use @source to force certain folders or files with a relative path, which is why I added the path leading to the views.

The dark: variant related to dark mode can be overridden in CSS instead of darkMode: "class",, like this:

@custom-variant dark (&:where(.dark, .dark *));

Reference:

• https://tailwindcss.com/docs/dark-mode#toggling-dark-mode-manually

[taylorotwell]

Does it matter that Pulse still uses Tailwind 3?

[jessarcher]

Does it matter that Pulse still uses Tailwind 3?

I don't think it matters what version Pulse uses because we ship compiled CSS.

[jessarcher]

According to https://tailwindcss.com/docs/upgrade-guide#removed-tailwind-directives, the @tailwind was removed.

I believe this would be the equivalent?

Suggested change

	@tailwind utilities;
	@import "tailwindcss/utilities.css" layer(utilities);

[rozsazoltan]

`@tailwind utilities;`

Basically, this is the guidance. Only @tailwind utilities; remains, but in that case the result is not placed into the utilities layer; however, this way it can be nested under your own CSS selector, similar to how the v3 important strategy would have generated it.

• @tailwind utilities; with #top-sellers selector

@layer theme, base, components, utilities;

@import "tailwindcss/theme.css" layer(theme);

@layer utilities {
  #top-sellers {
    @tailwind utilities;
  }
}

• @import "tailwindcss/utilities.css" layer(utilities); with #top-sellers selector - Then the utilities layer will not be placed at the root level. In this case, the actual layer became utilities.utilities.

@layer theme, base, components, utilities;

@import "tailwindcss/theme.css" layer(theme);

@layer utilities {
  #top-sellers {
    @import "tailwindcss/utilities.css" layer(utilities);
  }
}

Note

I overthought it… Yes, it actually works with @import in the correct layer. I didn't test it when writing the PR, but now I managed to manually place it into two layers.

However, I rushed the PR; Pulse itself is using v3. And in v3, TailwindCSS did not yet prioritize the use of layers. Therefore, the CSS generated by v3 will always remain stronger than the CSS generated by v4, and the only way to work around this is to avoid using layers in v4 as well. Since we are not shipping preflight, that part is not an issue, but the v3 setup will take precedence.

(TailwindCSS v3 generated CSS without utilities layer)

Thus, the previously mentioned layer problem is no longer an issue, so yes - we can use @import in order not to cause confusion in understanding how it all works.

• @import "tailwindcss/utilities.css" layer(utilities); with #top-sellers selector without layers

@import "tailwindcss/theme.css";

#top-sellers {
  @import "tailwindcss/utilities.css";
}

(TailwindCSS v4 generated CSS without utilities layer)

If I understood correctly, in v3 the important selector strategy was recommended because, due to configuration differences between Pulse's own setup and the card-related configuration, it could happen that a utility existed twice but with different settings. If we don't insist on a selector like #top-sellers, then it can be omitted, and the installation looks like this without Preflight.

@import "tailwindcss/theme.css";
@import "tailwindcss/utilities.css";

In v4, by default it tries to locate the project root (where the .git folder is) and maps almost everything within it, which is a disadvantage in the case of card-specific separated generated CSS and needs to be disabled. This can be done with source(none). Similarly, you need to manually add the single card source with @source, like the v3 content property:

@import "tailwindcss/theme.css";
#top-sellers {
  @import "tailwindcss/utilities.css" source(none);
}

@source "./../../views/livewire/pulse/top-sellers.blade.php";

(Assuming the file is placed at resources/css/pulse/top-sellers.css as per the docs.)

References:

• https://tailwindcss.com/docs/detecting-classes-in-source-files#disabling-automatic-detection

In the meantime I checked it, and even with @tailwind utilities; the disablement is still source(none); but since I've concluded that using @import "tailwindcss/utilities.css"; is appropriate instead, the use of source(none) is documented there.

[rozsazoltan]

So, I made the modifications: I omitted the layers, disabled source detection: rozsazoltan@aa8b388

@import "tailwindcss/theme.css";

@custom-variant dark (&:where(.dark, .dark *));
@source "./../../views/livewire/pulse/top-sellers.blade.php";

@theme {
  /* ... */
}

#top-sellers {
  @import "tailwindcss/utilities.css" source(none);
}

[rozsazoltan]

Does it matter that Pulse still uses Tailwind 3?

It doesn't matter, since we are assembling a dedicated generated CSS specifically for the custom card. However, this dedicated CSS is compiled by the Laravel app, where developers will already be using v4 by default, so the v3 recommendations will not yield the correct result there when try generate this.

However, it does matter in that v3 does not rely on CSS layers, so the CSS for the custom card should not use them either, which slightly simplifies the configuration, see:

• [12.x] Updating the Pulse Card TailwindCSS v3 configuration to TailwindCSS v4 #10926 (comment)

@import "tailwindcss/theme.css";
#top-sellers {
  @import "tailwindcss/utilities.css" source(none);
}

@source "./../../views/livewire/pulse/top-sellers.blade.php";

I'm not sure whether it will cause an issue that the v3 Preflight will be the one in effect. I don't think it should cause any problems. For example, I transferred the v3 Preflight into a v4 example, and it seems we get good results with it as well. This is relevant because Pulse provides the Preflight, which we can no longer provide in v4, and I'm not convinced - I can only assume - that it would need to contain similar rules.

• v4 example selector with v3's Preflight
• v4 example with #top-sellers selector with v3's Preflight