Home » Vite Build System

Vite Build System

Boilerplate uses Vite to compile JavaScript, SASS/CSS, sourcemaps, and static font assets into stable WordPress theme output paths.

Primary Files

  • vite.config.mjs – main Vite configuration
  • vite.plugin.sass_sourcemap.mjs – custom SASS sourcemap plugin
  • package.json – npm dependencies and build commands
  • assets/js/main.js – main JavaScript entrypoint
  • assets/sass/theme.scss – front-end theme stylesheet entrypoint
  • assets/sass/admin.scss – WordPress admin stylesheet entrypoint
  • assets/sass/editor.scss – block editor stylesheet entrypoint

Build Entries

Vite builds one JavaScript entry and multiple SASS style entries. The style entries are the shared source of truth for both Vite/Rolldown input and the custom SASS sourcemap plugin.

  • theme – assets/js/main.js → dist/js/theme.js
  • theme_style – assets/sass/theme.scss → dist/css/theme.css
  • admin_style – assets/sass/admin.scss → dist/css/admin.css
  • editor_style – assets/sass/editor.scss → dist/css/editor.css

Note: print styles are currently imported through theme.scss, not emitted as a separate dist/css/print.css file.

JavaScript Entrypoint

assets/js/main.js imports Bootstrap 5, Fancybox, lazy loading, color mode support, theme behavior, and WordPress-specific JavaScript behavior.

Output: dist/js/theme.js

SASS Entrypoints

SASS entrypoints compile the front-end theme, admin stylesheet, and block editor stylesheet. theme.scss owns the main front-end stack, including Bootstrap, Fancybox styles, parent theme styles, layout, widgets, comments, media, and print styles.

  • assets/sass/theme.scss
  • assets/sass/admin.scss
  • assets/sass/editor.scss

Font Copying

When install asset copying is enabled, Vite copies Bootstrap Icons and Open Sans font files into dist/font/.

  • dist/font/bootstrap_icons/
  • dist/font/open_sans/

Controlled by: BP_INSTALL

Image Optimization

Assets from assets/img will be copied over to dist/img on build (not watch); and then optimized using both Sharp and svgo.

Environment Variables

  • BP_INSTALL=false – skip font/install asset copying; default behavior copies install assets
  • BP_SOURCEMAP=true – emit sourcemaps; default is disabled
  • BP_BEEP_ON_BUILD_ERROR=true – enable terminal bell feedback on build errors; default is disabled

Development Builds

Development builds disable production minification and may enable sourcemaps. Use development builds when debugging JavaScript or SASS output.

npm run build:dev
npm run compile:dev
npm run watch

Production Builds

Production builds enable CSS minification and Terser JavaScript minification.

npm run build
npm run compile

Sourcemaps

Development sourcemaps are enabled through BP_SOURCEMAP=true. Boilerplate includes vite.plugin.sass_sourcemap.mjs to compile SASS entries with sourcemaps, pass them through PostCSS/Autoprefixer, and emit matching CSS map files when sourcemaps are enabled.

Sourcemaps had to be handled by our own custom plugin, due to Rolldown not supporting the emitting of them; read more here: https://github.com/rolldown/rolldown/issues/8403

Eventually, the goal is to deprecate our own sourcemap plugin, for more formal support. But, for now – we use our own plugin because sourcemaps are considered very important in our dev mode builds for easy reference, and overriding directly from the browser.

Beep Feedback

Build-error beep feedback is opt-in. Enable it explicitly with BP_BEEP_ON_BUILD_ERROR=true, normally during watch mode.

cross-env BP_BEEP_ON_BUILD_ERROR=true vite build --mode development --watch

cross-env Support

npm scripts use cross-env so environment variables work consistently across shells and operating systems.

Current npm Commands

  • npm run build – production build with install assets copied
  • npm run build:dev – development build with install assets and sourcemaps
  • npm run compile – production compile without install asset copying
  • npm run compile:dev – development compile without install asset copying, with sourcemaps
  • npm run watch – development watch build without install asset copying, with sourcemaps and beep-on-error enabled

Size Reporting

Size reporting should report generated output artifact sizes and gzip estimates for committed build checks.

Rule of Thumb

Use build when creating full production assets. Use compile when rebuilding code assets without copying install assets. Use build:dev or compile:dev when debugging sourcemaps. Use watch during active development.

© 2026 Boilerplate