From 3672d561cd730a55d0d77796e7971fa74f59cf58 Mon Sep 17 00:00:00 2001 From: Jordan Pittman Date: Mon, 15 Sep 2025 16:58:59 -0400 Subject: [PATCH 1/3] Add plugin option documentation to the postcss plugin readme --- packages/@tailwindcss-postcss/README.md | 94 +++++++++++++++++++++++++ 1 file changed, 94 insertions(+) diff --git a/packages/@tailwindcss-postcss/README.md b/packages/@tailwindcss-postcss/README.md index 7d21bd88385a..e3bd04742e97 100644 --- a/packages/@tailwindcss-postcss/README.md +++ b/packages/@tailwindcss-postcss/README.md @@ -34,3 +34,97 @@ For help, discussion about best practices, or feature ideas: ## Contributing If you're interested in contributing to Tailwind CSS, please read our [contributing docs](https://github.com/tailwindcss/tailwindcss/blob/next/.github/CONTRIBUTING.md) **before submitting a pull request**. + +--- + +## `@tailwindcss/postcss` plugin API + +### Changing where the plugin searches for source files + +You can use the `base` option (defaults to the current working directory) to change the directory in which the plugin searches for source files: + +```js +import tailwindcss from "@tailwindcss/postcss" + +export default { + plugins: [ + tailwindcss({ + base: path.resolve(__dirname, "./path) + }) + ] +} +``` + +### Enabling or disabling Lightning CSS + +By default, this plugin detects whether or not the CSS is being built for production by checking the `NODE_ENV` environment variable. When building for production Lightning CSS will be enabled otherwise it is disabled. + +If you want to always enable or disable Lightning CSS the `optimize` option may be used: + +```js +import tailwindcss from "@tailwindcss/postcss" + +export default { + plugins: [ + tailwindcss({ + // Disables Lightning CSS + optimize: false, + + // Disables Lightning CSS + optimize: true, + }) + ] +} +``` + +You may also pass options to `optimize` to enable Lighting CSS but prevent minification: + +```js +import tailwindcss from "@tailwindcss/postcss" + +export default { + plugins: [ + tailwindcss({ + // Enables Lightning CSS but disables minification + optimize: { minify: false }, + }) + ] +} +``` + +### Enabling or disabling `url(…)` rewriting + +Our PostCSS plugin can rewrite `url(…)`s for you since it also handles `@import` (no `postcss-import` is needed). This feature is enabled by default. + +In some situations the bundler or framework you're using may provide this feature itself. In this case you can set `transformAssetUrls` to `false` to disable this feature: + +```js +import tailwindcss from "@tailwindcss/postcss" + +export default { + plugins: [ + tailwindcss({ + // Disable `url(…)` rewriting + transformAssetUrls: false, + + // Enable `url(…)` rewriting (the default) + transformAssetUrls: true, + }) + ] +} +``` + +You may also pass options to `optimize` to enable Lighting CSS but prevent minification: + +```js +import tailwindcss from "@tailwindcss/postcss" + +export default { + plugins: [ + tailwindcss({ + // Enables Lightning CSS but disables minification + optimize: { minify: false }, + }) + ] +} +``` From 1d88d3d6b8ca77fc6ac4805beccfff4e9ae11fbc Mon Sep 17 00:00:00 2001 From: Jordan Pittman Date: Tue, 16 Sep 2025 10:32:53 -0400 Subject: [PATCH 2/3] Tweak example --- packages/@tailwindcss-postcss/README.md | 14 +------------- 1 file changed, 1 insertion(+), 13 deletions(-) diff --git a/packages/@tailwindcss-postcss/README.md b/packages/@tailwindcss-postcss/README.md index e3bd04742e97..73cfc5af4aa0 100644 --- a/packages/@tailwindcss-postcss/README.md +++ b/packages/@tailwindcss-postcss/README.md @@ -70,21 +70,9 @@ export default { // Disables Lightning CSS optimize: false, - // Disables Lightning CSS + // Enables Lightning CSS optimize: true, - }) - ] -} -``` - -You may also pass options to `optimize` to enable Lighting CSS but prevent minification: -```js -import tailwindcss from "@tailwindcss/postcss" - -export default { - plugins: [ - tailwindcss({ // Enables Lightning CSS but disables minification optimize: { minify: false }, }) From 66d4dae652000db658c0533147bd230ed006614c Mon Sep 17 00:00:00 2001 From: Jordan Pittman Date: Thu, 18 Sep 2025 09:58:18 -0400 Subject: [PATCH 3/3] Address feedback Co-authored-by: Philipp Spiess --- packages/@tailwindcss-postcss/README.md | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/packages/@tailwindcss-postcss/README.md b/packages/@tailwindcss-postcss/README.md index 73cfc5af4aa0..1d0900f4af04 100644 --- a/packages/@tailwindcss-postcss/README.md +++ b/packages/@tailwindcss-postcss/README.md @@ -67,13 +67,21 @@ import tailwindcss from "@tailwindcss/postcss" export default { plugins: [ tailwindcss({ - // Disables Lightning CSS + // Enable or disable Lightning CSS optimize: false, + }) + ] +} +``` - // Enables Lightning CSS - optimize: true, +It's also possible to keep Lightning CSS enabled but disable minification: - // Enables Lightning CSS but disables minification +```js +import tailwindcss from "@tailwindcss/postcss" + +export default { + plugins: [ + tailwindcss({ optimize: { minify: false }, }) ]