Build Pipeline

Build Pipeline

The UI bundle is built with Gulp 4, using PostCSS for CSS processing, Browserify for JS bundling, and Handlebars for template compilation. Output is build/ui-bundle.zip (~320 KB).

Build Flow

bundle (series)
├── bundle:build (series)
│   ├── clean           Remove build/ and public/
│   ├── lint (parallel)
│   │   ├── lint:css    stylelint (standard config)
│   │   └── lint:js     eslint (JavaScript Standard Style)
│   └── build           Process and stage all assets
└── bundle:pack         Create ui-bundle.zip from staged assets

Gulp Task Graph

Task Description Composition

bundle

Full build: clean, lint, build, pack

series(bundle:build, bundle:pack)

bundle:build

Clean + lint + build stages

series(clean, lint, build)

bundle:pack

Create zip from staged assets

single task

lint

Lint CSS and JS in parallel

parallel(lint:css, lint:js)

lint:css

stylelint with standard config

single task

lint:js

eslint with JavaScript Standard Style

single task

build

Process CSS/JS/HBS/images, stage to public/_/

single task

clean

Remove build/ and public/ directories

single task

format

Prettify JS source files

single task

preview

Build + serve with livereload on :5252

series(preview:build, preview:serve)

preview:build

Stage assets + generate preview pages

parallel(build, preview:build-pages)

preview:serve

Dev server at 0.0.0.0:5252 with file watcher

single task

Entry Points

Three equivalent ways to invoke the build:

Method Command

Gulp (direct)

npx gulp bundle

npm script

npm run build (runs gulp bundle && cp -r static/* build/)

Makefile

make or make build (adds colored output + dependency checks)

PostCSS Pipeline

CSS processing chain (configured in gulp.d/tasks/build.js):

  1. postcss-import — resolve @import statements in site.css

  2. postcss-custom-properties — compile CSS custom properties for older browsers

  3. postcss-calc — reduce calc() expressions

  4. postcss-url — rebase asset URLs

  5. autoprefixer — add vendor prefixes (last 2 versions)

  6. cssnano — minify (with rule merging disabled to preserve theme selectors)

cssnano’s mergeRules must remain disabled. Enabling it collapses [data-theme] selectors and breaks theme switching.

Browserify Bundling

JavaScript files matching +([^.])?(.bundle).js are bundled via Browserify with browser-pack-flat for flatter output. The numbered files (01-nav.js through 07-breadcrumbs.js) are concatenated into site.js. Vendor files (domus-ui.js, highlight.bundle.js) are loaded separately.

Makefile Interface

Target Description

make / make build

Build UI bundle (default target)

make preview

Preview with livereload on :5252

make lint

Lint CSS and JS

make install

npm install

make clean

Remove build/ directory

make check-deps

Verify Node.js, npx, and node_modules exist

make help

Show all targets with descriptions

npm Scripts

Script Command

build

gulp bundle && cp -r static/* build/

preview

gulp preview

lint

gulp lint

Key Dependencies

Package Version Category

gulp

~4.0

Build orchestration

gulp-postcss

~8.0

CSS processing

postcss-import

~12.0

CSS import resolution

postcss-custom-properties

~9.1

CSS variable compilation

autoprefixer

~9.7

Vendor prefix injection

cssnano

~4.1

CSS minification

browserify

~16.5

JS module bundling

browser-pack-flat

~3.4

Flattened JS output

gulp-uglify

~3.0

JS minification

handlebars

~4.7

Template compilation

highlight.js

9.18.3

Syntax highlighting

eslint

~6.8

JS linting (Standard Style)

stylelint

~13.3

CSS linting (Standard config)

gulp-imagemin

~6.2

Image optimization

@fontsource/roboto

~4.5

Roboto font files

@fontsource/roboto-mono

~4.5

Roboto Mono font files

@vscode/gulp-vinyl-zip

~2.5

Zip packaging

Source Files

File Lines

gulpfile.js

126

package.json

63

Makefile

91

gulp.d/tasks/

Build task implementations

gulp.d/lib/

Helper functions (create-task, export-tasks)