What's the differences between @tailwind directive and @import?

[mrdulin]

If you’re using postcss-import (or a tool that uses it under the hood, such as Webpacker for Rails), use our imports instead of the @tailwind directive to avoid issues when importing any of your own additional files:

What does "avoid issues when importing any of your own additional files" means? What issues? Please improve the documentation, thanks.

Why create the @tailwind directive instead of using postcss-import directly?

[adamwathan]

@tailwind is a placeholder in the CSS for where Tailwind inserts all of the generated code necessary after scanning your templates to figure out which classes you're using — that's the core of Tailwind and not something postcss-import would help with.

The reason we offer the imports as an alternative if because the CSS spec is strict about @import needing to come before any other rules in your CSS file, and postcss-import respects this part of the spec.

From https://github.com/postcss/postcss-import:

This plugin attempts to follow the CSS @import spec; @import statements must precede all other statements (besides @charset).

What this means is that this CSS doesn't work:

@tailwind base;
@import "some-custom-css";
@tailwind components;
@tailind utilities;

So we offer the imports as a way to workaround this so that you can write this and not get errors from postcss-import:

@import "tailwindcss/base";
@import "some-custom-css";
@import "tailwindcss/components";
@import "tailwindcss/utilities";

If you look at the source of those files you can see all they do is include the relevant @tailwind rule:

https://unpkg.com/browse/tailwindcss@3.4.4/utilities.css

/* tailwindcss/utilities.css */
@tailwind utilities;

This is all outlined in detail in our documentation on build-time imports:

https://tailwindcss.com/docs/using-with-preprocessors#build-time-imports