This appendix explains how to load lib/webg.core.min.js and convert samples
that use individual modules. Run the commands from the repository root.
lib/
webg.core.min.js
webg.core.min.js.map
webg.core.js
webg.core.js.map
convert_imports.mjs
build_report.json
package.json
package-lock.json
LICENSE
webg/ Original source with comments and assets
samples/ Samples using individual modules
For JavaScript at the repository root, use:
import { WebgApp, Shape, Primitive, WaterBody, PbrRenderer }
from "./lib/webg.core.min.js";
Classes use their class names as public export names. Use WebgApp as App for a
local alias. Choose webg.core.js to inspect bundled code with comments.
Source maps connect bundled code to the original lines and breakpoints in
browser developer tools. Keep the relative layout of lib/ and webg/ when
using them.
Both builds use the same APIs. Replace the individual imports shown in the
chapters with named imports from the bundle. Use one loading method for the
core throughout an application, including shared helpers, so that its classes
and module state remain consistent for instanceof and collision handling.
The bundle combines JavaScript. Images, fonts, models, and environment maps
keep their own URLs. An inline module resolves its imports relative to the
HTML page; an external module resolves them relative to its JavaScript file.
Asset URLs used by fetch() or library APIs follow those APIs’ URL rules.
Use the HTTP server and WebGPU-capable browser described in Chapter 2. An application can load the distributed bundle directly. Node.js and the packages below are tools for converting samples.
The tool has been checked with Node.js 22. Install its dependencies:
npm --prefix lib ci
node lib/convert_imports.mjs --help
The script uses lib/build_report.json to map original modules to bundle
exports. Use the bundle, converter, and mapping file from the same distribution.
For example, preview conversion of samples/aquarium/:
node lib/convert_imports.mjs samples/aquarium
The default mode lists changes. Review the files, number of replacements, and
before-and-after code. --dry-run has the same behavior. The tool follows local
JavaScript dependencies, including shared helpers and dynamically loaded files.
Start with a copy that keeps the original samples available for comparison.
Choose a new or empty directory for --out:
node lib/convert_imports.mjs --execute \
--out user/bundled-samples samples/aquarium samples/water
The tool preserves paths relative to the repository root. The copies appear at
user/bundled-samples/samples/aquarium/ and
user/bundled-samples/samples/water/. It copies regular files in the selected
directories, including CSS, models, and documentation, and converts shared
JavaScript dependencies as well. Check assets, CSS, and other URLs outside the
selected directories against the copied layout.
Start the Chapter 2 HTTP server at the repository root and open, for example:
http://localhost:8000/user/bundled-samples/samples/aquarium/aquarium.html
http://localhost:8000/user/bundled-samples/samples/water/water.html
Check rendering, camera controls, movement or animation, and effect toggles.
In the developer tools’ Network panel, look for lib/webg.core.min.js and any
individual core JavaScript requests. If individual core files are still loaded,
review the conversion of shared helpers and dynamic imports.
After reviewing the preview and testing the copy, omit --out to update the
original files and their shared JavaScript dependencies:
node lib/convert_imports.mjs --execute samples/aquarium
Keep the previous state in a commit or backup to compare changes.
--execute enables writing. Preview and execution each read the target code
as it exists at that time.
Default imports and aliases become named imports of the public class name:
// Individual module
import App from "../../webg/WebgApp.js";
// Bundle, when converting the sample in its original location
import { WebgApp as App } from "../../lib/webg.core.min.js";
Named exports have unique mapping names. For example:
import { DepthConvention_CAMERA_REVERSE_Z as CAMERA_REVERSE_Z }
from "../../lib/webg.core.min.js";
This preserves the local name and the ES module’s live binding. The converter
also handles namespace imports, re-exports, and dynamic imports with literal
paths. In HTML, it processes type="module" scripts and preserves the remaining
markup. It retains comments within imports as well.
Review dynamic imports whose paths are variables, unregistered core modules or exports, import attributes, HTML base elements, core references through URLs or import maps, and core paths with query strings. The tool reports these cases and stops before writing changes.
Select the version with comments using --bundle:
node lib/convert_imports.mjs --bundle lib/webg.core.js \
--out user/bundled-readable samples/water
This command previews changes. Add --execute to write them. Target paths,
--bundle, and --out are resolved from the command’s working directory.