-
-
Notifications
You must be signed in to change notification settings - Fork 1.6k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
feat: tailwind v4 #10773
Merged
Merged
feat: tailwind v4 #10773
Changes from all commits
Commits
Show all changes
13 commits
Select commit
Hold shift + click to select a range
a882987
feat: tailwind v4
florian-lefebvre 5b57a5c
Update src/content/docs/en/guides/integrations-guide/tailwind.mdx
florian-lefebvre f1a9c8d
Apply suggestions from sarah tiny edit review
sarah11918 1271380
Merge branch 'main' into feat/tailwind-v4
florian-lefebvre 14a0044
feat: update
florian-lefebvre 91d0018
feat: apply reviews
florian-lefebvre 8e878bf
Merge branch 'main' into feat/tailwind-v4
florian-lefebvre 938a81f
Update src/content/docs/en/guides/styling.mdx
florian-lefebvre c683a5c
Update styling.mdx
florian-lefebvre 2553943
Apply suggestions from Yan final boss code review
sarah11918 8f28cfa
Update src/content/docs/en/guides/styling.mdx
florian-lefebvre 31b2a72
Merge branch 'main' into feat/tailwind-v4
sarah11918 596886a
Merge branch '5.2.0' into feat/tailwind-v4
sarah11918 File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
266 changes: 3 additions & 263 deletions
266
src/content/docs/en/guides/integrations-guide/tailwind.mdx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,271 +1,11 @@ | ||
| --- | ||
| type: integration | ||
| title: '@astrojs/tailwind' | ||
| description: Learn how to use the @astrojs/tailwind integration in your Astro project. | ||
| sidebar: | ||
| label: Tailwind | ||
| githubIntegrationURL: 'https://github.com/withastro/astro/tree/main/packages/integrations/tailwind/' | ||
| category: other | ||
| i18nReady: true | ||
| --- | ||
| import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'; | ||
|
|
||
| This **[Astro integration][astro-integration]** brings [Tailwind's](https://tailwindcss.com/) utility CSS classes to every `.astro` file and [framework component](/en/guides/framework-components/) in your project, along with support for the Tailwind configuration file. | ||
|
|
||
| ## Why Tailwind? | ||
|
|
||
| Tailwind lets you use utility classes instead of writing CSS. These utility classes are mostly one-to-one with a certain CSS property setting: for example, adding the `text-lg` to an element is equivalent to setting `font-size: 1.125rem` in CSS. You might find it easier to write and maintain your styles using these predefined utility classes! | ||
|
|
||
| If you don't like those predefined settings, you can [customize the Tailwind configuration file](https://tailwindcss.com/docs/configuration) to your project's design requirements. For example, if the "large text" in your design is actually `2rem`, you can [change the `lg` fontSize setting](https://tailwindcss.com/docs/font-size#customizing-your-theme) to `2rem`. | ||
|
|
||
| Tailwind is also a great choice to add styles to React, Preact, or Solid components, which don't support a `<style>` tag in the component file. | ||
|
|
||
| Note: it's generally discouraged to use both Tailwind and another styling method (e.g. Styled Components) in the same file. | ||
|
|
||
| ## Installation | ||
|
|
||
| Astro includes an `astro add` command to automate the setup of official integrations. If you prefer, you can [install integrations manually](#manual-install) instead. | ||
|
|
||
| Run one of the following commands in a new terminal window. | ||
|
|
||
| <PackageManagerTabs> | ||
| <Fragment slot="npm"> | ||
| ```sh | ||
| npx astro add tailwind | ||
| ``` | ||
| </Fragment> | ||
| <Fragment slot="pnpm"> | ||
| ```sh | ||
| pnpm astro add tailwind | ||
| ``` | ||
| </Fragment> | ||
| <Fragment slot="yarn"> | ||
| ```sh | ||
| yarn astro add tailwind | ||
| ``` | ||
| </Fragment> | ||
| </PackageManagerTabs> | ||
|
|
||
| If you run into any issues, [feel free to report them to us on GitHub](https://github.com/withastro/astro/issues) and try the manual installation steps below. | ||
|
|
||
| ### Manual Install | ||
|
|
||
| First, install the `@astrojs/tailwind` and `tailwindcss` packages using your package manager. | ||
|
|
||
| <PackageManagerTabs> | ||
| <Fragment slot="npm"> | ||
| ```sh | ||
| npm install @astrojs/tailwind tailwindcss | ||
| ``` | ||
| </Fragment> | ||
| <Fragment slot="pnpm"> | ||
| ```sh | ||
| pnpm add @astrojs/tailwind tailwindcss | ||
| ``` | ||
| </Fragment> | ||
| <Fragment slot="yarn"> | ||
| ```sh | ||
| yarn add @astrojs/tailwind tailwindcss | ||
| ``` | ||
| </Fragment> | ||
| </PackageManagerTabs> | ||
|
|
||
| Then, apply the integration to your Astro config file using the `integrations` property: | ||
|
|
||
| ```js ins={2} ins="tailwind()" title="astro.config.mjs" | ||
| import { defineConfig } from 'astro/config'; | ||
| import tailwind from '@astrojs/tailwind'; | ||
|
|
||
| export default defineConfig({ | ||
| // ... | ||
| integrations: [tailwind()], | ||
| }); | ||
| ``` | ||
|
|
||
| Then, create a `tailwind.config.mjs` file in your project's root directory. You can use the following command to generate a basic configuration file for you: | ||
|
|
||
| <PackageManagerTabs> | ||
| <Fragment slot="npm"> | ||
| ```sh | ||
| npx tailwindcss init | ||
| ``` | ||
| </Fragment> | ||
| <Fragment slot="pnpm"> | ||
| ```sh | ||
| pnpm dlx tailwindcss init | ||
| ``` | ||
| </Fragment> | ||
| <Fragment slot="yarn"> | ||
| ```sh | ||
| yarn dlx tailwindcss init | ||
| ``` | ||
| </Fragment> | ||
| </PackageManagerTabs> | ||
|
|
||
| Finally, add this basic configuration to your `tailwind.config.mjs` file: | ||
|
|
||
| ```js ins={3} title="tailwind.config.mjs" "content: ['./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}']" | ||
| /** @type {import('tailwindcss').Config} */ | ||
| export default { | ||
| content: ['./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}'], | ||
| theme: { | ||
| extend: {}, | ||
| }, | ||
| plugins: [], | ||
| }; | ||
| ``` | ||
|
|
||
| ## Usage | ||
|
|
||
| When you install the integration, Tailwind's utility classes should be ready to go right away. Head to the [Tailwind docs](https://tailwindcss.com/docs/utility-first) to learn how to use Tailwind, and if you see a utility class you want to try, add it to any HTML element to your project! | ||
|
|
||
| [Autoprefixer](https://github.com/postcss/autoprefixer) is also set up automatically when working in dev mode, and for production builds, so Tailwind classes will work in older browsers. | ||
|
|
||
| ## Configuration | ||
|
|
||
| ### Configuring Tailwind | ||
|
|
||
| If you used the Quick Install instructions and said yes to each prompt, you'll see a `tailwind.config.mjs` file in your project's root directory. Use this file for your Tailwind configuration changes. You can learn how to customize Tailwind using this file [in the Tailwind docs](https://tailwindcss.com/docs/configuration). | ||
|
|
||
| If it isn't there, you add your own `tailwind.config.(js|cjs|mjs|ts|mts|cts)` file to the root directory and the integration will use its configurations. This can be great if you already have Tailwind configured in another project and want to bring those settings over to this one. | ||
|
|
||
| ### Configuring the Integration | ||
|
|
||
| The Astro Tailwind integration handles the communication between Astro and Tailwind and it has its own options. Change these in the `astro.config.mjs` file (*not* the Tailwind configuration file) which is where your project's integration settings live. | ||
|
|
||
| #### configFile | ||
|
|
||
| Previously known as `config.path` in `@astrojs/tailwind` v3. See the [v4 changelog](https://github.com/withastro/astro/blob/main/packages/integrations/tailwind/CHANGELOG.md#400) for updating your config. | ||
|
|
||
| If you want to use a different Tailwind configuration file instead of the default `tailwind.config.(js|cjs|mjs|ts|mts|cts)`, specify that file's location using this integration's `configFile` option. If `configFile` is relative, it will be resolved relative to the current working directory. | ||
|
|
||
| :::caution | ||
| Changing this isn't recommended since it can cause problems with other tools that integrate with Tailwind, like the official Tailwind VSCode extension. | ||
| :::caution[Deprecated] | ||
| Tailwind CSS now offers a Vite plugin which is the preferred way to use Tailwind 4 in Astro. | ||
| ::: | ||
|
|
||
| ```js title="astro.config.mjs" | ||
| import { defineConfig } from 'astro/config'; | ||
| import tailwind from '@astrojs/tailwind'; | ||
|
|
||
| export default defineConfig({ | ||
| // ... | ||
| integrations: [ | ||
| tailwind({ | ||
| // Example: Provide a custom path to a Tailwind config file | ||
| configFile: './custom-config.mjs', | ||
| }), | ||
| ], | ||
| }); | ||
| ``` | ||
|
|
||
| #### applyBaseStyles | ||
|
|
||
| Previously known as `config.applyBaseStyles` in `@astrojs/tailwind` v3. See the [v4 changelog](https://github.com/withastro/astro/blob/main/packages/integrations/tailwind/CHANGELOG.md#400) for updating your config. | ||
|
|
||
| By default, the integration imports a basic `base.css` file on every page of your project. This basic CSS file includes the three main `@tailwind` directives: | ||
|
|
||
| ```css title="base.css" | ||
| /* The integration's default injected base.css file */ | ||
| @tailwind base; | ||
| @tailwind components; | ||
| @tailwind utilities; | ||
| ``` | ||
|
|
||
| To disable this default behavior, set `applyBaseStyles` to `false`. This can be useful if you need to define your own `base.css` file (to include a [`@layer` directive](https://tailwindcss.com/docs/functions-and-directives#layer), for example). This can also be useful if you do not want `base.css` to be imported on every page of your project. | ||
|
|
||
| ```js title="astro.config.mjs" | ||
| import { defineConfig } from 'astro/config'; | ||
| import tailwind from '@astrojs/tailwind'; | ||
|
|
||
| export default defineConfig({ | ||
| // ... | ||
| integrations: [ | ||
| tailwind({ | ||
| // Example: Disable injecting a basic `base.css` import on every page. | ||
| // Useful if you need to define and/or import your own custom `base.css`. | ||
| applyBaseStyles: false, | ||
| }), | ||
| ], | ||
| }); | ||
| ``` | ||
|
|
||
| You can now [import your own `base.css` as a local stylesheet](/en/guides/styling/#import-a-local-stylesheet). | ||
|
|
||
| #### nesting | ||
|
|
||
| Set `true` to apply the [`tailwindcss/nesting` PostCSS plugin](https://tailwindcss.com/docs/using-with-preprocessors#nesting) so you can write nested CSS declarations alongside Tailwind's syntax. This option is `false` by default. | ||
|
|
||
| ```js ins="nesting: true" | ||
| // astro.config.mjs | ||
| import { defineConfig } from 'astro/config'; | ||
| import tailwind from '@astrojs/tailwind'; | ||
|
|
||
| export default defineConfig({ | ||
| integrations: [ | ||
| tailwind({ | ||
| // Example: Allow writing nested CSS declarations | ||
| // alongside Tailwind's syntax | ||
| nesting: true, | ||
| }), | ||
| ], | ||
| }); | ||
| ``` | ||
|
|
||
| ## 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.ts) or an [example component](https://github.com/withastro/astro.build/blob/main/src/components/Checkbox.astro) | ||
| * The [Astro Ink](https://github.com/one-aalam/astro-ink), [Sarissa Blog](https://github.com/iozcelik/SarissaBlogAstroStarter), [Astro Tech Blog](https://github.com/nicdun/astro-tech-blog) 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%3A+path%3A%2Fpackage.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. | ||
|
|
||
| ```sh | ||
| 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 title="tailwind.config.mjs" | ||
| export default { | ||
| // ... | ||
| plugins: [ | ||
| function ({ addComponents, theme }) { | ||
| addComponents({ | ||
| '.btn': { | ||
| padding: theme('spacing.4'), | ||
| margin: 'auto', | ||
| }, | ||
| }); | ||
| }, | ||
| ], | ||
| }; | ||
| ``` | ||
|
|
||
| ### Class-based modifiers do not work with `@apply` directives | ||
|
|
||
| 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: | ||
|
|
||
| ```html "text-black group-hover:text-gray" | ||
| <p class="text-black group-hover:text-gray">Astro</p> | ||
| ``` | ||
|
|
||
| ### Others | ||
|
|
||
| * 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. | ||
|
|
||
| For help, check out the `#support` channel on [Discord](https://astro.build/chat). Our friendly Support Squad members are here to help! | ||
|
|
||
| You can also check our [Astro Integration Documentation][astro-integration] for more on integrations. | ||
|
|
||
| [astro-integration]: /en/guides/integrations-guide/ | ||
|
|
||
| [astro-ui-frameworks]: /en/guides/framework-components/#using-framework-components | ||
| To use Tailwind in Astro, follow the [styling guide for Tailwind](/en/guides/styling/#tailwind). | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@florian-lefebvre Just checking, do any of these troubleshooting things about
@applystill apply in v4?There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think this is still relevant, although the tailwind config example isn't correct anymore: https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes