Skip to content

feat: Replace the gulp UI toolchain with Vite#874

Open
lfrancke wants to merge 5 commits into
chore/vendor-uifrom
chore/ui-toolchain
Open

feat: Replace the gulp UI toolchain with Vite#874
lfrancke wants to merge 5 commits into
chore/vendor-uifrom
chore/ui-toolchain

Conversation

@lfrancke

@lfrancke lfrancke commented Jul 10, 2026

Copy link
Copy Markdown
Member

Description

Phase 2a of the docs overhaul, stacked on #873 (GitHub retargets this to main when #873 merges). Five commits, reviewable independently - happy to split into separate PRs if preferred:

  1. chore: Commit the minified images - gulp-imagemin ran on every build; the minified results are committed instead (-673 lines of SVG cruft).
  2. chore: Remove upstream leftovers from the UI - .gitlab-ci.yml and upstream's own docs/ component, never used here.
  3. chore: Add a NOTICE file - minification strips embedded license header comments from the built css/js, so the third-party attributions (Font Awesome CC BY 4.0/OFL/MIT, highlight.js BSD-3, Asciidoctor Tabs MIT, Octicons MIT, the OFL fonts, MPL-2.0 upstream fork) live in ui/NOTICE, which the build ships in the bundle and therefore publishes on the site. The Octicons attribution inside the SVG's <desc> is preserved.
  4. feat: Replace the gulp UI toolchain with Vite - the main course, see below.
  5. fix: Remove invalid css declarations and lint leftovers - background-color: none/min-width: none are invalid and were ignored by browsers; removing them changes nothing.

The toolchain swap

  • Why Vite: it's what stackable-apps and stackable-cockpit use, and the gulp pipeline was frozen (gulp-eslint/gulp-stylelint unmaintained, eslint 6, stylelint 13). Upstream antora-ui-default ships the same frozen toolchain, so there's no upstream modernisation we'd diverge from. Everything starts on the current majors: Vite 8, eslint 10, stylelint 17, archiver 8, Node 24.
  • ui/build.mjs produces the identical bundle layout (js/, js/vendor/, css/, font/, webfonts/, img/, helpers/, layouts/, partials/, NOTICE, LICENSEbuild/ui-bundle.zip). JS entries are built as self-contained classic scripts, one Vite pass each - rollup cannot code-split IIFE output, which is exactly what <script src> consumers need.
  • The two vendor bundle sources are now ESM and reference @asciidoctor/tabs' browser build and css explicitly (Vite doesn't honor the style/browser package fields the way browserify/postcss-import did).
  • CSS custom properties are no longer inlined at build time - every supported browser handles var(), and the planned design-token work needs them preserved. This is the only intentional CSS output change.
  • The standalone gulp preview is gone; UI changes render with real content via make build-truly-local or the deploy preview.
  • stylelint is configured to accept the inherited upstream CSS conventions rather than reformatting everything right before the planned upstream re-sync.
  • package-lock.json had to be regenerated; @antora/ and pagefind are pinned to their previously locked versions* (3.1.7 / 1.3.0) so the rendered site and search assets stay identical - bumping those is Renovate's job, not this PR's.
  • The root .nvmrc raises the Netlify build to Node 24.

Verification

Full site built with the gulp bundle and the Vite bundle, every page compared: 0 differing pages out of 220 (after normalising the trailing whitespace that #873's lint commit removed from an inline script). Bundle file lists are identical except the standalone css/vendor/fontawesome.css copy, which nothing referenced (Font Awesome stays inlined in site.css - its removal is a separate, planned performance PR). npm run lint --workspace ui and make build-ui pass; the UI CI workflow now also runs the lint.

lfrancke added 5 commits July 11, 2026 00:49
gulp-imagemin minified these on every build; the minified versions are
committed so the build does not need an image pipeline.
The .gitlab-ci.yml and the docs/ component are inherited from
antora-ui-default and were never used here.
Minification strips embedded license header comments from the built
css/js, so the attributions (Font Awesome, highlight.js, Asciidoctor
Tabs, Octicons, the OFL fonts, and the MPL-2.0 upstream fork) live in
a NOTICE file. The build ships it in the UI bundle, which publishes it
on the site.
Vite is what stackable-apps and stackable-cockpit build with, and the
gulp pipeline was frozen: gulp-eslint/gulp-stylelint are unmaintained
and pinned eslint 6 / stylelint 13. Upstream antora-ui-default still
ships the same frozen toolchain, so there is no upstream modernisation
to converge with. Everything starts on the current majors: vite 8,
eslint 10, stylelint 17, archiver 8, Node 24.

- build.mjs produces the identical bundle layout: js entries are built
  as self-contained classic scripts (one vite pass each), the css in a
  separate pass, static directories are copied, NOTICE and LICENSE are
  included, everything is zipped to build/ui-bundle.zip. Verified by
  building the full site with both toolchains: every page is
  byte-identical.
- The vendor bundle sources become ESM and reference the browser build
  of @asciidoctor/tabs explicitly (vite does not honor the style and
  browser package fields the way browserify/postcss-import did).
- CSS custom properties are no longer inlined at build time; every
  supported browser handles var(), and the upcoming design-token work
  needs them preserved.
- The standalone gulp preview is gone; render UI changes with real
  content via 'make build-truly-local' or the deploy preview.
- The stylelint config accepts the inherited upstream css conventions
  instead of reformatting everything right before the planned upstream
  re-sync.
- package-lock.json is regenerated; @antora/* and pagefind are pinned
  to their previously locked versions so the rendered site and search
  assets stay identical (bumping those is Renovate's job).
- Node 24 in .nvmrc/engines/CI, matching stackable-apps. The root
  .nvmrc also raises the Netlify build to Node 24.
background-color/min-width do not accept 'none'; browsers ignored the
declarations, so removing them does not change rendering. Also an
unused event parameter and a stale eslint-disable directive.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant