Skip to content

Storefront Asset Build

How the storefront's own scripts and stylesheets, and the admin's, get from src/main/resources to the browser: what the build writes, how a page finds the right file, and how the server caches it, and how the scripts are linted and type checked on the way. This is step 3 of the Front-End Direction: stage A minifies and hashes the files as they are, and stage B bundles ES modules (piloted with the filter sheet).

In short

  • The Maven build writes a minified, content-hashed copy of each storefront script and stylesheet beside the plain file (fragments.js and fragments-7KQ2M4AB.js), and a manifest that maps one to the other.
  • AssetUrls turns a path into the URL a page should use: the hashed copy when there is one, otherwise today's path?version.
  • Hashed copies are served with Cache-Control: public, max-age=31536000, immutable. Storefront pages link to them without a version, so a release only makes browsers download the files that changed.
  • With no manifest (dev builds, by default), every storefront URL and every response is what it was before. An admin URL carries the release version alone (admin-ui.js?<release version>), no longer the build time too.
  • The same scripts are linted (Biome) and, file by file, type checked from their JSDoc (tsc). Both are ratchets: the build fails on a new problem, not on the ones already recorded.
  • The admin's own scripts and stylesheets (themes/admin/) go through the same build, are linked the same way and are linted by the same ratchet (see The admin's own files).
  • New and ported code can be written as ES modules in a theme's js/modules/ folder. The build bundles each module entry into one hashed file (code entries share goes into hashed chunks); a dev build serves the modules as written, as native modules.

Where it stands: the build, the manifest, AssetUrls, #assets and the serving side are in place, and every storefront template (all themes, the shared components, the extension templates and the pattern library) links its first-party scripts and stylesheets through #assets.url. StorefrontAssetUrlsTest stops the old form coming back. The admin, System and admin extension templates link the admin's own files the same way, and AdminAssetUrlsTest holds them to it. Nova's bdgr.css is written as source files, one per page area or component, that the build bundles back into the one stylesheet pages load (stage C, without cascade layers so far). The first ES modules, the filter sheet (themes/nova/js/modules/facet-sheet.js) and the one-page checkout (themes/nova/js/modules/checkout.js), are bundled through the same manifest.

The build

web-mvc/scripts/build-assets.mjs runs in process-resources, over what Maven has just copied into web-mvc/target/classes/resources/settBuilder.

