feat: add Tailwind CSS support behind the feature flag (#22611)

platosha · web-flow · commit 6f6cd574e86a · 2025-11-06T10:59:21.000+02:00
* feat: add Tailwind CSS support behind the feature flag Fixes #21643 * fix: add Tailwind CSS file required by its tooling * test: add IT test module for Tailwind CSS * chore: formatting * chore: fix javadoc * test: add TaskGenerateTailwindCssTest
diff --git a/flow-server/src/main/java/com/vaadin/experimental/CoreFeatureFlagProvider.java b/flow-server/src/main/java/com/vaadin/experimental/CoreFeatureFlagProvider.java
@@ -45,10 +45,14 @@ public class CoreFeatureFlagProvider implements FeatureFlagProvider {
             "Copilot experimental features", "copilotExperimentalFeatures",
             "https://vaadin.com/docs/latest/tools/copilot", false, null);
 
+    public static final Feature TAILWIND_CSS = new Feature(
+            "Tailwind CSS framework", "tailwindCss",
+            "https://github.com/vaadin/flow/issues/21643", true, null);
+
     @Override
     public List<Feature> getFeatures() {
         return List.of(COLLABORATION_ENGINE_BACKEND, FLOW_FULLSTACK_SIGNALS,
                 ACCESSIBLE_DISABLED_BUTTONS, COMPONENT_STYLE_INJECTION,
-                COPILOT_EXPERIMENTAL);
+                COPILOT_EXPERIMENTAL, TAILWIND_CSS);
     }
 }
diff --git a/flow-server/src/main/java/com/vaadin/flow/server/frontend/AbstractUpdateImports.java b/flow-server/src/main/java/com/vaadin/flow/server/frontend/AbstractUpdateImports.java
@@ -62,6 +62,7 @@
 import static com.vaadin.flow.server.Constants.PACKAGE_JSON;
 import static com.vaadin.flow.server.Constants.RESOURCES_FRONTEND_DEFAULT;
 import static com.vaadin.flow.server.frontend.FrontendUtils.FRONTEND_FOLDER_ALIAS;
+import static com.vaadin.flow.server.frontend.FrontendUtils.TAILWIND_CSS;
 
 /**
  * Common logic for generate import file JS content.
@@ -94,6 +95,8 @@ abstract class AbstractUpdateImports implements Runnable {
             .compile("^\\s*injectGlobalCss\\(([^,]+),.*$");
     private static final String INJECT_WC_CSS = "injectGlobalWebcomponentCss(%s);";
 
+    private static final String TAILWIND_IMPORT = "./" + TAILWIND_CSS;
+
     private static final String THEMABLE_MIXIN_IMPORT = "import { css, unsafeCSS, registerStyles } from '@vaadin/vaadin-themable-mixin';";
     private static final String REGISTER_STYLES_FOR_TEMPLATE = CSS_IMPORT_AND_MAKE_LIT_CSS
             + "%n" + "registerStyles('%s', $css_%1$d%s);";
@@ -305,6 +308,9 @@ private Map<File, List<String>> process(Map<ChunkInfo, List<CssData>> css,
         Map<ChunkInfo, List<String>> lazyCss = new LinkedHashMap<>();
         List<CssData> eagerCssData = new ArrayList<>();
         List<CssData> appShellCssData = new ArrayList<>();
+        if (FrontendUtils.isTailwindCssEnabled(options)) {
+            appShellCssData.add(new CssData(TAILWIND_IMPORT, null, null, null));
+        }
         for (Entry<ChunkInfo, List<String>> entry : javascript.entrySet()) {
             if (isLazyRoute(entry.getKey())) {
                 lazyJavascript.put(entry.getKey(), entry.getValue());
diff --git a/flow-server/src/main/java/com/vaadin/flow/server/frontend/FrontendUtils.java b/flow-server/src/main/java/com/vaadin/flow/server/frontend/FrontendUtils.java
@@ -48,6 +48,7 @@
 import org.slf4j.LoggerFactory;
 import tools.jackson.databind.JsonNode;
 
+import com.vaadin.experimental.CoreFeatureFlagProvider;
 import com.vaadin.flow.di.Lookup;
 import com.vaadin.flow.di.ResourceProvider;
 import com.vaadin.flow.function.DeploymentConfiguration;
@@ -268,6 +269,11 @@ public class FrontendUtils {
 
     public static final String ROUTES_JS = "routes.js";
 
+    /**
+     * File name of the Tailwind CSS framework integration entrypoint.
+     */
+    public static final String TAILWIND_CSS = "tailwind.css";
+
     /**
      * Default generated path for generated frontend files.
      */
