Allow users to disable url rewriting in the PostCSS plugin

CHANGELOG.md

@@ -13,6 +13,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Fix trailing `)` from interfering with extraction in Clojure keywords ([#18345](https://github.com/tailwindlabs/tailwindcss/pull/18345))
 - Detect classes inside Elixir charlist, word list, and string sigils ([#18432](https://github.com/tailwindlabs/tailwindcss/pull/18432))
 - Track source locations through `@plugin` and `@config` ([#18345](https://github.com/tailwindlabs/tailwindcss/pull/18345))
+- Add option to disable url rewriting in `@tailwindcss/postcss` ([#18321](https://github.com/tailwindlabs/tailwindcss/pull/18321))
 
 ## [4.1.11] - 2025-06-26
 

integrations/postcss/url-rewriting.test.ts

@@ -72,3 +72,78 @@ test(
     `)
   },
 )
+
+test(
+  'url rewriting can be disabled',
+  {
+    fs: {
+      'package.json': json`
+        {
+          "dependencies": {
+            "postcss": "^8",
+            "postcss-cli": "^10",
+            "tailwindcss": "workspace:^",
+            "@tailwindcss/postcss": "workspace:^"
+          }
+        }
+      `,
+      'postcss.config.js': js`
+        module.exports = {
+          plugins: {
+            '@tailwindcss/postcss': {
+              transformAssetUrls: false,
+            },
+          },
+        }
+      `,
+      'src/index.css': css`
+        @reference 'tailwindcss';
+        @import './dir-1/bar.css';
+        @import './dir-1/dir-2/baz.css';
+        @import './dir-1/dir-2/vector.css';
+      `,
+      'src/dir-1/bar.css': css`
+        .test1 {
+          background-image: url('../../resources/image.png');
+        }
+      `,
+      'src/dir-1/dir-2/baz.css': css`
+        .test2 {
+          background-image: url('../../../resources/image.png');
+        }
+      `,
+      'src/dir-1/dir-2/vector.css': css`
+        @import './dir-3/vector.css';
+        .test3 {
+          background-image: url('../../../resources/vector.svg');
+        }
+      `,
+      'src/dir-1/dir-2/dir-3/vector.css': css`
+        .test4 {
+          background-image: url('./vector-2.svg');
+        }
+      `,
+    },
+  },
+  async ({ fs, exec, expect }) => {
+    await exec('pnpm postcss src/index.css --output dist/out.css')
+
+    expect(await fs.dumpFiles('dist/out.css')).toMatchInlineSnapshot(`
+      "
+      --- dist/out.css ---
+      .test1 {
+        background-image: url('../../resources/image.png');
+      }
+      .test2 {
+        background-image: url('../../../resources/image.png');
+      }
+      .test4 {
+        background-image: url('./vector-2.svg');
+      }
+      .test3 {
+        background-image: url('../../../resources/vector.svg');
+      }
+      "
+    `)
+  },
+)

packages/@tailwindcss-postcss/src/index.ts

@@ -48,16 +48,30 @@ function getContextFromCache(inputFile: string, opts: PluginOptions): CacheEntry
 }
 
 export type PluginOptions = {
-  // The base directory to scan for class candidates.
+  /**
+   * The base directory to scan for class candidates.
+   *
+   * Defaults to the current working directory.
+   */
   base?: string
 
-  // Optimize and minify the output CSS.
+  /**
+   * Optimize and minify the output CSS.
+   */
   optimize?: boolean | { minify?: boolean }
+
+  /**
+   * Enable or disable asset URL rewriting.
+   *
+   * Defaults to `true`.
+   */
+  transformAssetUrls?: boolean
 }
 
 function tailwindcss(opts: PluginOptions = {}): AcceptedPlugin {
   let base = opts.base ?? process.cwd()
   let optimize = opts.optimize ?? process.env.NODE_ENV === 'production'
+  let shouldRewriteUrls = opts.transformAssetUrls ?? true
 
   return {
     postcssPlugin: '@tailwindcss/postcss',
@@ -123,7 +137,7 @@ function tailwindcss(opts: PluginOptions = {}): AcceptedPlugin {
             let compiler = await compileAst(ast, {
               from: result.opts.from,
               base: inputBasePath,
-              shouldRewriteUrls: true,
+              shouldRewriteUrls,
               onDependency: (path) => context.fullRebuildPaths.push(path),
               // In CSS Module files, we have to disable the `@property` polyfill since these will
               // emit global `*` rules which are considered to be non-pure and will cause builds