Class FrontendUtils

java.lang.Object
io.jmix.flowui.devserver.frontend.FrontendUtils

public class FrontendUtils extends Object
A class for static methods and definitions that might be used in different locations.
  • Field Details

    • PROJECT_BASEDIR

      public static final String PROJECT_BASEDIR
      See Also:
    • DEFAULT_NODE_DIR

      public static final String DEFAULT_NODE_DIR
      Default folder for the node related content. It's the base directory for Constants.PACKAGE_JSON and NODE_MODULES. By default it's the project root folder.
      See Also:
    • NODE_MODULES

      public static final String NODE_MODULES
      Location for the installed node packages. This folder is always considered by node, even though we define extra folders with the NODE_PATH.
      See Also:
    • FRONTEND

      public static final String FRONTEND
      Default folder used for source and generated folders.
      See Also:
    • GENERATED

      public static final String GENERATED
      Default folder for client-side generated files inside the project root frontend folder.
      See Also:
    • DEFAULT_FRONTEND_DIR

      public static final String DEFAULT_FRONTEND_DIR
      Path of the folder containing application frontend source files, it needs to be relative to the DEFAULT_NODE_DIR By default it is /src/main/frontend in the project folder.
      See Also:
    • LEGACY_FRONTEND_DIR

      public static final String LEGACY_FRONTEND_DIR
      Path of the old folder containing application frontend source files, it needs to be relative to the DEFAULT_NODE_DIR By default the old folder is /frontend in the project folder.
      See Also:
    • VITE_CONFIG

      public static final String VITE_CONFIG
      The name of the vite configuration file.
      See Also:
    • VITE_GENERATED_CONFIG

      public static final String VITE_GENERATED_CONFIG
      The name of the generated vite configuration file.
      See Also:
    • SERVICE_WORKER_SRC

      public static final String SERVICE_WORKER_SRC
      The name of the service worker source file for InjectManifest method of the workbox plugin.
      See Also:
    • SERVICE_WORKER_SRC_JS

      public static final String SERVICE_WORKER_SRC_JS
      The JavaScript version of the service worker file, for checking if a user has a JavaScript version of a custom service worker file already.
      See Also:
    • JAR_RESOURCES_FOLDER

      public static final String JAR_RESOURCES_FOLDER
      The folder inside the 'generated' folder where frontend resources from jars are copied.
      See Also:
    • JAR_RESOURCES_IMPORT

      public static final String JAR_RESOURCES_IMPORT
      The location where javascript files present in jar resources are copied and can be imported from.
      See Also:
    • JAR_RESOURCES_IMPORT_FRONTEND_RELATIVE

      public static final String JAR_RESOURCES_IMPORT_FRONTEND_RELATIVE
      The location where javascript files present in jar resources are copied and can be imported from, relative to the frontend folder.
    • IMPORTS_NAME

      public static final String IMPORTS_NAME
      Name of the file that contains application imports, javascript, theme and style annotations.
      See Also:
    • IMPORTS_D_TS_NAME

      public static final String IMPORTS_D_TS_NAME
      The TypeScript definitions for the IMPORTS_NAME file.
      See Also:
    • IMPORTS_WEB_COMPONENT_NAME

      public static final String IMPORTS_WEB_COMPONENT_NAME
      Name of the file that contains application imports, javascript, theme and style annotations used when embedding Flow as web-component.
      See Also:
    • THEME_IMPORTS_D_TS_NAME

      public static final String THEME_IMPORTS_D_TS_NAME
      See Also:
    • THEME_IMPORTS_NAME

      public static final String THEME_IMPORTS_NAME
      See Also:
    • BOOTSTRAP_FILE_NAME

      public static final String BOOTSTRAP_FILE_NAME
      File name of the bootstrap file that is generated in frontend GENERATED folder. The bootstrap file is always executed in a Vaadin app.
      See Also:
    • WEB_COMPONENT_BOOTSTRAP_FILE_NAME

      public static final String WEB_COMPONENT_BOOTSTRAP_FILE_NAME
      File name of the web component bootstrap file that is generated in frontend GENERATED folder. The bootstrap file is always executed in an exported web component.
      See Also:
    • FEATURE_FLAGS_FILE_NAME

      public static final String FEATURE_FLAGS_FILE_NAME
      File name of the feature flags file that is generated in frontend GENERATED folder. The feature flags file contains code to define feature flags as globals that might be used by Vaadin web components or application code.
      See Also:
    • INDEX_HTML

      public static final String INDEX_HTML
      File name of the index.html in client side.
      See Also:
    • WEB_COMPONENT_HTML

      public static final String WEB_COMPONENT_HTML
      File name of the web-component.html in client side.
      See Also:
    • INDEX_TS

      public static final String INDEX_TS
      File name of the index.ts in client side.
      See Also:
    • INDEX_JS

      public static final String INDEX_JS
      File name of the index.js in client side.
      See Also:
    • INDEX_TSX

      public static final String INDEX_TSX
      File name of the index.tsx in client side.
      See Also:
    • VITE_DEVMODE_TS

      public static final String VITE_DEVMODE_TS
      File name of Vite helper used in development mode.
      See Also:
    • ROUTES_TS

      public static final String ROUTES_TS
      See Also:
    • ROUTES_TSX

      public static final String ROUTES_TSX
      See Also:
    • ROUTES_FLOW_TSX

      public static final String ROUTES_FLOW_TSX
      See Also:
    • ROUTES_JS

      public static final String ROUTES_JS
      See Also:
    • DEFAULT_PROJECT_FRONTEND_GENERATED_DIR

      public static final String DEFAULT_PROJECT_FRONTEND_GENERATED_DIR
      Default generated path for generated frontend files.
      See Also:
    • PARAM_FRONTEND_DIR

      public static final String PARAM_FRONTEND_DIR
      A parameter for overriding the DEFAULT_FRONTEND_DIR folder.
      See Also:
    • PARAM_FLOW_FRONTEND_DIR

      public static final String PARAM_FLOW_FRONTEND_DIR
      See Also:
    • PARAM_THEME_VALUE

      public static final String PARAM_THEME_VALUE
      See Also:
    • PARAM_THEME_VARIANT

      public static final String PARAM_THEME_VARIANT
      See Also:
    • PARAM_THEME_CLASS

      public static final String PARAM_THEME_CLASS
      See Also:
    • PARAM_STUDIO_DIR

      public static final String PARAM_STUDIO_DIR
      See Also:
    • VIEW_DESIGNER_FOLDER

      public static final String VIEW_DESIGNER_FOLDER
      See Also:
    • FRONTEND_FOLDER

      public static final String FRONTEND_FOLDER
      See Also:
    • BUILD_FOLDER

      public static final String BUILD_FOLDER
      See Also:
    • FLOW_FRONTEND_FOLDER

      public static final String FLOW_FRONTEND_FOLDER
      See Also:
    • GENERATED_FRONTEND_FOLDER

      public static final String GENERATED_FRONTEND_FOLDER
      See Also:
    • PARAM_IGNORE_VERSION_CHECKS

      public static final String PARAM_IGNORE_VERSION_CHECKS
      Set to true to ignore node/npm tool version checks.
      See Also:
    • FRONTEND_FOLDER_ALIAS

      public static final String FRONTEND_FOLDER_ALIAS
      A special prefix used to map imports placed in the DEFAULT_FRONTEND_DIR. e.g. import 'Frontend/foo.js'; references the filefrontend/foo.js.
      See Also:
    • FRONTEND_GENERATED_FLOW_IMPORT_PATH

      public static final String FRONTEND_GENERATED_FLOW_IMPORT_PATH
      The prefix used to import files generated by Flow.
      See Also:
    • HILLA_VIEWS_PATH

      public static final String HILLA_VIEWS_PATH
      The default directory in frontend directory, where Hilla views are located.
      See Also:
    • TOKEN_FILE

      public static final String TOKEN_FILE
      File used to enable npm mode.
      See Also:
    • CHUNKS

      public static final String CHUNKS
      A key in a Json object for chunks list.
      See Also:
    • EXPORT_CHUNK

      public static final String EXPORT_CHUNK
      The entry-point key used for the exported bundle.
      See Also:
    • CSS_IMPORTS

      public static final String CSS_IMPORTS
      A key in a Json object for css imports data.
      See Also:
    • JS_MODULES

      public static final String JS_MODULES
      A key in a Json object for js modules data.
      See Also:
    • PARAM_TOKEN_FILE

      public static final String PARAM_TOKEN_FILE
      A parameter informing about the location of the TOKEN_FILE.
      See Also:
    • DISABLE_CHECK

      public static final String DISABLE_CHECK
      See Also:
    • YELLOW

      public static final String YELLOW
      See Also:
    • RED

      public static final String RED
      See Also:
    • GREEN

      public static final String GREEN
      See Also:
    • BRIGHT_BLUE

      public static final String BRIGHT_BLUE
      See Also:
  • Method Details

    • getOsName

      public static String getOsName()
      Get the Operating System name from the os.name system property.
      Returns:
      operating system name
    • isWindows

      public static boolean isWindows()
      Check if the current os is Windows.
      Returns:
      true if windows
    • streamToString

      public static String streamToString(InputStream inputStream)
      Read a stream and copy the content into a String using system line separators for all 'carriage return' characters.
      Parameters:
      inputStream - the input stream
      Returns:
      the string
    • createProcessBuilder

      public static ProcessBuilder createProcessBuilder(List<String> command)
      Creates a process builder for the given list of program and arguments. If the program is defined as an absolute path, then the directory that contains the program is also appended to PATH so that the it can locate related tools.
      Parameters:
      command - a list with the program and arguments
      Returns:
      a configured process builder
    • getIndexHtmlContent

      public static String getIndexHtmlContent(com.vaadin.flow.server.VaadinService service) throws IOException
      Gets the content of the frontend/index.html file which is served by vite in dev-mode and read from classpath in production mode.

      NOTE: In dev mode, the file content is fetched using an http request so that we don't need to have a separate index.html's content watcher. Auto-reloading will work automatically, like other files in the `frontend/` folder.

      Parameters:
      service - the vaadin service
      Returns:
      the content of the index html file as a string, null if not found.
      Throws:
      IOException - on error when reading file
    • getWebComponentHtmlContent

      public static String getWebComponentHtmlContent(com.vaadin.flow.server.VaadinService service) throws IOException
      Gets the content of the frontend/web-component.html file which is served by vite in dev-mode and read from classpath in production mode.

      NOTE: In dev mode, the file content is fetched using an http request so that we don't need to have a separate web-component.html's content watcher. Auto-reloading will work automatically, like other files in the `frontend/` folder.

      Parameters:
      service - the vaadin service
      Returns:
      the content of the web-component.html file as a string, null if not found.
      Throws:
      IOException - on error when reading file
    • getFrontendFileFromDevModeHandler

      public static InputStream getFrontendFileFromDevModeHandler(com.vaadin.flow.server.VaadinService service, String path)
      Get the contents of a frontend file from the running dev server.
      Parameters:
      service - the Vaadin service.
      path - the file path.
      Returns:
      an input stream for reading the file contents; null if there is no such file or the dev server is not running.
    • resolveFrontendPath

      public static File resolveFrontendPath(File projectRoot, com.vaadin.flow.function.DeploymentConfiguration deploymentConfiguration, String path)
      Looks up the frontend resource at the given path. If the path starts with ./, first look in "./src/main/frontend/", then in "jar-resources". If the path does not start with ./, look in node_modules instead.
      Parameters:
      projectRoot - the project root folder.
      deploymentConfiguration - the active deployment configuration
      path - the file path.
      Returns:
      an existing File , or null if the file doesn't exist.
    • getLegacyFrontendFolderIfExists

      public static File getLegacyFrontendFolderIfExists(File projectRoot, File frontendDir)
      Get the legacy frontend folder if available and new folder doesn't exist.
      Parameters:
      projectRoot - project's root directory
      frontendDir - the frontend directory location from project's configuration
      Returns:
      correct folder or legacy folder if not user defined
    • resolveFrontendPath

      public static File resolveFrontendPath(File projectRoot, String path, File frontendDirectory)
      Looks up the fronted resource at the given path. If the path starts with ./, first look in frontend, then in "jar-resources". If the path does not start with ./, look in node_modules instead.
      Parameters:
      projectRoot - the project root folder.
      path - the file path.
      frontendDirectory - the frontend directory.
      Returns:
      an existing File , or null if the file doesn't exist.
    • getJarResourceString

      public static String getJarResourceString(String jarImport, com.vaadin.flow.server.frontend.scanner.ClassFinder finder)
      Get resource from JAR package.
      Parameters:
      jarImport - jar file to get (no resource folder should be added)
      Returns:
      resource as String or null if not found
    • getJarResourcesFolder

      public static File getJarResourcesFolder(File frontendDirectory)
      Get the front-end resources folder. This is where the contents of JAR dependencies are copied to.
      Parameters:
      frontendDirectory - project's frontend directory
      Returns:
      a File representing a folder with copied resources
    • getFrontendGeneratedFolder

      public static File getFrontendGeneratedFolder(File frontendDirectory)
    • getProjectFrontendDir

      public static File getProjectFrontendDir(com.vaadin.flow.server.AbstractConfiguration configuration)
      Get directory where project's frontend files are located.
      Parameters:
      configuration - the current deployment configuration
      Returns:
      DEFAULT_FRONTEND_DIR or value of PARAM_FRONTEND_DIR if it is set.
    • getUnixRelativePath

      public static String getUnixRelativePath(Path source, Path target)
      Get relative path from a source path to a target path in Unix form. All the Windows' path separator will be replaced.
      Parameters:
      source - the source path
      target - the target path
      Returns:
      unix relative path from source to target
    • getUnixPath

      public static String getUnixPath(Path source)
      Get path as a String in Unix form.
      Parameters:
      source - path to get
      Returns:
      path as a String in Unix form.
    • getVersion

      protected static com.vaadin.flow.server.frontend.FrontendVersion getVersion(String tool, List<String> versionCommand) throws FrontendUtils.UnknownVersionException
      Throws:
      FrontendUtils.UnknownVersionException
    • executeCommand

      public static String executeCommand(List<String> command) throws FrontendUtils.CommandExecutionException
      Executes a given command as a native process.
      Parameters:
      command - the command to be executed and it's arguments.
      Returns:
      process output string.
      Throws:
      FrontendUtils.CommandExecutionException - if the process completes exceptionally.
    • consumeProcessStreams

      public static CompletableFuture<com.vaadin.flow.internal.Pair<String,String>> consumeProcessStreams(Process process)
      Reads input and error stream from the give process asynchronously. The method returns a CompletableFuture that is completed when both the streams are consumed. Streams are converted into strings and wrapped into a Pair, mapping input stream into Pair.getFirst() and error stream into Pair.getSecond(). This method should be mainly used to avoid that Process.waitFor() hangs indefinitely on some operating systems because process streams are not consumed. See https://github.com/vaadin/flow/issues/15339 for an example case.
      Parameters:
      process - the process whose streams should be read
      Returns:
      a CompletableFuture that return the string contents of the process input and error streams when both are consumed, wrapped into a Pair.
    • parseFrontendVersion

      public static com.vaadin.flow.server.frontend.FrontendVersion parseFrontendVersion(String versionString) throws IOException
      Parse the version number of node/npm from version output string.
      Parameters:
      versionString - string containing version output, typically produced by tool --version
      Returns:
      FrontendVersion of versionString
      Throws:
      IOException - if parsing fails
    • getVaadinHomeDirectory

      public static File getVaadinHomeDirectory()
      Gets vaadin home directory (".vaadin" folder in the user home dir).

      The directory is created if it's doesn't exist.

      Returns:
      a vaadin home directory
    • commandToString

      public static String commandToString(String baseDir, List<String> command)
      Pretty prints a command line order. It split in lines adapting to 80 columns, and allowing copy and paste in console. It also removes the current directory to avoid security issues in log files.
      Parameters:
      baseDir - the current directory
      command - the command and it's arguments
      Returns:
      the string for printing in logs
    • getPackageVersionFromJson

      public static com.vaadin.flow.server.frontend.FrontendVersion getPackageVersionFromJson(elemental.json.JsonObject sourceJson, String pkg, String versionOrigin)
      Tries to parse the given package's frontend version or if it doesn't exist, returns null. In case the value cannot be parsed, logs an error and returns null.
      Parameters:
      sourceJson - json object that has the package
      pkg - the package name
      versionOrigin - origin of the version (like a file), used in error message
      Returns:
      the frontend version the package or null
    • console

      public static void console(String format, Object message)
      Intentionally send to console instead to log, useful when executing external processes.
      Parameters:
      format - Format of the line to send to console, it must contain a `%s` outlet for the message
      message - the string to show
    • console

      public static void console(Object message)
      See Also:
    • console

      public static void console(Object message, boolean logInFile)
    • console

      public static void console(String format, Object message, boolean logInFile)
    • logInFile

      public static void logInFile(String text, boolean createLogFileIfNotExist, boolean throwExceptionIfLogFileNotExist)
    • logInFile

      public static void logInFile(String text, boolean createLogFileIfNotExist)
    • logInFile

      public static void logInFile(String text)
    • getLogFile

      @Nullable public static File getLogFile()
    • deleteNodeModules

      public static void deleteNodeModules(File nodeModules) throws IOException
      Try to remove the node_modules directory, if it exists inside the given base directory. Note that pnpm uses symlinks internally, so delete utilities that follow symlinks when deleting and/or modifying permissions may not work as intended.
      Parameters:
      nodeModules - the node_modules directory
      Throws:
      IOException - on failure to delete any one file, or if the directory name is not node_modules
    • deleteDirectory

      public static void deleteDirectory(File directory) throws IOException
      Recursively delete given directory and contents.

      Will not delete contents of symlink or junction directories, only the link file.

      Parameters:
      directory - directory to delete
      Throws:
      IOException - on failure to delete or read any one file
    • getFrontendServletPath

      public static String getFrontendServletPath(jakarta.servlet.ServletContext servletContext)
      Gets the servlet path (excluding the context path) for the servlet used for serving the VAADIN frontend bundle.
      Returns:
      the path to the servlet used for the frontend bundle. Empty for a /* mapping, otherwise always starts with a slash but never ends with a slash
    • getFlowGeneratedFolder

      public static File getFlowGeneratedFolder(File frontendFolder)
      Gets the folder where Flow generated frontend files are placed.
      Parameters:
      frontendFolder - the project frontend folder
      Returns:
      the folder for Flow generated files
    • getFlowGeneratedImports

      public static File getFlowGeneratedImports(File frontendFolder)
      Gets the location of the generated import file for Flow.
      Parameters:
      frontendFolder - the project frontend folder
      Returns:
      the location of the generated import JS file
    • getFlowGeneratedWebComponentsImports

      public static File getFlowGeneratedWebComponentsImports(File frontendFolder)
      Gets the location of the generated import file for exported web components.
      Parameters:
      frontendFolder - the project frontend folder
      Returns:
      the location of the generated import JS file for exported web components
    • getFlowGeneratedWebComponentsFolder

      public static File getFlowGeneratedWebComponentsFolder(File frontendFolder)
      Gets the folder where exported web components are generated.
      Parameters:
      frontendFolder - the project frontend folder
      Returns:
      the exported web components folder
    • isReactRouterRequired

      public static boolean isReactRouterRequired(File frontendDirectory)
      Auto-detects what router is used in a project based on what is imported in INDEX_TS file.
      Parameters:
      frontendDirectory - path to the frontend folder in a project.
      Returns:
      false if vaadin-router is used, true otherwise.
    • isHillaViewsUsed

      public static boolean isHillaViewsUsed(File frontendDirectory)
      Auto-detects if hilla views are used in the project based on what is in routes.ts or routes.tsx file. getProjectFrontendDir(AbstractConfiguration) can be used to get the frontend directory.
      Parameters:
      frontendDirectory - Target frontend directory.
      Returns:
      true if hilla views are used, false otherwise.
    • isHillaUsed

      public static boolean isHillaUsed(File frontendDirectory)
      Checks if Hilla is available and Hilla views are used in the project based on what is in routes.ts or routes.tsx file. getProjectFrontendDir(AbstractConfiguration) can be used to get the frontend directory.
      Returns:
      true if Hilla is available and Hilla views are used, false otherwise
    • isHillaUsed

      public static boolean isHillaUsed(File frontendDirectory, com.vaadin.flow.server.frontend.scanner.ClassFinder classFinder)
      Checks if Hilla is available and Hilla views are used in the project based on what is in routes.ts or routes.tsx file. getProjectFrontendDir(AbstractConfiguration) can be used to get the frontend directory. Given class finder is used to check the presence of Hilla in a classpath.
      Parameters:
      classFinder - class finder to check the presence of Hilla endpoint class
      Returns:
      true if Hilla is available and Hilla views are used, false otherwise
    • isReactModuleAvailable

      public static boolean isReactModuleAvailable(Options options)
      Is the React module available in the classpath.
      Returns:
      true if the React module is available, false otherwise
    • getClientRoutes

      public static List<String> getClientRoutes()
      Get all available client routes in a distinct list of route paths collected from all ClientRoutesProvider implementations found with Vaadin Lookup.
      Returns:
      a list of available client routes
    • getResourceAsStream

      public static InputStream getResourceAsStream(String name)
    • getResource

      public static URL getResource(String name)
    • findFreePort

      public static int findFreePort(int rangeStart, int rangeEnd)
    • getProjectBaseDir

      public static File getProjectBaseDir(com.vaadin.flow.server.startup.ApplicationConfiguration configuration)