Javelle

Javelle is a Java-first UI framework foundation for SPA, SSR, MVC, UI components, native-style mobile shells, plugins, and runtime packaging.

Maven group:

one.nextera.openat.javelle

Quick start

Starting with a fresh laptop? Follow the beginner setup guide for Ubuntu, Windows, and macOS to install Java, download the released CLI, create an app, and verify your first run and build.

The npm package is a thin cross-platform launcher over the Javelle CLI jar (it runs java -jar, so it works on Windows, macOS, and Linux without bash). It installs both javelle-cli and javelle aliases and needs only a JDK 21+:

# Interactive picker (run with no app name on a terminal)
npx @nextera.one/javelle-cli new

# A blank app
npx @nextera.one/javelle-cli new hello-javelle --package dev.example.hello

# Pick targets at create time (web is always included)
npx @nextera.one/javelle-cli new hello --mode pwa,android

# The canonical full sample app
npx @nextera.one/javelle-cli create my-full-app --sample app-shell

new scaffolds a blank app; create --sample app-shell creates the canonical full Javelle sample with MainLayout.jvl, header, drawer, footer, all built-in modes, and app-local scripts for web/native/APK/AAB builds. Remote --from gh:owner/repo overlays can still customize the base scaffold. Both accept:

| Flag | Purpose | | --- | --- | | --package <pkg> | Java base package (default app) | | --mode <m,...> | Extra targets: pwa ssr mvc mobile android ios desktop, or all | | --format html\|jvl | Page templates as Java+.html or .jvl single-file components | | --mvc-kind <k> | With --mode mvc: basic, secure, or spring-fabric | | --android-package / --ios-bundle-id | Native app/bundle id | | --group-id / --javelle-version | Generated Maven coordinates |

From a checkout you can use the same CLI directly:

./bin/javelle new hello-javelle --package dev.example.hello --mode pwa

The scripts/create-from-maven.sh shim maps the older <feature> <app> grammar onto javelle new <app> --mode <feature>.

Build And Dev

Build the local framework first:

mvn install

A generated app ships cross-platform run/build/add scripts (.sh on macOS/Linux, .bat/.ps1 on Windows) plus per-mode helpers under scripts/:

cd hello-javelle
./run.sh                 # dev server (web); run.bat / run.ps1 on Windows
./build.sh all           # build every enabled target
./add.sh mobile ssr      # enable more targets after create
scripts/release-all.sh   # release alias for CI/release jobs

Or drive the CLI directly:

javelle dev --mode web --port 3000
javelle build --mode all
javelle mode add android

The dev server watches app resources, Java sources, mode files, and project config, then reloads connected browsers on change.

IDEL apps

Javelle can compile its strict native component subset into the architecture-neutral IDEL site bundle already consumed by IDEL Browser Lite:

javelle build --mode idel \
  --package-id org.example/hello \
  --version 1.0.0

The output is target/javelle/idel/hello-1.0.0.idel.pkg plus a publication receipt. The package contains canonical IDEL source, not HTML, JavaScript, a WebView, or platform-specific binaries. Unsupported components and dynamic semantics fail the build instead of falling back to the web runtime. By default every literal application route with a resolvable page template is packaged; pass --template <file> for the explicit single-view home build. The current Browser Lite v1 bundle cannot carry local asset bytes, so local image paths also fail closed until a digest-bound resource contract exists.

An optional src/main/javelle/package/seo.json publishes deterministic HTTPS discovery inputs next to the package: discovery.json, robots.txt, sitemap.xml, and, when enabled, llms.txt. SEO routes must be present in the compiled IDEL package; the discovery files remain separate unsigned publication inputs and never add HTML or browser behavior to .idel.pkg.

This artifact is currently an unsigned IDEL registry blob. Production install still requires the IDEL release signature, provenance, SBOM, and transparency pipeline; the IDEL OS package broker is not implemented yet. See docs/idel-apps.md for the exact boundary and the IDEL Run/NexRun relationship.

Developer Documentation Site

Start with the documentation hub for task-based navigation, examples for every module, and documentation validation.

The static developer docs are generated by the javelle-docs module. They cover quick start, CLI usage, code snippets, sample code, templates, routing, MVC, UI components, directives, plugins, forms, store, i18n, TES, utils, and Codex-style agent rules.

./mvnw -pl javelle-docs exec:java
open target/docs/index.html

On Linux, use xdg-open target/docs/index.html; on Windows, open the same file from File Explorer or a browser.

Focused guides include docs/javelle-native.md for real native source generation and docs/javelle-litert.md for Java-first on-device inference with LiteRT.js. IDEL application packaging is covered by docs/idel-apps.md.

Sample App

The repository no longer carries generated sample projects. Create the one canonical sample from the CLI when needed:

javelle create my-full-app --sample app-shell --package app
cd my-full-app
./build.sh all
scripts/build-apk.sh --skip-aab
scripts/build-aab.sh
scripts/create-apk.sh
scripts/create-aab.sh
scripts/release-all.sh
scripts/build-ios.sh
scripts/build-ubuntu-touch.sh
scripts/build-windows-mobile.sh

More project creation docs:

docs/create-javelle-projects.md
docs/cli-commands.md

App-local npm interop and .d.ts wrapper generation:

docs/npm-interop.md

Quorium-style module composition, typed tokens, and dynamic route application:

docs/quorium-javelle.md

The final reactor, ownership map, validation gates, and release checklist are recorded in docs/final-state.md.

The framework source packages currently remain under io.javelle.*.

Final consolidated modules

The implementation is organized around owning artifacts only:

• javelle-core owns io.javelle.router.
• javelle-reactive owns io.javelle.store.
• javelle-ui-foundation includes CSS, themes, Material presets, motion, fonts, and accessibility.
• javelle-ui-components owns the Material-style j-* component surface.
• javelle-ui-xcomponents owns the Eclat-style jx-* component surface.

The empty compatibility projects and their BOM coordinates have been removed. Applications should depend on the owning artifacts above.

Java package names remain unchanged, so source imports do not need migration.