fix: Rewrite relative url() paths when inlining @Stylesheet imports in production bundle (#24165)

When a CSS file referenced by @Stylesheet contains @import statements
that pull in other CSS files with relative url(...) references, the
production build inlined the imports but left the urls untouched. After
inlining, the browser resolves those urls relative to the entry file,
breaking image paths.

Add a new build-time entry point that rewrites url(...) references so
each one is expressed relative to the entry CSS file's folder. Absolute
urls, protocol urls (http, https, data, ftp, file) and urls whose
resolved target falls outside the entry's base folder (e.g. npm package
siblings) are left untouched.

Fixes #24164

Author: Artur-

flow-build-tools/src/main/java/com/vaadin/flow/server/frontend/TaskProcessStylesheetCss.java

@@ -184,17 +184,14 @@ private File resolveCssFile(File resourcesDir, String cssPath) {
     private void processCssFile(File cssFile) throws IOException {
         getLogger().debug("Processing CSS file: {}", cssFile.getName());
 
-        // Get node_modules folder for resolving npm package imports
         File nodeModulesFolder = options.getNodeModulesFolder();
 
-        // Inline @import statements for local files and node_modules
-        String content = CssBundler.inlineImports(cssFile.getParentFile(),
-                cssFile, null, nodeModulesFolder);
+        // Inline @import statements and rewrite relative url() references so
+        // they remain correct after imports are inlined into the entry file.
+        String content = CssBundler.inlineImportsForStaticResourcesRelative(
+                cssFile.getParentFile(), cssFile, nodeModulesFolder);
 
-        // Minify the CSS
         content = CssBundler.minifyCss(content);
-
-        // Write back to the same file
         Files.writeString(cssFile.toPath(), content);
     }
 

flow-build-tools/src/test/java/com/vaadin/flow/server/frontend/TaskProcessStylesheetCssTest.java

@@ -304,6 +304,66 @@ void execute_inlinesNodeModulesImports()
                 "Should contain main CSS");
     }
 
