How to setup the Java SDK and use JavaFX with macOS/Windows

Visit the Gluon Scene Builder website to download the latest version (LTS recommended, e.g., 23). Install it.

• Go to Settings/Preferences > Languages & Frameworks > JavaFX.
• Set "Path to SceneBuilder" to your installation (e.g., /Applications/SceneBuilder.app on macOS, or C:\Program Files\SceneBuilder\SceneBuilder.exe on Windows).

• Install the SceneBuilder extension for Visual Studio Code.
• Open the Command Palette (Cmd+Shift+P on macOS, Ctrl+Shift+P on Windows)
• Type Configure Scene Builder path and press enter
• Browse to and select your installed Scene Builder executable

• Once configured, you can right-click an .fxml file in the VS Code explorer and choose "Open in Scene Builder". We'll cover how to create the project and open it in Scene Builder in the next step below.

• File > New > Project...
• Select JavaFX.
• Choose your project SDK (e.g., Java 21).
• Select Maven or Gradle as the build system.
• Fill in project details (Name, GroupId, ArtifactId). Click Create.

• Open the Command Palette (Cmd+Shift+P on macOS, Ctrl+Shift+P on Windows).
• Type Java: Create Java Project and press Enter
• Select JavaFX from the list
• It'll ask for your desired repository version number for this new project, you can just hit enter to proceed with the default ('version' 1.0-SNAPSHOT)
• When prompted to confirm (Y/N), make sure you hit N to be able to change the JavaFX version to 21 (no other details should need changed, just hit enter to proceed with the default each time)
• Choose a folder location for your new project

• Once created, VS Code will open the new project. You can test run it:
  • Open the App.java file (usually under src/main/java/com/example/).
  • Click the "Run" button that appears above the main method or press F5.

• After the project is successfully created, VS Code will show a notification. Click Open to load the project in a new window.

• In Project tool window, navigate to your FXML file (e.g., src/main/resources/com/example/hello-view.fxml).
• Right-click > Open In SceneBuilder.

• In Explorer, navigate to FXML file (e.g., src/main/resources/com/example/primary.fxml).
• Right-click > Open in Scene Builder.

• Issue: Errors like "package does not exist", "cannot find symbol", or runtime linkage errors with JavaFX components.
• Fix: Ensure your JavaFX version (in pom.xml or build.gradle) is compatible with your project's JDK. For JDK 21, use JavaFX 21+.
  ✕−+

  <!-- Maven pom.xml example for JavaFX 21 with JDK 21 -->
  <properties>
      <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
      <maven.compiler.release>21</maven.compiler.release> <!-- Corresponds to JDK version -->
      <javafx.version>21.0.2</javafx.version> <!-- Or latest compatible JavaFX 21+ version -->
  </properties>
  
  <dependencies>
      <dependency>
          <groupId>org.openjfx</groupId>
          <artifactId>javafx-controls</artifactId>
          <version>${javafx.version}</version>
      </dependency>
      <dependency>
          <groupId>org.openjfx</groupId>
          <artifactId>javafx-fxml</artifactId>
          <version>${javafx.version}</version>
      </dependency>
      <!-- Add other JavaFX modules as needed: javafx-graphics, javafx-media, etc. -->
  </dependencies>
  
  <build>
      <plugins>
          <plugin>
              <groupId>org.apache.maven.plugins</groupId>
              <artifactId>maven-compiler-plugin</artifactId>
              <version>3.11.0</version> <!-- Or newer -->
              <configuration>
                  <release>${maven.compiler.release}</release>
              </configuration>
          </plugin>
          <plugin>
              <groupId>org.openjfx</groupId>
              <artifactId>javafx-maven-plugin</artifactId>
              <version>0.0.8</version> <!-- Or newer -->
              <configuration>
                  <!-- Ensure this matches your main application class -->
                  <mainClass>com.example.yourproject.YourMainAppClass</mainClass>
              </configuration>
              <executions>
                  <execution>
                      <!-- Default configuration for running via IDE -->
                      <id>default-cli</id>
                      <configuration>
                          <mainClass>com.example.yourproject.YourMainAppClass</mainClass>
                      </configuration>
                  </execution>
              </executions>
          </plugin>
      </plugins>
  </build>
  

  Show all code
• Verify JDK in IDE: Confirm IDE's project SDK matches your JavaFX dependencies and build config.
• For general JDK, JAVA_HOME, multiple Java versions, and build system (Maven/Gradle) setup, refer to the Core Java, Maven & Gradle Setup Guide.

• Issue: "Open in SceneBuilder" option missing or not working.
• Fix:
  1. Confirm Scene Builder is installed.
  2. Verify IDE path to Scene Builder is correct (Part 2.2 & 2.3).
  3. Ensure FXML file is valid XML.
  4. Restart IDE.

• Issue: javafx.fxml.LoadException, InvocationTargetException, ClassNotFoundException.
• Fixes:
  1. Controller Class Path: fx:controller in FXML must be fully qualified (e.g., com.example.yourproject.MyController).
     ✕−+

     <VBox xmlns:fx="http://javafx.com/fxml/1" fx:controller="com.example.yourproject.PrimaryController">...</VBox>
     

  2. Controller Constructor: Must have a no-argument constructor.
  3. @FXML Annotations: UI elements in FXML with fx:id need corresponding @FXML annotated fields in the controller.
     ✕−+

     // PrimaryController.java
     public class PrimaryController {
         @FXML private Label myLabel; // fx:id="myLabel"
         @FXML private void initialize() { /* ... */ }
     }
     

  4. Resource Path: FXML files in correct resource path (e.g., src/main/resources/com/example/yourproject/) and loaded correctly:
     ✕−+

     Parent root = FXMLLoader.load(getClass().getResource("primary.fxml")); // Relative to class
     // Or: FXMLLoader.load(getClass().getResource("/com/example/yourproject/primary.fxml")); // Absolute from classpath root
     

  5. Build System: Ensure Maven/Gradle includes resources.

• Sync Project: Reads your pom.xml file and updates IntelliJ IDEA's project structure, dependencies, and settings to match. Use this after making changes to the pom.xml or if you suspect the IDE is out of sync.
• Generate Sources and Update Folders: Runs Maven phases that might generate source code (e.g., from annotation processors or build plugins) and tells IDEA to recognize these generated sources/folders correctly.
• Ignore Projects: Temporarily tells IntelliJ IDEA to stop treating the selected module as a Maven project. This can be useful for troubleshooting or excluding a module without removing it.
• Unlink Maven Projects: Completely removes the Maven integration from the project within IntelliJ IDEA. The pom.xml file remains, but IDEA will no longer manage dependencies or build configurations through Maven for this project until you re-import it.
• Create 'settings.xml': Creates a Maven settings.xml file in your user's .m2 directory (~/.m2/settings.xml) if one doesn't exist. This file allows you to configure user-specific Maven settings like custom repository locations, proxy settings, or server credentials.
• Download Sources / Documentation: Fetches the source code (.java files) or Javadoc documentation for your project's dependencies from the Maven repositories. This allows you to navigate into library code or view documentation directly within the IDE. "Download Sources and Documentation" does both.
• Show Effective POM: Calculates and displays the complete Project Object Model (POM) that Maven uses for the build. This includes configurations inherited from parent POMs, profiles, and settings, giving you the final, consolidated view of the build configuration.