Module

utils.js_bundler

Pure Python JavaScript Bundler for Bengal SSG.

Bundles multiple JavaScript files into a single file without any Node.js dependencies. Uses concatenation with IIFE preservation to avoid variable conflicts.

Features:

  • Preserves IIFEs (Immediately Invoked Function Expressions)
  • Adds source file comments for debugging
  • Configurable load order via manifest or naming convention
  • Minification via jsmin (optional)

Performance Impact:

  • Reduces HTTP requests from ~20 to 1 on mobile (saves ~1-2s on slow 4G)
  • Single bundled file can be cached efficiently
View source
5 Functions

Functions

bundle_js_files
Bundle multiple JavaScript files into a single string. Files are concatenated in the order provide…
1 str 
def bundle_js_files(files: list[Path]) -> str

Bundle multiple JavaScript files into a single string.

Files are concatenated in the order provided. Each file's content is separated by a newline. Source comments can be added for debugging.

Parameters 1

Name Type Default Description
files list[Path] —

List of JS file paths in load order (dependencies first)

Returns

str —

Bundled JavaScript content as a single string

get_theme_js_bundle_order
Return the canonical load order for Bengal default theme JS files. This order ensures dependencies…
0 list[str] 
def get_theme_js_bundle_order() -> list[str]

Return the canonical load order for Bengal default theme JS files.

This order ensures dependencies are loaded before dependents:

  1. utils.js - Core utilities (BengalUtils namespace)
  2. bengal-enhance.js - Enhancement registry (load second)
  3. core/theme.js - Theme switching (merged from theme-toggle.js + theme-init.js)
  4. core/search.js - Search (merged from search.js, search-modal.js, search-page.js, search-preload.js)
  5. core/nav-dropdown.js - Navigation dropdowns (always needed)
  6. core/session-path-tracker.js - Analytics (always needed)
  7. enhancements/mobile-nav.js - Mobile navigation
  8. enhancements/tabs.js - Tab component
  9. enhancements/toc.js - Table of contents
  10. enhancements/action-bar.js - Action bar (copy, etc.)
  11. enhancements/interactive.js - Interactive elements
  12. main.js - Main initialization
  13. enhancements/copy-link.js - Copy link functionality
  14. enhancements/holo.js - Holographic effects (merged from holo.js + holo-cards.js)
  15. enhancements/lazy-loaders.js - Lazy loading (Mermaid, D3, etc.)

Returns

list[str] —

List of JS filenames in load order (with paths relative to js/ directory)

get_theme_js_excluded
Return JS files that should NOT be bundled. These are either: - Third-party minified libraries (al…
0 set[str] 
def get_theme_js_excluded() -> set[str]

Return JS files that should NOT be bundled.

These are either:

  • Third-party minified libraries (already optimized)
  • Conditionally loaded scripts (loaded via lazy-loaders.js)
  • Feature-specific scripts that may not be enabled

Returns

set[str] —

Set of filenames to exclude from bundling

discover_js_files
Discover and order JS files for bundling from a directory. Files are ordered according to bundle_o…
1 list[Path] 
def discover_js_files(js_dir: Path) -> list[Path]

Discover and order JS files for bundling from a directory.

Files are ordered according to bundle_order if provided, with any remaining files appended at the end.

Parameters 1

Name Type Default Description
js_dir Path —

Directory containing JS files

Returns

list[Path] —

List of file paths in bundling order

create_js_bundle
Create a JavaScript bundle from a theme's JS directory. High-level function that discovers files a…
2 str 
def create_js_bundle(js_dir: Path, output_path: Path | None = None) -> str

Create a JavaScript bundle from a theme's JS directory.

High-level function that discovers files and bundles them.

Parameters 2

Name Type Default Description
js_dir Path —

Directory containing JS files
output_path Path | None None

Optional path to write bundle (if None, returns string only)

Returns

str —

Bundled JavaScript content