Configuration

Which file is loaded

The builder looks for a configuration file in your project root, the directory you run jamsedu --watch or jamsedu --build from. It checks for .jamsedu/config.js first and falls back to jamsedu.config.js in the root if that does not exist. You only need one of these files.

The file uses standard ES module syntax: export default { ... } with properties separated by commas. There is no special syntax to learn beyond the option names documented below. To run a build with a different configuration file, use jamsedu --config path/to/file.js.

Required paths

Three directory paths are required in every configuration file. Each is relative to your project root. Use clean, stable names like www/private rather than relative prefixes like ./ or ../ to keep paths predictable during builds.

        export default {
            destDir: 'output/',
            srcDir: 'src/',
            templateDir: 'src/templates'
        };
    

srcDir is your working directory where all authored content lives: .jhp pages, CSS, JavaScript, images, and other static assets. destDir is the build output where generated HTML and copied assets are written. This is what you upload or deploy to your hosting provider. You should never edit files inside destDir directly since it is regenerated on every build.

templateDir holds your shared HTML fragments and layout pieces that pages pull in using $include in JHP. Keeping templates in their own directory separates page content from site layout, so when you update something like header.html, every page that includes it picks up the change on the next build. Placing templateDir inside srcDir as shown above is the most common setup.

Options reference

The three directory paths listed below are required. All other options are optional. The pre and post options accept arrays of standard JavaScript functions using either traditional or arrow syntax. The builder calls these functions at the appropriate stage of the build pipeline.

destDir Required

Output directory where compiled HTML and copied assets are written for deployment or local preview.

srcDir Required

Input directory containing your pages, templates (if colocated), and all assets the build reads or copies from.

templateDir Required

Directory the compiler searches when resolving shared HTML templates and includes. Typically a templates folder inside srcDir.

websiteUrl Optional

Canonical absolute URL for your site (including https://), used by features like sitemap generation that need a stable origin. (Not implemented yet)

verbose Optional

Set to true to enable detailed logging on every build without passing --verbose on the command line.

pre Optional

Array of functions that run before the main template pass. Each receives the build scope which includes a mutable DOM view of the page.

post Optional

Array of functions that run after templates have been merged but before the final HTML is written to disk. Merged with any built in post processing steps where applicable.

doNotCopy Optional

List of file extensions (without the leading dot) that should not be copied into destDir. Setting this replaces the entire default exclusion list, so your array must include every extension you still want excluded.

Hooks

Hooks let you run your own JavaScript during the build to adjust HTML structure, inject repeated markup, or normalize content across pages. These are not browser scripts; the builder executes them while processing each page. pre hooks run before template expansion, and post hooks run after templates are applied but before the final HTML is written to disk.

Each hook receives structured access to the current document through a scope object, allowing you to query and modify the page tree. You do not need hooks for a straightforward static site. They are there for when templates and static assets alone are not enough.

For full details on the build pipeline, execution order, and working examples, see the Hooks page.