Skip to content

About

jsass

The ultimate SASS compiler for Java / the JVM.

Early development

jsass 6 is still in the early stages of development. API breaks are to be expected! The current preview is 6.0.0-alpha.6, published to the GitLab package registry — not to Maven Central.

What jsass 6 is

jsass 6 runs dart-sass, the reference Sass implementation, in one of two ways:

  • inside the JVM on an embedded JavaScript engine: Javet in V8 or Node.js mode, or GraalJS through the GraalVM Polyglot API. No sass binary to install, no external process to manage;
  • as the native dart-sass executable in a subprocess, driven over the Embedded Sass Protocol. No JavaScript engine at all.

Either way there is no libsass any more, which has been deprecated and is what jsass 5 was built on.

jsass does not bundle dart-sass. You decide which version runs and where it comes from: a org.webjars.npm:sass WebJar on the classpath or a plain node_modules/sass directory for the JavaScript engines, a dart-sass release executable for the embedded engine. Upgrading Sass is a dependency bump in your build, not a jsass release.

How it differs from jsass 5

jsass 5 jsass 6
Sass implementation libsass (deprecated) dart-sass, supplied by you
Runtime native library via JNI Javet V8, Javet Node, GraalJS or native dart-sass
Compile API blocking Compiler.compileString(…) CompletableFuture<Output>, with a timeout
Sass module system @import only @use / @forward / @import
Custom functions reflection over annotated methods typed SassValue callbacks
Importers Collection<Import> apply(url, previous) dart-sass canonicalize / load
Output styles NESTED, EXPANDED, COMPACT, COMPRESSED EXPANDED, COMPRESSED
Java baseline Java 8 Java 21
Nullability undocumented JSpecify @NullMarked

Coming from jsass 5? The migration guide maps the old API onto the new one.

The modules

jsass 6 is a set of small artifacts under the io.bit3 group. You pick a compiler (the engine); a JavaScript engine also needs a module resolver and — usually just by putting it on the runtime classpath — a JSON deserializer. Everything else is optional. Every artifact is a Java module named after its root package.

Artifact Module What it is
jsass io.bit3.jsass The API: JsassCompiler, StringOptions, Output, importer / function / JSON SPI
jsass.js io.bit3.jsass.js The engine-neutral layer under every JavaScript engine: ModuleResolver, startup / compile scripts, the shared compiler core
jsass.javet io.bit3.jsass.javet The Javet adapter behind both Javet engines, and JavetOptions
jsass.javet.v8.compiler io.bit3.jsass.javet.v8 JavetV8JsassCompiler — the Javet V8 engine
jsass.javet.node.compiler io.bit3.jsass.javet.node JavetNodeJsassCompiler — the Javet Node.js engine
jsass.graaljs.compiler io.bit3.jsass.graaljs GraalJsJsassCompiler — the GraalJS engine, pure Java
jsass.embedded.compiler io.bit3.jsass.embedded EmbeddedJsassCompiler — native dart-sass over the Embedded Sass Protocol
jsass.webjar-module-resolver io.bit3.jsass.js.webjars Loads the Sass JS library from a WebJar (any engine)
jsass.node-modules-resolver io.bit3.jsass.js.nodemodules Loads the Sass JS library from node_modules/ (any engine)
jsass.webjar-importer io.bit3.jsass.webjar Resolves SCSS @use / @import against WebJars
jsass.jackson2 io.bit3.jsass.json.jackson2 JSON SPI implementation on Jackson 2.x
jsass.jackson3 io.bit3.jsass.json.jackson3 JSON SPI implementation on Jackson 3.x

Where to go next

  • Getting started

    Add the dependencies and compile your first stylesheet.

    getting started

  • Options

    Every knob on StringOptions, and what it does.

    options

  • Engines

    V8, Node, GraalJS or native dart-sass, module resolvers, engine pools, timeouts.

    engines

  • Migration

    Coming from jsass 5? Here is the API mapping.

    migration