Javelle .jvl — VS Code Extension

Editor support for Javelle Single-File Components (.jvl): formatting, IntelliSense, auto-import, diagnostics with quick fixes, navigation and the Javelle CLI/Studio tooling with fast live preview.

A .jvl file looks like:

<template>
  <j-page class="j-page my-page">
    <h1>{{ title }}</h1>
    <j-button color="primary" variant="filled" data-jvl-on-click="refresh">Refresh</j-button>
  </j-page>
</template>

<code lang="java">
@Component("my-page")
public final class MyPage {
  @State private String title = "Hello, Javelle";

  public void refresh() {
    Composables.useNotify().info("Refreshed");
  }
}
</code>

<style scoped>
.my-page { padding: var(--jv-space-lg); }
</style>

Fast Preview

Open a file in your Javelle app and click the Fast Preview icon in the .jvl editor title, run Javelle: Fast Preview, or press Ctrl+K V (Cmd+K V on macOS). The Explorer and editor context menus also offer it.

Fast Preview finds the nearest javelle.config.json, starts javelle dev with jvl.previewMode and jvl.previewPort, and opens the running app beside the editor without prompts. It waits for HTTP readiness and reuses the server and panel on repeated clicks, keeping the app state and selected preview size. Switching to another app restarts the server for that app. The preview toolbar offers desktop, phone, landscape, tablet, PWA and SSR frames.

The requested file is saved before launching if it has unsaved changes. Subsequent saves use Javelle's hot reload for templates, styles and Java; web mode uses the existing CLI development pipeline without a Maven package step. This previews the whole app, including its layout and routes. Components are displayed where the app mounts them. JVM SSR mode still needs compilation.

With the default jvl.cliPath, generated apps use their scripts/javelle.sh (scripts/javelle.bat on Windows) when present, otherwise javelle from PATH. A configured relative CLI path such as bin/javelle resolves from the owning workspace folder, including when the app is nested in a larger repository. Remote workspaces forward the preview URL through VS Code.

Use Javelle: Stop Dev Server to stop it. Closing the panel keeps the server available for the next preview; unloading the extension stops it. Startup errors appear in Javelle .jvl output. Change jvl.previewPort if occupied, or increase jvl.previewStartupTimeout for a first-time toolchain download or SSR compilation. Starting a preview requires a trusted workspace.

Formatting

Format Document (and format-on-save, range formatting) formats every block with a Javelle-aware built-in formatter, then normalizes the file skeleton: block tags at column 0, one blank line between blocks, template content indented one level, Java and CSS at column 0 (matching the framework examples), a single trailing newline.

• Template (HTML) — re-indents elements, wraps long attribute lists one per line with > on its own line, fills text and inline elements up to the print width without introducing whitespace between adjacent inline elements, keeps {{ }} interpolations, comments, <pre>/<textarea> content and named <template #slot> blocks intact, and collapses whitespace in class values.
• Java — re-indents from brace/paren structure (blocks, switch labels, lambda and anonymous-class bodies, chained calls, continuation lines, JSON object literals, text blocks kept verbatim) and normalizes spacing around keywords, commas, parentheses, braces, assignment/comparison operators and ->. Lines are never split or joined.
• CSS / SCSS — one declaration per line, comma-separated selectors one per line, spaced combinators, property: value;, nested rules and at-rules, } @else {, comments preserved.

Every built-in formatter is whitespace-only and verifies that before returning; structurally broken markup or CSS is only re-indented, never rewritten.

Set jvl.format.template, jvl.format.code or jvl.format.style to external to hand a block to the formatter VS Code has for that language (when that formatter supports virtual documents) instead. External formatting uses read-only snapshots and never creates Untitled editors. If a provider is unavailable or requires files on disk, Javelle falls back to its built-in formatter. The default built-in formatters cover HTML, Java, CSS and SCSS without scratch documents. jvl.format.printWidth and jvl.format.indent* tune the layout.

If saving opens Untitled files, check your [jvl] settings: the old javelle.vscode-jvl formatter ID selects the legacy extension. Select digital-pages.vscode-jvl as editor.defaultFormatter, update this extension, and reload VS Code. Existing Untitled tabs are left open so their contents are not discarded.

IntelliSense

Template

• <j-*> / <jx-*> component tags from the registries (333), local components from components/*.jvl, structural HTML tags, j-include / j-component snippets and closing-tag completion. Native form controls are filtered out of the standard HTML suggestions.
• Attributes per component (derived from each component's Java builder and the compiler's attribute contract, e.g. variant, color, side, mode, storage-key), common Javelle attributes, every directive family (v-*, jv-* shorthands, data-jv-*, data-jvl-on-*, :attr, @event, #slot) with modifier completion (v-model.trim, @click.prevent). Attributes already on the tag are hidden.
• Attribute values: enum values (variant="filled"), Javelle utility classes plus classes from this file's <style> and template, Java action methods for data-jvl-on-* / @event, writable @State fields for v-model, route paths from app.route(...) / @Page for to=, resource paths for j-include src=, Material icon names, drawer and tab-panel ids, runtime action names.
• Expressions ({{ }}, :attr, v-if, data-jv-text, handler arguments): loop variables in scope, @State/@Prop/@Model fields, @Computed values, actions, backing-class members, t('key') / tn() / env() / $env. helpers, translation keys from i18n/*.json, .env keys, and size() / isEmpty() / contains() idioms after a dot.

Java block

• Offline catalog of the public Javelle API (1,150 types, 6,700 methods with Javadoc summaries) shipped in data/javelle-types.json: type completion with auto-import, static and instance member completion (Http., LocalStorage., Composables.useNotify()., plugins().get(X.class)., local variables by declared type, enum constants, nested types), signature help, and hover documentation — no Java language server required.
• Workspace types and the Java extension's Maven index remain merged in.
• Local fields and methods, annotations with snippets (@Watch("field") offers state fields, @Template("...") offers sibling templates, @Page("/...") offers routes), browser facades (Console, Location, ...), storage keys used in the file, and member-level snippets (state, computed, watch, action, onMounted, httpGet, httpFunc, notify, ...).
• Organize imports (source.organizeImports, command Javelle: Organize Imports in Block) and an Import '...' quick fix on any unimported Javelle type. jvl.autoImport controls automatic imports.

cd vscode-jvl
npm install
npm run data:sync   # regenerate data/*.json from the framework sources
npm test            # data freshness, compile, unit tests

npx @vscode/vsce package
code --install-extension vscode-jvl-0.8.0.vsix