+    @Test
+    void execute_rewritesRelativeUrlsInInlinedImports()
+            throws ExecutionFailedException, IOException {
+        Mockito.when(classFinder.getAnnotatedClasses(StyleSheet.class))
+                .thenReturn(Set.of(TestClassWithStyleSheet.class));
+
+        // Entry file at META-INF/resources/styles.css imports
+        // views/messages.css which references ../images/foo.svg
+        String mainCss = "@import './views/messages.css';";
+        String messagesCss = ".icon { mask-image: url(\"../images/foo.svg\"); }";
+
+        File mainFile = new File(metaInfResources, "styles.css");
+        FileUtils.writeStringToFile(mainFile, mainCss, StandardCharsets.UTF_8);
+
+        File viewsDir = new File(metaInfResources, "views");
+        viewsDir.mkdirs();
+        File messagesFile = new File(viewsDir, "messages.css");
+        FileUtils.writeStringToFile(messagesFile, messagesCss,
+                StandardCharsets.UTF_8);
+
+        File imagesDir = new File(metaInfResources, "images");
+        imagesDir.mkdirs();
+        new File(imagesDir, "foo.svg").createNewFile();
+
+        TaskProcessStylesheetCss task = new TaskProcessStylesheetCss(options);
+        task.execute();
+
+        String processedCss = Files.readString(mainFile.toPath());
+        assertTrue(processedCss.contains("url('images/foo.svg')"),
+                "Expected url rewritten to 'images/foo.svg' but got: "
+                        + processedCss);
+        assertTrue(!processedCss.contains("../images/"),
+                "Expected '../images/' to be rewritten away but got: "
+                        + processedCss);
+    }
+
+    @Test
+    void execute_leavesAbsoluteAndExternalUrlsAlone()
+            throws ExecutionFailedException, IOException {
+        Mockito.when(classFinder.getAnnotatedClasses(StyleSheet.class))
+                .thenReturn(Set.of(TestClassWithStyleSheet.class));
+
+        String mainCss = """
+                .a { background: url('/absolute/x.svg'); }
+                .b { background: url('https://cdn.example.com/y.svg'); }
+                """;
+        File mainFile = new File(metaInfResources, "styles.css");
+        FileUtils.writeStringToFile(mainFile, mainCss, StandardCharsets.UTF_8);
+
+        TaskProcessStylesheetCss task = new TaskProcessStylesheetCss(options);
+        task.execute();
+
+        String processedCss = Files.readString(mainFile.toPath());
+        assertTrue(processedCss.contains("url('/absolute/x.svg')"),
+                "Absolute url should remain unchanged: " + processedCss);
+        assertTrue(
+                processedCss.contains("url('https://cdn.example.com/y.svg')"),
+                "External url should remain unchanged: " + processedCss);
+    }
+
     @Test
     void execute_processesMultipleAnnotatedClasses()
             throws ExecutionFailedException, IOException {

flow-server/src/main/java/com/vaadin/flow/internal/CssBundler.java

@@ -59,8 +59,34 @@ public class CssBundler {
     private static final String MAYBE_LAYER_OR_MEDIA_QUERY = "(" + LAYER + "|"
             + MEDIA_QUERY + ")";
 
+    // Selects how url(...) references are rewritten when inlining @import
+    // statements. The right choice depends on how the bundled CSS is later
+    // delivered to the browser:
+    //
+    // THEMES — used for application themes; url() targets are rewritten to
+    // absolute "VAADIN/themes/<theme>/..." paths because themes are
+    // served from a known fixed location.
+    //
+    // STATIC_RESOURCES — used in dev mode for @StyleSheet files served from
+    // public roots (META-INF/resources, webapp, ...). The dev-tools
+    // live-reload client (vaadin-dev-tools.ts onUpdate) injects the
+    // bundled content into an inline <style> tag and removes the
+    // original <link>. An inline <style> has no URL of its own, so the
+    // browser resolves any relative url() against the *page URL*, which
+    // would point to the wrong folder. To stay correct we rewrite to
+    // absolute paths rooted at the servlet context (e.g.
+    // "/myapp/relurl-test/images/dot.svg").
+    //
+    // STATIC_RESOURCES_RELATIVE — used in prod by TaskProcessStylesheetCss.
+    // The bundled CSS is written back in-place under META-INF/resources
+    // and served via the original <link href>, so the browser still
+    // fetches it from the entry file's URL. Relative url() therefore
+    // resolves against the entry's folder and we just need to express
+    // each url() relative to that folder. We can't use STATIC_RESOURCES
+    // here because the deployment context path is not known at build
+    // time.
     private enum BundleFor {
-        THEMES, STATIC_RESOURCES
+        THEMES, STATIC_RESOURCES, STATIC_RESOURCES_RELATIVE
     }
 
     /**
@@ -167,6 +193,36 @@ public static String inlineImportsForPublicResources(File baseFolder,
                 BundleFor.STATIC_RESOURCES, contextPath, null);
     }
 
+    /**
+     * Inlines imports for CSS files located under public static resources (e.g.
+     * META-INF/resources) at build time, rewriting relative {@code url(...)}
+     * references so they are expressed relative to the entry CSS file's folder.
+     * <p>
+     * Unlike {@link #inlineImportsForPublicResources(File, File, String)}, this
+     * variant does not prepend a servlet context path. The resulting URLs are
+     * purely relative, which is required when the CSS is processed at build
+     * time and the deployment context path is not yet known.
+     *
+     * @param baseFolder
+     *            folder of the entry CSS file; inlined {@code url(...)}
+     *            references are rewritten to paths relative to this folder.
+     * @param cssFile
+     *            the CSS file to process.
+     * @param nodeModulesFolder
+     *            the node_modules folder for resolving npm package imports, or
+     *            {@code null} if node_modules resolution is not needed.
+     * @return the processed stylesheet content, with inlined imports and
+     *         rewritten URLs.
+     * @throws IOException
+     *             if filesystem resources cannot be read.
+     */
+    public static String inlineImportsForStaticResourcesRelative(
+            File baseFolder, File cssFile, File nodeModulesFolder)
+            throws IOException {
+        return inlineImports(baseFolder, cssFile, new HashSet<>(),
+                BundleFor.STATIC_RESOURCES_RELATIVE, null, nodeModulesFolder);
+    }
+
     /**
      * Internal implementation that can optionally skip URL rewriting.
      *
@@ -247,6 +303,9 @@ private static String inlineImports(File baseFolder, File cssFile,
         } else if (bundleFor == BundleFor.STATIC_RESOURCES) {
             content = rewriteCssUrlsForStaticResources(baseFolder, cssFile,
                     contextPath, content);
+        } else if (bundleFor == BundleFor.STATIC_RESOURCES_RELATIVE) {
+            content = rewriteCssUrlsForStaticResourcesRelative(baseFolder,
+                    cssFile, content);
         }
         content = StringUtil.removeComments(content, true);
         List<String> unhandledImports = new ArrayList<>();
@@ -307,48 +366,76 @@ private static String inlineImports(File baseFolder, File cssFile,
 
     private static String rewriteCssUrlsForStaticResources(File baseFolder,
             File cssFile, String contextPath, String content) {
-        // Public resources: rebase URLs from the current cssFile to the
-        // entry stylesheet base folder
+        // Bundled CSS is delivered as inline <style> in dev mode, so url()s
+        // need to be absolute paths rooted at the servlet context.
+        return rewriteCssUrls(baseFolder, cssFile, content,
+                target -> rebaseToContextPath(baseFolder, contextPath, target));
+    }
+
+    private static String rewriteCssUrlsForStaticResourcesRelative(
+            File baseFolder, File cssFile, String content) {
+        // Bundled CSS is written back to disk and served from the entry
+        // file's URL in prod mode, so url()s can be expressed relative to
+        // that entry folder.
+        Path baseNormalized = baseFolder.toPath().normalize().toAbsolutePath();
+        return rewriteCssUrls(baseFolder, cssFile, content,
+                target -> baseNormalized.relativize(target).toString()
+                        .replace('\\', '/'));
+    }
+
+    /**
+     * Common url() rewriting pipeline used by both static-resource bundling
+     * strategies. Walks every {@code url(...)} in {@code content}, skips ones
+     * that should be left untouched (empty, absolute, protocol-prefixed,
+     * unresolvable, outside {@code baseFolder}, or pointing at a missing file),
+     * and lets the caller decide how to format the kept ones via
+     * {@code targetToUrl}.
+     */
+    private static String rewriteCssUrls(File baseFolder, File cssFile,
+            String content,
+            java.util.function.Function<Path, String> targetToUrl) {
+        Path baseNormalized = baseFolder.toPath().normalize().toAbsolutePath();
         Matcher urlMatcher = URL_PATTERN.matcher(content);
-        content = urlMatcher.replaceAll(result -> {
+        return urlMatcher.replaceAll(result -> {
             String url = getNonNullGroup(result, 2, 3, 4);
             if (url == null || url.trim().endsWith(".css")) {
-                // CSS imports handled separately below
+                // @import-style url()s are handled by import inlining, not
+                // here.
                 return Matcher.quoteReplacement(urlMatcher.group());
             }
             String sanitized = sanitizeUrl(url);
             if (sanitized == null) {
                 return Matcher.quoteReplacement(urlMatcher.group());
             }
             String trimmed = sanitized.trim();
-            // Only handle relative URLs (no protocol, no leading slash, not
-            // data URIs)
-            // Treat only known protocols as absolute to avoid false
-            // positives like "my:file.css"
-            if (trimmed.startsWith("/")
+            // Only handle relative URLs: not empty, no leading slash, no
+            // known protocol prefix. Match only known protocols as absolute
+            // to avoid false positives like "my:file.css".
+            if (trimmed.isEmpty() || trimmed.startsWith("/")
                     || PROTOCOL_PATTER_FOR_URLS.matcher(trimmed).matches()) {
                 return Matcher.quoteReplacement(urlMatcher.group());
             }
             try {
                 Path target = cssFile.getParentFile().toPath().resolve(trimmed)
-                        .normalize();
-                // Only rewrite when we can safely confirm the target (in
-                // url()) file exists
-                if (Files.exists(target)) {
-                    // For inline <style> tags, make URLs absolute to the
-                    // application context
-                    String rebased = rebaseToContextPath(baseFolder,
-                            contextPath, target);
-                    return Matcher.quoteReplacement("url('" + rebased + "')");
+                        .normalize().toAbsolutePath();
+                if (!target.startsWith(baseNormalized)) {
+                    // Target is outside the entry's base folder (e.g. an
+                    // npm-package CSS referencing a sibling file). Don't
+                    // invent a path for it.
+                    return Matcher.quoteReplacement(urlMatcher.group());
                 }
+                if (!Files.exists(target)) {
+                    // Don't rewrite something we can't confirm.
+                    return Matcher.quoteReplacement(urlMatcher.group());
+                }
+                return Matcher.quoteReplacement(
+                        "url('" + targetToUrl.apply(target) + "')");
             } catch (Exception e) {
-                // On any resolution issue, keep the original
                 getLogger().debug("Unable to resolve url: {}",
                         urlMatcher.group());
             }
             return Matcher.quoteReplacement(urlMatcher.group());
         });
-        return content;
     }
 
     private static String rewriteCssUrlsForThemes(File baseFolder, File cssFile,