@@ -1548,4 +1554,16 @@ public static List<String> getClientRoutes() {
                 VaadinService.getCurrent().getDeploymentConfiguration());
     }
 
+    /**
+     * Checks if integration with Tailwind CSS framework is enabled.
+     *
+     * @param options
+     *            the build options
+     * @return true if Tailwind CSS integration is enabled, false otherwise
+     */
+    public static boolean isTailwindCssEnabled(Options options) {
+        return options.getFeatureFlags()
+                .isEnabled(CoreFeatureFlagProvider.TAILWIND_CSS);
+    }
+
 }
diff --git a/flow-server/src/main/java/com/vaadin/flow/server/frontend/NodeTasks.java b/flow-server/src/main/java/com/vaadin/flow/server/frontend/NodeTasks.java
@@ -63,6 +63,7 @@ public class NodeTasks implements FallibleCommand {
             TaskGenerateIndexHtml.class,
             TaskGenerateIndexTs.class,
             TaskGenerateReactFiles.class,
+            TaskGenerateTailwindCss.class,
             TaskUpdateOldIndexTs.class,
             TaskGenerateViteDevMode.class,
             TaskGenerateCommercialBanner.class,
@@ -294,6 +295,9 @@ private void addBootstrapTasks(Options options) {
                 || options.isBundleBuild()) {
             commands.add(new TaskGenerateIndexTs(options));
             commands.add(new TaskGenerateReactFiles(options));
+            if (FrontendUtils.isTailwindCssEnabled(options)) {
+                commands.add(new TaskGenerateTailwindCss(options));
+            }
             if (!options.isProductionMode()) {
                 commands.add(new TaskGenerateViteDevMode(options));
             }
diff --git a/flow-server/src/main/java/com/vaadin/flow/server/frontend/NodeUpdater.java b/flow-server/src/main/java/com/vaadin/flow/server/frontend/NodeUpdater.java
@@ -310,6 +310,10 @@ Map<String, String> getDefaultDependencies() {
             dependencies
                     .putAll(readDependencies("vaadin-router", "dependencies"));
         }
+        if (FrontendUtils.isTailwindCssEnabled(options)) {
+            dependencies
+                    .putAll(readDependencies("tailwindcss", "dependencies"));
+        }
         putHillaComponentsDependencies(dependencies, "dependencies");
         return dependencies;
     }
@@ -373,6 +377,9 @@ Map<String, String> getDefaultDevDependencies() {
             defaults.putAll(
                     readDependencies("react-router", "devDependencies"));
         }
+        if (FrontendUtils.isTailwindCssEnabled(options)) {
+            defaults.putAll(readDependencies("tailwindcss", "devDependencies"));
+        }
 
         // Add workbox dependencies only when PWA is enabled
         if (frontDeps != null && frontDeps.getPwaConfiguration() != null
diff --git a/flow-server/src/main/java/com/vaadin/flow/server/frontend/TaskGenerateTailwindCss.java b/flow-server/src/main/java/com/vaadin/flow/server/frontend/TaskGenerateTailwindCss.java
@@ -0,0 +1,79 @@
+/*
+ * Copyright 2000-2025 Vaadin Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not
+ * use this file except in compliance with the License. You may obtain a copy of
+ * the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations under
+ * the License.
+ */
+package com.vaadin.flow.server.frontend;
+
+import java.io.File;
+import java.io.IOException;
+import java.io.InputStream;
+
+import org.apache.commons.io.IOUtils;
+
+import static com.vaadin.flow.server.frontend.FrontendUtils.TAILWIND_CSS;
+import static java.nio.charset.StandardCharsets.UTF_8;
+
+/**
+ * Generate <code>tailwind.css</code> if it is missing in the generated frontend
+ * folder.
+ * <p>
+ * For internal use only. May be renamed or removed in a future release.
+ *
+ * @since 25.0
+ */
+public class TaskGenerateTailwindCss extends AbstractTaskClientGenerator {
+
+    private static final String RELATIVE_SOURCE_PATH_MARKER = "#relativeSourcePath#";
+
+    private String relativeSourcePath;
+
+    private File tailwindCss;
+
+    /**
+     * Create a task to generate <code>tailwind.css</code> integration file.
+     *
+     * @param options
+     *            the task options
+     */
+    TaskGenerateTailwindCss(Options options) {
+        tailwindCss = new File(options.getFrontendGeneratedFolder(),
+                TAILWIND_CSS);
+        relativeSourcePath = options.getFrontendGeneratedFolder().toPath()
+                .relativize(options.getNpmFolder().toPath().resolve("src"))
+                .toString();
+        // Use forward slash as a separator
+        relativeSourcePath = relativeSourcePath.replace(File.separator, "/");
+    }
+
+    @Override
+    protected String getFileContent() throws IOException {
+        try (InputStream indexStream = getClass()
+                .getResourceAsStream(TAILWIND_CSS)) {
+            var template = IOUtils.toString(indexStream, UTF_8);
+            template = template.replace(RELATIVE_SOURCE_PATH_MARKER,
+                    relativeSourcePath);
+            return template;
+        }
+    }
+
+    @Override
+    protected File getGeneratedFile() {
+        return tailwindCss;
+    }
+
+    @Override
+    protected boolean shouldGenerate() {
+        return true;
+    }
+}
diff --git a/flow-server/src/main/java/com/vaadin/flow/server/frontend/TaskUpdateVite.java b/flow-server/src/main/java/com/vaadin/flow/server/frontend/TaskUpdateVite.java
@@ -133,6 +133,7 @@ private void createGeneratedConfig() throws IOException {
                 .replace("#frontendExtraFileExtensions#",
                         getFrontendExtraFileExtensions());
         template = updateFileSystemRouterVitePlugin(template);
+        template = updateTailwindCssVitePlugin(template);
 
         FileIOUtils.writeIfChanged(generatedConfigFile, template);
         log().debug("Created vite generated configuration file: '{}'",
@@ -166,6 +167,18 @@ private String updateFileSystemRouterVitePlugin(String template) {
                 .replace("//#vitePluginFileSystemRouter#", "");
     }
 
+    private String updateTailwindCssVitePlugin(String template) {
+        if (FrontendUtils.isTailwindCssEnabled(options)) {
+            return template
+                    .replace("//#tailwindcssVitePluginImport#",
+                            "import tailwindcss from '@tailwindcss/vite';")
+                    .replace("//#tailwindcssVitePlugin#", "tailwindcss(),");
+        } else {
+            return template.replace("//#tailwindcssVitePluginImport#", "")
+                    .replace("//#tailwindcssVitePlugin#", "");
+        }
+    }
+
     private Logger log() {
         return LoggerFactory.getLogger(this.getClass());
     }
diff --git a/flow-server/src/main/resources/com/vaadin/flow/server/frontend/dependencies/tailwindcss/package.json b/flow-server/src/main/resources/com/vaadin/flow/server/frontend/dependencies/tailwindcss/package.json
@@ -0,0 +1,10 @@
+{
+  "private": true,
+  "description": "Tailwind CSS dependencies",
+  "dependencies": {
+    "tailwindcss": "4.1.16"
+  },
+  "devDependencies": {
+    "@tailwindcss/vite": "4.1.16"
+  }
+}
diff --git a/flow-server/src/main/resources/com/vaadin/flow/server/frontend/tailwind.css b/flow-server/src/main/resources/com/vaadin/flow/server/frontend/tailwind.css
@@ -0,0 +1,4 @@
+@import 'tailwindcss/theme.css';
+@import 'tailwindcss/utilities.css';
+
+@source "#relativeSourcePath#";
diff --git a/flow-server/src/main/resources/vite.generated.ts b/flow-server/src/main/resources/vite.generated.ts
@@ -33,6 +33,7 @@ import vaadinBundlesPlugin from '#buildFolder#/plugins/vite-plugin-vaadin-bundle
 
 import { visualizer } from 'rollup-plugin-visualizer';
 import reactPlugin from '@vitejs/plugin-react';
+//#tailwindcssVitePluginImport#
 
 //#vitePluginFileSystemRouterImport#
 
@@ -565,6 +566,7 @@ export const vaadinConfig: UserConfigFn = (env) => {
           ].filter(Boolean)
         }
       }),
+      //#tailwindcssVitePlugin#
       productionMode && vaadinI18n({
         cwd: __dirname,
         meta: {
diff --git a/flow-server/src/test/java/com/vaadin/flow/server/frontend/TaskGenerateTailwindCssTest.java b/flow-server/src/test/java/com/vaadin/flow/server/frontend/TaskGenerateTailwindCssTest.java
@@ -0,0 +1,97 @@
+/*
+ * Copyright 2000-2025 Vaadin Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not
+ * use this file except in compliance with the License. You may obtain a copy of
+ * the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations under
+ * the License.
+ */
+package com.vaadin.flow.server.frontend;
+
+import java.io.File;
+import java.io.IOException;
+import java.nio.file.Files;
+
+import org.junit.Assert;
+import org.junit.Before;
+import org.junit.Rule;
+import org.junit.Test;
+import org.junit.rules.TemporaryFolder;
+import org.mockito.Mockito;
+
+import com.vaadin.flow.di.Lookup;
+
+import static com.vaadin.flow.server.frontend.FrontendUtils.TAILWIND_CSS;
+
+public class TaskGenerateTailwindCssTest {
+
+    @Rule
+    public TemporaryFolder temporaryFolder = new TemporaryFolder();
+
+    private File npmFolder;
+    private File frontendGeneratedFolder;
+    private TaskGenerateTailwindCss taskGenerateTailwindCss;
+
+    @Before
+    public void setUp() throws IOException {
+        npmFolder = temporaryFolder.newFolder();
+        frontendGeneratedFolder = new File(npmFolder, "src/frontend-generated");
+        frontendGeneratedFolder.mkdirs();
+        Options options = new Options(Mockito.mock(Lookup.class), npmFolder)
+                .withFrontendGeneratedFolder(frontendGeneratedFolder);
+        taskGenerateTailwindCss = new TaskGenerateTailwindCss(options);
+    }
+
+    @Test
+    public void should_haveCorrectFileContent() throws Exception {
+        verifyTailwindCss(taskGenerateTailwindCss.getFileContent());
+    }
+
+    @Test
+    public void should_generateTailwindCss() throws Exception {
+        File tailwindcss = new File(frontendGeneratedFolder, TAILWIND_CSS);
+        taskGenerateTailwindCss.execute();
+        Assert.assertEquals("Should have correct tailwind.css file path",
+                tailwindcss, taskGenerateTailwindCss.getGeneratedFile());
+        verifyTailwindCss(getTailwindCssFileContent());
+        Assert.assertTrue(
+                "Should generate tailwind.css in the frontend generated folder",
+                taskGenerateTailwindCss.shouldGenerate());
+    }
+
+    @Test
+    public void should_updateExistingTailwindCss() throws Exception {
+        File tailwindcss = new File(frontendGeneratedFolder, TAILWIND_CSS);
+        Files.writeString(tailwindcss.toPath(), "OLD CONTENT");
+        taskGenerateTailwindCss.execute();
+        Assert.assertTrue(
+                "Should generate tailwind.css in the frontend generated folder",
+                taskGenerateTailwindCss.shouldGenerate());
+        var tailwindCssContent = getTailwindCssFileContent();
+        Assert.assertEquals("Should update content in tailwind.css",
+                taskGenerateTailwindCss.getFileContent(), tailwindCssContent);
+    }
+
+    private void verifyTailwindCss(String tailwindCssContent) {
+        Assert.assertTrue("Should have tailwindcss/theme.css import",
+                tailwindCssContent
+                        .contains("@import 'tailwindcss/theme.css';\n"));
+        Assert.assertTrue("Should have tailwindcss/utilities.css import",
+                tailwindCssContent
+                        .contains("@import 'tailwindcss/utilities.css';\n"));
+        Assert.assertTrue("Should have correct @source directive",
+                tailwindCssContent.contains("@source \"..\";\n"));
+    }
+
+    private String getTailwindCssFileContent() throws IOException {
+        return Files.readString(
+                taskGenerateTailwindCss.getGeneratedFile().toPath());
+    }
+}
diff --git a/flow-tests/pom.xml b/flow-tests/pom.xml
@@ -19,6 +19,7 @@
     <module>test-express-build</module>
     <module>test-aura</module>
     <module>test-lumo-theme</module>
+    <module>test-tailwindcss</module>
   </modules>
 
   <properties>
diff --git a/flow-tests/test-tailwindcss/pom.xml b/flow-tests/test-tailwindcss/pom.xml
diff --git a/flow-tests/test-tailwindcss/src/main/java/com/vaadin/flow/tailwindcsstest/TailwindCssView.java b/flow-tests/test-tailwindcss/src/main/java/com/vaadin/flow/tailwindcsstest/TailwindCssView.java
diff --git a/flow-tests/test-tailwindcss/src/main/resources/vaadin-featureflags.properties b/flow-tests/test-tailwindcss/src/main/resources/vaadin-featureflags.properties
diff --git a/flow-tests/test-tailwindcss/src/test/java/com/vaadin/flow/tailwindcsstest/TailwindCssIT.java b/flow-tests/test-tailwindcss/src/test/java/com/vaadin/flow/tailwindcsstest/TailwindCssIT.java

Original file line number	Diff line number	Diff line change
`@@ -310,6 +310,10 @@ Map<String, String> getDefaultDependencies() {`
`310`	`310`	`dependencies`
`311`	`311`	`.putAll(readDependencies("vaadin-router", "dependencies"));`
`312`	`312`	`}`
	`313`	`+ if (FrontendUtils.isTailwindCssEnabled(options)) {`
	`314`	`+ dependencies`
	`315`	`+ .putAll(readDependencies("tailwindcss", "dependencies"));`
	`316`	`+ }`
`313`	`317`	`putHillaComponentsDependencies(dependencies, "dependencies");`
`314`	`318`	`return dependencies;`
`315`	`319`	`}`
`@@ -373,6 +377,9 @@ Map<String, String> getDefaultDevDependencies() {`
`373`	`377`	`defaults.putAll(`
`374`	`378`	`readDependencies("react-router", "devDependencies"));`
`375`	`379`	`}`
	`380`	`+ if (FrontendUtils.isTailwindCssEnabled(options)) {`
	`381`	`+ defaults.putAll(readDependencies("tailwindcss", "devDependencies"));`
	`382`	`+ }`
`376`	`383`
`377`	`384`	`// Add workbox dependencies only when PWA is enabled`
`378`	`385`	`if (frontDeps != null && frontDeps.getPwaConfiguration() != null`