Allow users to disable url rewriting in the PostCSS plugin

CHANGELOG.md

@@ -7,7 +7,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-- Nothing yet!
+- Add option to disable url rewriting in `@tailwindcss/postcss` ([#18321](https://github.com/tailwindlabs/tailwindcss/pull/18321))
 
 ## [4.1.10] - 2025-06-11
 

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': {
+              rewriteUrls: 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

@@ -53,11 +53,16 @@ export type PluginOptions = {
 
   // Optimize and minify the output CSS.
   optimize?: boolean | { minify?: boolean }
+
+  // Whether or not we should rewrite any encountered urls
+  // default: true
+  rewriteUrls?: boolean
 }
 
 function tailwindcss(opts: PluginOptions = {}): AcceptedPlugin {
   let base = opts.base ?? process.cwd()
   let optimize = opts.optimize ?? process.env.NODE_ENV === 'production'
+  let shouldRewriteUrls = opts.rewriteUrls ?? true
 
   return {
     postcssPlugin: '@tailwindcss/postcss',
@@ -123,7 +128,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