From 8f203bfda3aee735df21b131d93f9722f9bb4710 Mon Sep 17 00:00:00 2001
From: Bjorn Lu <bjornlu.dev@gmail.com>
Date: Tue, 22 Nov 2022 01:42:45 +0800
Subject: [PATCH] Update tailwindcss `@apply` suggestion (#5406)

Co-authored-by: Chris Swithinbank <swithinbank@gmail.com>
---
 packages/integrations/tailwind/README.md | 35 +++++++++++++++++++-----
 1 file changed, 28 insertions(+), 7 deletions(-)

diff --git a/packages/integrations/tailwind/README.md b/packages/integrations/tailwind/README.md
index 1494928cb..8c1f56416 100644
--- a/packages/integrations/tailwind/README.md
+++ b/packages/integrations/tailwind/README.md
@@ -127,7 +127,25 @@ export default {
 
 You can now [import your own `base.css` as a local stylesheet](https://docs.astro.build/en/guides/styling/#import-a-local-stylesheet).
 
-If you are using Vue, Svelte, or another component integration with Astro, `@apply` directives used in component `<style>`s may generate errors about your custom Tailwind class not existing and cause your builds to fail. [Instead of using `@layer` directives in a a global stylesheet](https://tailwindcss.com/docs/functions-and-directives#using-apply-with-per-component-css), define your custom styles by adding a plugin to your Tailwind config:
+## Examples
+
+- The [Astro Tailwind Starter](https://github.com/withastro/astro/tree/latest/examples/with-tailwindcss?on=github) gets you up and running with a base for your project that uses Tailwind for styling
+- Astro's homepage uses Tailwind. Check out its [Tailwind configuration file](https://github.com/withastro/astro.build/blob/main/tailwind.config.cjs) or an [example component](https://github.com/withastro/astro.build/blob/main/src/components/IntegrationCard.astro)
+- The [Astro Ink](https://github.com/one-aalam/astro-ink), [Sarissa Blog](https://github.com/iozcelik/SarissaBlogAstroStarter), and [Creek](https://github.com/robertguss/Astro-Theme-Creek) themes use Tailwind for styling
+- [Browse Astro Tailwind projects on GitHub](https://github.com/search?q=%22%40astrojs%2Ftailwind%22+filename%3Apackage.json&type=Code) for more examples!
+
+## Troubleshooting
+
+### Class does not exist with `@apply` directives
+
+When using the `@apply` directive in an Astro, Vue, Svelte, or another component integration's `<style>` tag, it may generate errors about your custom Tailwind class not existing and cause your build to fail.
+
+```
+error   The `text-special` class does not exist. If `text-special` is a custom class, make sure it is defined within a `@layer` directive.
+```
+
+[Instead of using `@layer` directives in a global stylesheet](https://tailwindcss.com/docs/functions-and-directives#using-apply-with-per-component-css), define your custom styles by adding a plugin to your Tailwind config to fix it:
+
 
 ```js
 // tailwind.config.cjs
@@ -146,14 +164,17 @@ module.exports = {
 }
 ```
 
-## Examples
+### Class-based modifiers do not work with `@apply` directives
 
-- The [Astro Tailwind Starter](https://github.com/withastro/astro/tree/latest/examples/with-tailwindcss?on=github) gets you up and running with a base for your project that uses Tailwind for styling
-- Astro's homepage uses Tailwind. Check out its [Tailwind configuration file](https://github.com/withastro/astro.build/blob/main/tailwind.config.cjs) or an [example component](https://github.com/withastro/astro.build/blob/main/src/components/IntegrationCard.astro)
-- The [Astro Ink](https://github.com/one-aalam/astro-ink), [Sarissa Blog](https://github.com/iozcelik/SarissaBlogAstroStarter), and [Creek](https://github.com/robertguss/Astro-Theme-Creek) themes use Tailwind for styling
-- [Browse Astro Tailwind projects on GitHub](https://github.com/search?q=%22%40astrojs%2Ftailwind%22+filename%3Apackage.json&type=Code) for more examples!
+Certain Tailwind classes with modifiers rely on combining classes across multiple elements. For example, `group-hover:text-gray` compiles to `.group:hover .text-gray`. When this is used with the `@apply` directive in Astro `<style>` tags, the compiled styles are removed from the build output because they do not match any markup in the `.astro` file. The same issue may also happen in framework components that support scoped styles like Vue and Svelte.
+
+To fix this, you can use inline classes instead:
+
+```astro
+<p class="text-black group-hover:text-gray">Astro</p>
+
+### Others
 
-## Troubleshooting
 - If your installation doesn't seem to be working, try restarting the dev server.
 - If you edit and save a file and don't see your site update accordingly, try refreshing the page.
 - If refreshing the page doesn't update your preview, or if a new installation doesn't seem to be working, then restart the dev server.