webforJ build plugin 26.01

Open in ChatGPT

The webforJ build plugin runs webforJ's build time work as part of your Maven or Gradle build. You add it once, and it binds its goals to the phases you already run, with no separate frontend project to keep in sync. It drives the frontend bundler, compiling the frontend, running the frontend tests, and serving the development watch.

Adding the plugin

A webforJ project created from an archetype already has the plugin. To add it to an existing project:

Maven

Declaring the plugin with <extensions>true</extensions> binds its goals to the build with no execution blocks to write:

pom.xml

<plugin>
  <groupId>com.webforj</groupId>
  <artifactId>webforj-maven-plugin</artifactId>
  <extensions>true</extensions>
</plugin>

Gradle

Add the plugin through a buildscript classpath dependency and apply it:

build.gradle

buildscript {
  repositories {
    mavenCentral()
  }
  dependencies {
    classpath "com.webforj:webforj-gradle-plugin:${webforjVersion}"
  }
}

apply plugin: 'com.webforj'

Goals

The plugin binds four goals, each to a phase you already run, so a normal mvn package or gradle build produces an app with its frontend compiled in, and mvn test runs the frontend tests alongside the Java tests.

Maven goal	Gradle task	Phase	What it does
bundle	webforjBundle	prepare-package	Compiles the frontend for production
test	webforjTest	test	Runs the frontend tests
clean	webforjCleanFrontend	clean	Removes the generated frontend
watch	webforjWatch	run by hand	Rebuilds on change during development

The watch goal is the one you run by hand during development, alongside the app. Its reload behavior is covered in Frontend watch.

Options

Set options as Maven <configuration> (or -D properties on the command line), and as Gradle webforj { } extension values. The two build tools mirror each other.

Option	Maven property	Gradle	Default	Purpose
Bun version	webforj.bundler.version	bunVersion	managed	Pin the Bun version for reproducible builds
Bun binary	webforj.bundler.path	bunPath	download	Use an existing Bun binary instead of downloading
Cache directory	webforj.bundler.cacheDir	cacheDir	${user.home}/.webforj/bun	Where managed Bun binaries are cached
Source root	webforj.bundler.sourceRoot	sourceRoot	src/main/frontend	Where the frontend entry sources live
Work directory	webforj.bundler.workDir	workDir	target/bundle	Where the plugin writes its generated build files
Extensions	plugins	plugins	—	Turn an extension on or off by id, such as webforj-tailwind
Exclude packages	webforj.bundler.excludePackages	excludePackages	—	Package prefixes to skip during the annotation scan
Eager	webforj.bundler.eager	eager	false	Load the whole frontend at app start instead of per view, see Eager bundle
Test arguments	webforj.bundler.testArgs	testArgs	—	Extra arguments passed to the frontend test runner
Skip tests	skipTests, maven.test.skip	—	false	Skip the frontend tests

For example, to pin the Bun version and turn on Tailwind:

Maven

pom.xml

<plugin>
  <groupId>com.webforj</groupId>
  <artifactId>webforj-maven-plugin</artifactId>
  <extensions>true</extensions>
  <configuration>
    <version>1.3.0</version>
    <plugins>
      <webforj-tailwind>true</webforj-tailwind>
    </plugins>
  </configuration>
</plugin>

Gradle

build.gradle

webforj {
  bunVersion = '1.3.0'
  plugins.put('webforj-tailwind', 'true')
}