First it bundles: a stylesheet written as source files, name.src.css (today only Nova's bdgr.src.css), is bundled by Lightning CSS into name.css beside it. The entry and the files it imports are then removed from target/classes, so they are neither served nor hashed. See Nova's stylesheet. Then:

  1. Stylesheets. Lightning CSS minifies every theme stylesheet (themes/**/*.css, not *.min.css) in place, as the build did before. No browser targets are set, so it only minifies: modern syntax such as nesting ships as written.
  2. Hashed copies. For every first-party script and stylesheet (everything under themes/, the admin's folder included, and js/, except any vendor/ folder, *.min.* files and the ES modules, which step 3 bundles):
    • a script is minified by esbuild as it is: no bundling and no change of format. An IIFE stays an IIFE, and top-level names stay global, so scripts that share state through window or top-level functions keep working. Nothing is lowered to an older JavaScript version.
    • the copy is named after the first eight base32 characters of the SHA-256 of its content, name-XXXXXXXX.js. Each script copy has a linked source map whose source is the plain file next to it, so a stack trace can be mapped back. A script's hash covers its source map as well as the minified code, so an edit the minifier drops (a comment) still gives a new name, and the map, served under that name, is never stale.
    • a stylesheet's copy is the minified stylesheet. It sits in the same folder, so relative url()s still resolve.
  3. ES modules, bundled: see ES modules below.
  4. The manifest, target/classes/META-INF/badger/asset-manifest.json, outside the served folder:

    {"version": 1, "assets": {
      "themes/nova/js/fragments.js": {
        "file": "themes/nova/js/fragments-7KQ2M4AB.js",
        "integrity": "sha384-…"},
      "themes/nova/js/modules/facet-sheet.js": {
        "file": "themes/nova/js/modules/facet-sheet-F44ISHWO.js",
        "integrity": "sha384-…"}},
     "chunks": {
      "themes/nova/js/modules/chunks/chunk-KNJX4MBD.js": {"integrity": "sha384-…"}}}
    

    Keys and files are relative to /settBuilder/. integrity is the copy's Subresource Integrity value, recorded for later use (a Content Security Policy, preload hints). chunks lists the files the bundler split out of the module entries; no page names one, so they have no key. The manifest only has chunks when two entries share a part: today's build has none (see What the build does), so the example shows what one would look like.

The plain files stay in the jar, so stored shop content that names /settBuilder/... directly, and an admin script that fetches a file from its own folder at run time (the media browser's Mustache templates), keep working.

The build fails if a source file is named like a hashed copy (promo-ABCDEFGH.js), because the server would cache it for a year. It takes well under a second.

Skipping it in dev

devEnv.sh builds with -DskipAssetBuild unless MINIFY_ASSETS=true is set in ~/devEnv.conf (MINIFY_CSS=true, the setting's old name, and -DskipCssMinify still work). Skipped, the build minifies and hashes nothing and removes the copies and manifest an earlier build left in the same target/, so pages fall back to the plain files rather than to copies of old sources. It still bundles (well under a second), because the bundled bdgr.css is the file pages load; skipped, the bundle is left unminified. Set MINIFY_ASSETS=true to try a change as production will serve it.

The dev loop: hot assets

With the asset build skipped (the default in dev), an edit to a storefront or admin script or stylesheet shows on a browser refresh, with no build and no restart. The mount below is the whole settBuilder folder, so it covers themes/admin/ too, and the admin's pages are served by the same web containers and the same /settBuilder/** handler.

devEnv.sh mounts the checkout's web-mvc/src/main/resources/resources/settBuilder folder into the web containers read-only at /dev-assets. In the dev profile the server serves /settBuilder/** from that folder first and from the jar second, and sends Cache-Control: no-cache so the browser revalidates on every load. Nothing else is mounted: no node_modules, no build output, no Java, and the containers stay read-only, so the "builds run in containers" isolation is unchanged. The mount path comes from the checkout that started the stack, so a git worktree serves its own files.

Setting in ~/devEnv.conf Default Effect
HOT_ASSETS true false mounts an empty folder and serves the jar's copy, as before

It turns itself off when it would give the wrong file, and then the jar serves everything:

  • outside the dev profile (DevAssetLocations checks it; production and tests never see the mount);
  • when badger.dev.hot-assets-dir (env BADGER_DEV_HOT_ASSETS_DIR, set by devEnv.sh) is blank or the folder is missing;
  • when an asset manifest exists, which is the case with MINIFY_ASSETS=true: pages then link to hashed copies that live only in the jar, and those are served exactly as in production.

Templates and Java still need a rebuild (b in devEnv.sh): templates are loaded from the jar and cached by Thymeleaf. After changing HOT_ASSETS, restart the stack so the web containers are recreated with or without the mount.

The first time you use it, force one full reload (or clear the browser's cache for the site). Files the browser fetched before were sent with the year-long header, and a dev build's URLs carry the same ?version from one build to the next, so a normal refresh keeps using those copies without asking the server. After that one reload, every file comes back with no-cache and normal refreshes pick up edits.

Tests

web-mvc/src/test/js/build-assets.test.js (run by npm test, and by Maven in the test phase) builds a fixture tree and checks the manifest, that hashes depend only on content, and that a rebuild without clean leaves no stale copies, and that the admin's files get copies too. It also runs every real storefront and admin script twice in a stub page, as written and minified, and fails if the two define different globals. It checks bundling on a fixture too: import order kept, only the bundle shipped, the same with -DskipAssetBuild, and an unlisted source file or an import from outside the entry's folder failing the build. web-mvc/src/test/js/build-modules.test.mjs does the same for the module bundles (see ES modules below). nova-css-sources.test.js checks Nova's real source files (see below).

Nova's stylesheet: source files and the bundle

Nova's stylesheet is written as source files in web-mvc/src/main/resources/resources/settBuilder/themes/nova/css/src/, one per page area or component, following the stylesheet's section banners: tokens.css (the :root design tokens), product-card.css, account.css, json-component-tokens.css and so on, then the shared components, one ui-<component>.css per "ui: " sub-section, after ui-components.css, which holds the banner that opens that section. css/bdgr.src.css lists them, in order, with plain @import "src/<name>.css"; lines and holds nothing else but comments and @charset.

The build bundles them into bdgr.css, which is what every Nova-family page loads, as before. bdgr.css is only ever generated: it is not in the source tree, and the jar holds the bundle but not the source files. So:

  • Edit the file in css/src/. A new file must be added to bdgr.src.css where its rules belong; the build fails on a file in src/ that bdgr.src.css doesn't import. Order matters as it did in one file: when two rules are equally specific, the later file wins.
  • Write url()s relative to css/, the folder bdgr.css is served from, not to css/src/: the bundler keeps them as written. (Today's only url()s are inline data: images.)
  • A source file imports nothing. Only bdgr.src.css imports, and only from src/; the build fails on an import from outside the entry's folder.
  • Running the app without the Maven build (from an IDE, say) serves no bdgr.css. Build web-mvc once (devEnv.sh does), and again after editing a source file.

The split changed no rule. The bundle is the same stylesheet as the single file it replaced: minified with the same Lightning CSS options, the bundled stylesheet and the old file are byte-identical, so bdgr.css's hashed copy kept its name. nova-css-sources.test.js keeps the structure honest: bdgr.src.css holds only plain imports, every file in src/ is imported exactly once, no source file imports anything, each starts with the copyright line, every ui- file opens with its sub-section banner, relative url()s resolve from css/, and Lightning CSS's bundle is byte-for-byte the minified concatenation of the files in import order. It also holds the cascade layers to their rules (below).

The guard tests and tools that read Nova's stylesheet read the source files in import order: StorefrontSources.novaCss() (behind UiComponentContractTest, ThemeTokenValuesTest and JsonComponentTokenCssTest) and nova_css() in dev-scripts/design-system/build.py. StorefrontStyleRatchetTest counts the source files' raw colours as the one nova/css/bdgr.css they are bundled into, so its baseline key is unchanged. The pattern library and ui-snapshots.sh look at the running app, so they see the bundle.

Cascade layers

src/layers.css, the first file bdgr.src.css imports, declares the layer order and holds nothing else:

@layer bdgr.reset, bdgr.tokens, bdgr.base, bdgr.components, bdgr.theme;
  • One outer layer, bdgr. A shop's own CSS may use layers too: Tailwind's output, for one, declares theme, base, components, utilities. Plain names would merge with a shop's layers of the same name and could reorder them. Inside bdgr, a shop's layers keep their order, unless the shop names one of its own layers bdgr.
  • No layer for shop overrides. A shop's CSS (the Design Brief's theme.css and the hand-written global.css, linked by GlobalCSSThemeExtension after every theme stylesheet) is unlayered, and an unlayered rule beats every layered one. That is what an override has to do, and stored CSS can't be wrapped in a layer without changing which rules it beats.
  • bdgr.theme is reserved for the layered themes' stylesheets. They stay unlayered until the Nova rules they override are layered: a theme rule in a layer would lose to every unlayered Nova rule.

What can go in a layer

A layered rule loses to every unlayered rule, whatever the specificity. For !important the order is reversed: a layered !important beats every unlayered one. Every stylesheet around bdgr.css is unlayered: Bootstrap's stylesheet, which every theme head loads before it; each layered theme's stylesheet; extension stylesheets and the <style> blocks in templates; and the shop's own CSS, which isn't in the repository, so no screenshot can show a change against it. So a rule moves into a layer only when that can be shown to change no outcome:

  • No specificity. Every selector is written with :where() (or is *). Such a rule already lost to every later rule that sets the same property on the same element, so a layer doesn't change that.
  • No !important. In a layer it would start beating !important rules in the themes and in shops' CSS.
  • No @keyframes, @font-face or @property. Layers also decide which of two such rules with the same name applies.
  • No earlier rule with no specificity sets the same property, unless it is in the same layer or an earlier one. Without layers the later of two such rules wins the tie. Layered, the rule loses to an earlier unlayered one (in Bootstrap's stylesheet, Font Awesome's or earlier in bdgr.css), and to one in a later layer wherever it stands. For the same reason, a later rule with no specificity may not sit in an earlier layer. Bootstrap's only rule with no specificity is *, for box-sizing, and neither it nor Font Awesome sets any of Nova's custom properties.

nova-css-sources.test.js enforces all four. For the last it reads Bootstrap 5.3.2 and Font Awesome 5.15.4 from node_modules (the copies the build vendors and every theme head loads before bdgr.css) and Nova's source files in order, and checks that each layered rule wins and loses against the same rules with no specificity as it did unlayered. It compares property names only, not selectors or media queries, and treats a longhand and its shorthand as the same property, so it errs on the side of refusing. It also checks that layers.css comes first and declares exactly this order, that the bundle still names the layers in that order, and that every layer is written as two wrapper lines with the rules between them unindented:

@layer bdgr.tokens {
:where([class~="nova-jc-bg-success"]) {
  --jsonc-text: var(--json-bg-success-text, white);
}
} /* @layer bdgr.tokens */

Taking those two lines out leaves the file exactly as it was before the rules were layered, and the test checks the bundle against that: its unlayered rules are the source files' rules outside the layers, in order, and its layered rules are the ones inside, in order. Lightning CSS moves layer blocks to the top of the bundle and splits the order statement around them (@layer bdgr.reset;@layer bdgr.tokens{…}@layer bdgr.base,bdgr.components,bdgr.theme;). That changes nothing: the first mention of each layer sets its place in the order, and a layered rule's position among unlayered rules doesn't affect which one wins.

Layered so far: the four rules in json-component-tokens.css that set --jsonc-text, --jsonc-button-bg and --jsonc-button-color for each JSON component background (bdgr.tokens). The minified bundle is the old one with those four rules moved, unchanged, into the layer block at its top. In the screenshot comparison of every pattern in every theme (./dev-scripts/ui-snapshots.sh), every page that uses these rules (the JSON component patterns) is pixel-identical. About 40 of the 4,110 screenshots differ by a few antialiased pixels, as many as differ between two runs over the same pages, in the same patterns (email capture, facet rail, mini basket, page shells), and ui-snapshots.sh styles finds no computed-style difference on them. A browser without cascade layers (before Chrome 99, Firefox 97 and Safari 15.4) ignores the layer block, so these four rules don't apply there; the Front-End Direction lists cascade layers as safe to rely on.

Why the rest stays unlayered

  • Design tokens (tokens.css, :root). A shop's CSS that sets one of Nova's tokens from inside a layer loses to Nova's :root today and would win once the tokens were layered. Tailwind's output, pasted into a shop's CSS, would do that: it sets its variables in @layer theme { :root { … } }, and names such as --color-gray-500, --radius-md, --shadow-sm and --font-weight-bold are Nova's names too. A shop rule on the root element with less specificity than :root (html { --color-primary: … }) would start winning in the same way. Within the repository, layering tokens.css changes nothing: tried, the screenshots differ only as much as two runs do, with no computed-style difference. The reason to leave it is shops' CSS, which no screenshot shows.
  • Base styles (global.css). Bootstrap's reboot, loaded unlayered before bdgr.css, styles the same elements with the same specificity: body (font, size, line height, colour, background), h1 to h6 (margins, weight, line height, colour, sizes) and a (colour, underline). Nova wins today because it comes later. Layered, it would lose all of them: tried, 1,982 of the 4,110 screenshots changed in every theme. On Nova's pages the body text took Bootstrap's colour (#212529) and system font, and headings its line height and margins.
  • Components, utilities and theme overrides. The same applies: any Bootstrap rule of equal or lower specificity, and any later theme, extension or shop rule of lower specificity, would start winning. !important rules would start beating every theme's and shop's !important. None of the stylesheet's !important declarations was removed: no layer makes one redundant while the stylesheets around it are unlayered.

The way forward is the Front-End Direction's order: Bootstrap's stylesheet leaves the storefront first, and moving the tokens needs a decision on shops' CSS that sets them from a layer, since no screenshot can show that case.

ES modules

Stage B: new and ported scripts are written as ES modules, with import and export, and the build bundles them. The filter sheet was the first; the one-page checkout followed (see The checkout below).

Where they live

A theme's modules are in its js/modules/ folder (themes/nova/js/modules/):

  • Entries are the scripts directly in the folder (modules/facet-sheet.js, modules/bridge.js). A page loads an entry, never anything else in the folder.
  • Parts are in subfolders (modules/facet-sheet/count.js, params.js, slider.js, sheet.js). Entries and parts import parts by a relative path to the .js file (import { init } from './facet-sheet/sheet.js'). The build fails on anything else: a bare name ('lodash', which a browser can't load without an import map), a path without .js, or a file outside the module folder (a classic script). So a module only ever imports modules.
  • modules/package.json ({"type": "module"}) tells Node (for node --test) and the type checker that the folder's .js files are modules. It isn't served: the pom leaves it out of the jar.
  • modules/chunks/ is where the build writes the chunks; don't put a module there.

There is no import map: bundling makes one unnecessary, and an import map would be one more inline script for a future Content Security Policy to allow.

Loading one

<script type="module" data-cookieconsent="ignore"
        th:src="${#assets.url(siteContext.templateTheme.jsPath + '/modules/facet-sheet.js')}"></script>

A module script runs like a defer script: once the page has been parsed, in document order with the deferred classic scripts, and only once however many times the page names it. A theme without its own copy gets Nova's, as for any asset. Browsers too old for modules skip the script, so a module must, like every storefront script, only improve a page that works without it (the filter rail's values are plain links). StorefrontAssetUrlsTest fails on a module loaded without type="module", or on a page loading a part instead of an entry.

What the build does

Each module folder's entries are bundled with esbuild (bundle, format: 'esm', splitting, minified, nothing lowered):

  • an entry becomes name-HASH.js beside its source, with the parts only it uses inside it;
  • code two or more entries import goes into modules/chunks/chunk-HASH.js, which those entries import by relative path (./chunks/chunk-KNJX4MBD.js);
  • every output has a linked source map whose sources are the plain modules, served beside it.

What production serves today: Nova's entries share no part, so there are no chunks. A listing page loads facet-sheet-HASH.js, one self-contained file of about 10 KB with the whole sheet inside it. The checkout page loads checkout-HASH.js, about 68 KB minified, with all of the checkout's parts inside it. bridge.js is bundled too (a few bytes), but no page loads it.

Keep it that way unless a page really loads two entries that share a part. The browser only finds a chunk once the entry that imports it has arrived, so a split costs one extra round trip before the module runs. During a rolling deploy the entry and its chunk can also come from pods of different releases, and the chunk is then a 404 (see Serving). build-modules.test.mjs builds Nova's own modules and fails if a chunk appears.

esbuild's hash covers an output's code, its source map and the names of the chunks it imports, so editing a shared part renames its chunk and every entry that imports it, and a change only to a comment still renames the file whose map changed. Entries and chunks are in the manifest (above).

In a dev build

With -DskipAssetBuild nothing is bundled. #assets.url gives the entry's plain path with the release version, and the browser loads the parts it imports as native modules, by their relative URLs. Those URLs carry no version, so the server sends plain-named modules Cache-Control: no-cache (with Last-Modified, so an unchanged module costs a 304): a rebuild is picked up on the next load, with no stale part kept for a year.

Talking to the classic scripts

Modules read the classic scripts' globals (window.NovaUi.fragments) through the types in web-mvc/types/globals.d.ts. In the other direction there is one door: modules/bridge.js is the only module that writes to window.NovaUi (a Node test fails if another one does), publishing what classic scripts may use. Today it publishes nothing, because no classic script needs a module's code: it only makes sure window.NovaUi exists. Its header shows how to publish a part. A part the bridge imports that another entry imports too moves into a shared chunk (above), so import one only when a page needs it. The rule: anything the bridge publishes is used from deferred code only (a defer script, an event handler, a DOMContentLoaded listener). The bridge runs once the page is parsed, so an inline script that runs while the page is parsed would find it missing. A page whose classic scripts use a bridge export loads modules/bridge.js before them; no storefront page needs one yet.

The checkout

The one-page checkout (nova/extensions/unifiedCheckout/main.html) loads modules/checkout.js, which was a single classic script, extensions/unifiedCheckout/checkout.js. The split moved its code as it was into parts in modules/checkout/, one per area of the page: session.js (the /api/checkout/session calls and the debounced patch queue), view.js (drawing each session), address.js and inputs.js (the address fields and what typing in them does), delivery.js, split.js and order-mode.js (delivery, collection, split handover and the restaurant header's choice), payment.js and wallet.js (Stripe, Pay and express wallets), consent.js, direct.js, summary.js (the basket summary and promo codes), readiness.js (what still blocks Pay), and state.js, money.js, util.js and init.js. The entry's header lists them.

  • Loading. main.html names the entry itself, with type="module"; the extension's script list (requiresJS, which the footer emits as classic scripts) carries only handover.js.
  • Timing. The module runs once the page is parsed, like a deferred script: after every ordinary classic script on the page (the footer's script list included, wherever it is) and after deferred scripts that come before it, but not necessarily after an async one such as Stripe.js. It reads what the classic scripts leave on window (BdgrHandover from handover.js, BdgrSlotPicker from js/slot-picker.js) and waits for Stripe.js through the head's addStripeInitFunction, as the classic script did. These globals are declared in web-mvc/types/globals.d.ts.
  • Nothing is published. No other script calls into the checkout, so it puts nothing on window and nothing goes through bridge.js. The basket summary's promo box talks to it with bdgr:promo events, as before.
  • handover.js stays a classic script, because the basket page uses it too (basket-handover.js), and its Node tests load it with require.

Checks

  • Types: every module carries // @ts-check and has no type errors, whatever type-baseline.json says; the type ratchet fails otherwise (see below).
  • Lint: modules are linted like every other script.
  • Tests: node --test runs *.test.mjs files as ES modules, so a module's pure parts are imported and tested as they are (facet-sheet.test.mjs, and checkout.test.mjs, which runs the checkout's parts on a stub page with a stub fetch). build-modules.test.mjs builds a fixture with two entries and a shared part and checks the bundling, the split chunk, the source maps, that the bundles and the plain sources give the same results when run as modules, that an entry's name moves with the chunks it imports and only then, and that the import rules fail the build. It also builds Nova's own modules and checks that the facet sheet and the checkout are one file each, with no chunk, and that editing one of the checkout's parts renames the checkout's file and not the facet sheet's.

Finding the URL: AssetUrls

AssetUrls (commerce-core) loads the manifest once at start-up. For a path under /settBuilder/:

  1. If the manifest has the path, the URL is its hashed copy.
  2. If the path is a Nova-family theme's (themes/ridge/...) and the manifest has Nova's copy instead, the URL is Nova's hashed copy. This is the rule the server uses to serve a theme asset the theme hasn't got (ThemeAssetPaths, shared with NovaThemeAssetResolver). A theme's own file is always in the manifest when it exists, so it still wins.
  3. Otherwise the URL is path?version, with the release version, as before.

Anything else (//cdn..., /vendor/..., which already has the version in its path, and /dynamic/..., the shop's own stylesheets) is returned unchanged. A missing entry never fails: it falls back to ?version.

In templates: #assets

AssetUrlDialect registers #assets on the application's Thymeleaf engine, which renders the storefront and the admin alike (it's a Spring bean, as #shopMoney is), so templates need no bean access. Give it the path as the page would have named it, theme path included, and nothing else: no ?version, no @{...}:

<script th:src="${#assets.url(siteContext.templateTheme.jsPath + '/fragments.js')}"
        data-cookieconsent="ignore" defer></script>

The version it falls back to is read through the template's own messages (#{admin.badger.system.version}), so with no manifest the URL is the plain path with the build identity (the short commit SHA, see Versioning) after it, in every engine, render tests' bare engines included. Render tests that build their own engine add new AssetUrlDialect() next to ShopMoneyDialect; it reads the manifest on the test classpath, if the build wrote one. A test that asserts on the exact URL gives the dialect a manifest of its own (new AssetUrlDialect(new AssetUrls(AssetManifest.of(...)))), since whether the classpath has one depends on whether the asset build ran.

#assets.url leaves a name that already is one of the hashed copies alone, so applying it to the extension lists (below) is safe.

What the templates pass through it:

  • a theme's own files, siteContext.templateTheme.jsPath + '/x.js' and cssPath + '/bdgr.css', and the theme heads' literal paths ('/settBuilder/themes/nova/js/fragments.js');
  • each entry of the extension and theme stylesheet lists the heads and footers loop over;
  • the stylesheet a theme hands to the shared sign-in head (ui/auth-head);
  • a script a template loads at run time from an inline script (the animation scene's runtime and the GSAP files it needs): the template resolves the URL on the server, [[${#assets.url('...')}]], and the script uses it, so a script never builds a /settBuilder/ URL itself. The one exception is the error beacon, which reports a script's manifest key and builds nothing it loads.
  • a library copied under /settBuilder/ (themes/nova/js/vendor/gsap.min.js). The build leaves vendor/ folders and *.min.* files out of the manifest and these paths carry no version, so #assets.url gives them ?version; a plain URL would be cached for a year and never refetched.

Left alone, because they aren't ours to hash: CDN assets (#{system.css.and.js.cdn.url(...)}, with the library's version in its path), the top-level /vendor/... copies (version in the path too), absolute URLs and the shop's own stylesheets (/dynamic/...). Images and other files that are not scripts or stylesheets (the wallet badges) are not covered by the asset build, so they keep their plain URLs.

#assets.integrity(path) gives the hashed copy's SRI value, or null. #assets.linked(path) says whether the page has already asked #assets.url for that file's URL (see Extension scripts and stylesheets).

Emails don't get #assets: they load no first-party scripts.

The admin's own files

The admin's scripts and stylesheets live in themes/admin/js and themes/admin/css. The build treats them as it treats a theme's: each gets a minified, content-hashed copy (a script with its source map) in the same manifest, and the server sends the copy immutable, with the same stale-name answer during a rolling deploy. The admin's folder never falls back to Nova's files.

Admin, System and admin extension templates link them through #assets.url, from the admin (or System) site's theme folder or by literal path:

<link th:href="${#assets.url(adminContext.templateTheme.cssPath + '/admin-ui.css')}" rel="stylesheet" />
<script th:src="${#assets.url(adminContext.templateTheme.jsPath + '/admin-ui.js')}"></script>
<script th:src="${#assets.url('/settBuilder/themes/admin/js/admin-csrf.js')}"></script>

With no manifest (a dev build) the URL is the plain file with the release version, as on the storefront. The admin used to add its own ?v= with the release version and the build's timestamp (admin.badger.asset.version); that message is gone, since the hashed name now changes whenever a file does, and only then.

AdminAssetUrlsTest (web-admin) reads every admin, System and admin extension template (web-admin's and web-mvc's) and fails on a first-party script or stylesheet linked without #assets.url, a path built on the admin's jsPath or cssPath outside it, or a version added by hand. Left as they are: the third-party libraries the admin loads through #{system.css.and.js.cdn.url(...)}, absolute URLs, the top-level /vendor/... copies and the extension lists' loops (th:src="${js}"), whose entries are already hashed names. AdminAssetUrlRenderTest renders the admin and System heads and footers and the admin's error page with a manifest (hashed names, no version) and without (plain file and release version), and AdminAssetWiringTest checks that Spring Boot's engine gets the dialect.

The admin's scripts are linted (below), with the admin's library globals configured and the problems they already had recorded in the baseline. They are not type checked: tsconfig.json leaves the admin's folder out, the type ratchet ignores a // @ts-check there, and the admin's folder has no ES modules.

Extension scripts and stylesheets

ExtensionService builds the externalListOfJSRequired and externalListOfCSSRequired lists from each extension's requiresJS and requiresCSS. Each first-party path in them becomes its hashed copy (AssetUrls.path), without a version. The storefront templates pass each entry through #assets.url, which keeps a hashed name as it is and gives any other first-party path (no manifest, or a file the build left out) the release version. A CDN or // entry comes out unchanged, with no version added. The admin's templates add no version to these lists, so where an admin page lists a storefront asset it gets the hashed name as it is.

A file the theme's head already loads is left out of these lists' tags, so a page never loads it twice. Every theme head loads fragments.js, which several extensions also require, and Bistro's head loads the restaurant menu's stylesheet and ordering-status.js for the header on every page. Each loop skips an entry with th:unless="${#assets.linked(js)}": #assets serves the whole page and remembers the URLs it has given out, so linked is true for a file the head has already linked, and the first tag, where the theme put it, is the one kept. A new loop over these lists needs the same th:unless, with the same argument as its th:src or th:href.

Serving: HashedAssetResolver

/settBuilder/** is served by Spring's resource handler with this chain:

Request Response
A hashed copy this release's manifest lists, or a chunk it lists under chunks The copy, Cache-Control: public, max-age=31536000, immutable
A name shaped like a hashed copy that this release hasn't got The plain file, Cache-Control: public, max-age=60, no Last-Modified
A chunk name this release hasn't got 404, with no cache headers
An ES module under its plain name (.../js/modules/...) The module (or Nova's), Cache-Control: no-cache, with Last-Modified
Any other name As before: the file (or Nova's), max-age=31536000

The second row is a rolling deploy: a page rendered by a new pod asks an old pod for a file the old release doesn't have. Rather than a 404, the old pod sends its plain file, briefly cached and with no Last-Modified, so a revalidation can't extend it. Under the old ?version scheme the old pod answered the new version's URL with old content, cached for a year.

A module entry falls back the same way: its plain source is a module too, and the parts it imports by relative path are beside it in that release. A chunk has no plain file to stand in for it, so a chunk name a pod hasn't got is a 404. That only happens when an entry from one release and its chunk are fetched from pods of different releases during a rollout. No pod ever sends one release's code under another release's chunk name. The 404 carries no Cache-Control, so a browser asks again on the next load, but a shared cache in front of the storefront may keep a 404 that has no cache headers for a few minutes (some CDNs do by default), and pages fetched through it lose the module's behaviour until it expires. The page still works without the module (the filter rail's values are plain links), and the edge's settings for 404s decide how long that lasts. Today's build has no chunks (see What the build does), so this case can't arise yet.

Source maps (*.map) are served as application/json (SourceMapMimeConfiguration adds the mapping to the web server, whose defaults don't know the extension).

/settBuilder/ is outside tenant resolution, so all of this is the same for every shop.

Lint and type checks

Lint looks at the scripts the build hashes: everything under settBuilder/js and settBuilder/themes, the admin's folder included, except any vendor/ folder and *.min.js. The type check looks at the same scripts less the admin's. Both run in Maven's test phase, after the Node unit tests, so CI's unit-tests job runs them. Like the asset build, they are skipped with -DskipAssetBuild (and with -DskipTests), so the dev build is unchanged.

The tools are dev dependencies pinned exactly in web-mvc/package.json: Biome 2.6.7 and TypeScript 7.0.2 (the native tsc). Neither has dependencies of its own beyond its platform binary, and neither needs an install script.

Lint: Biome

web-mvc/biome.json turns on a few correctness rules and nothing else: undeclared variables, unused variables, unreachable code, debugger and duplicate object keys. The formatter is off, so no file is reformatted. Biome reads each script as a module, so a name one script shares with another through the page (a top-level function a template calls, or a variable a template's inline script sets) shows up as unused in one and undeclared in the other. The libraries the storefront loads ($, Stripe, Splide, PhotoSwipe and a few more) are listed under javascript.globals; add one there only for a real global a library or the theme head provides. The admin's scripts get the same list plus three libraries the admin shell loads (bootstrap, Mustache, Dropzone), in the overrides entry for themes/admin/. An override's globals replace the top-level list rather than adding to it, so the entry repeats it.

scripts/lint-ratchet.mjs (npm run lint) runs Biome and counts the problems per script and rule against web-mvc/lint-baseline.json:

  • more than the baseline records: the build fails, naming the script, the rule and the counts;
  • fewer: it passes and asks you to lower the baseline, so the fixed problems can't come back;
  • a script Biome can't parse: the build fails, whatever the baseline says;
  • Biome checking fewer files than the build hashes (the files.includes in biome.json no longer match them): the build fails, rather than reading the missing files as problems fixed.

To see the problems in one script, run npx biome lint <path> in web-mvc. Lower the baseline with npm run lint -- --write-baseline. Raising it is a reviewed decision, as it is for the inline-style baseline of StorefrontStyleRatchetTest.

Types: tsc over JSDoc

Scripts stay plain JavaScript; there is no TypeScript source and nothing is compiled. web-mvc/tsconfig.json sets checkJs off, strict on, the browser's types and nothing from Node, so tsc checks only the scripts that opt in with a // @ts-check line at the top (above or below the copyright line, before the first statement). In those, types come from JSDoc:

/** @param {string} url @param {RequestOptions} [opts] @returns {Promise<FragmentResult>} */
function request(url, opts) {

Globals the scripts share are declared in web-mvc/types/globals.d.ts: window.NovaUi (its fragments and addToBasket parts are typed from the scripts themselves) and addStripeInitFunction. When a checked script reads another global, declare it there.

scripts/type-ratchet.mjs (npm run typecheck) runs tsc and checks web-mvc/type-baseline.json, which lists every checked script with the errors it may have:

  • a script with // @ts-check that the baseline doesn't list fails: add it with its error count (npm run typecheck -- --write-baseline). A script can be opted in before it is clean;
  • a listed script that loses its // @ts-check fails, so the list only grows;
  • more errors than the baseline allows fails; fewer passes, with a note to lower it;
  • a script with // @ts-check that tsc never looked at (left out by include or exclude in tsconfig.json) fails, since its zero errors would mean nothing;
  • an error anywhere else (globals.d.ts, tsconfig.json) fails;
  • an ES module (js/modules/) without // @ts-check, or with any type error, fails, whatever the baseline says: modules are new code, so they start checked and clean.

The first checked scripts are the shared helpers, nova/js/fragments.js and nova/js/add-to-basket.js, the error beacon, shared/js/client-errors.js, and every ES module, all with no errors. Opt in the scripts you change, starting with the small shared ones. Notes for writing checked scripts:

  • A type the checker can't follow into a callback (a variable set in a forEach callback, a parameter normalised with opts = opts || {} and read in a nested function declaration, which is hoisted above that line) needs a cast, /** @type {T} */ (value), or a function expression instead of a declaration. The two shared helpers show both.
  • TypeScript 7 doesn't support the JSDoc tags @enum and @constructor, or a postfix !.

Checking it

  • npm test, npm run lint and npm run typecheck in web-mvc (in a container, after npm ci: see Build and Runtime Footprint).
  • After a build without -DskipAssetBuild, the web-mvc jar holds the hashed copies, their .map files and META-INF/badger/asset-manifest.json.
  • AdminAssetUrlsTest, AdminAssetUrlRenderTest and AdminAssetWiringTest (web-admin) cover the admin's templates (see The admin's own files).
  • AssetUrlsTest, AssetUrlDialectTest, ExtensionServiceAssetPathsTest, AssetManifestTest and HashedAssetResolverTest (which covers the admin's copies too) cover the URL rules, the manifest's chunks and the headers. PatternRenderGoldenTest masks hashed names (and the version), so golden render hashes are the same with or without a manifest.
  • StorefrontAssetUrlsTest reads every storefront template and fails if one loads a first-party script or stylesheet without #assets.url (in th:src or th:href, a plain src or href with no #assets.url beside it, a URL set through th:attr, or an inline script naming one), or still adds the version itself. Admin, System and admin editor templates are left out (AdminAssetUrlsTest checks those). Its ALLOWED list can name a template and the paths it may load another way, each with a reason; it is empty today. A new theme or extension template needs nothing special: write th:src="${#assets.url(siteContext.templateTheme.jsPath + '/x.js')}" and the test is satisfied.

What a release invalidates

A page's script and stylesheet URLs now change only when the file's content does. Releasing with no change to fragments.js leaves its URL, and so every browser's and cache's copy of it, as it was; editing one script makes that script's name change, in every theme that loads it, and nothing else. Before this, every release added a new ?version to every URL and everything was fetched again.

Some URLs still change on every release: those of the first-party files the build leaves out of the manifest (vendor/ folders and *.min.* files), and every URL in a dev build, which has no manifest. Those get ?version, so they are fetched afresh per release, as before.

The error beacon

The browser error beacon (themes/shared/js/client-errors.js) is one of these assets: the theme heads load it through #assets.url, so it gets a hashed copy and a source map like any other script. It reports a script by its manifest key (the path under /settBuilder/ without the hash), and the release, so a reported line and column can be mapped back through that release's source map.

What's next

  • More scripts as ES modules, starting with the checkout split, bundled by esbuild through the same manifest.
  • More of Nova's rules in cascade layers once Bootstrap's stylesheet has left the storefront (see Cascade layers), and loading the page-specific parts of the stylesheet only on the pages that use them.
  • Type checking for the admin's scripts, opted in script by script as on the storefront.