README.adoc

Site builder

This is a CLI tool to build a static site for given Paneron RegistryKit-based dataset.

STATUS: Not production ready; currently under development.

Tested using Node 20.11.1.

Quick Usage

Building the site artifacts with local data

Is is intended to be run as:

npx @paneron/site-builder [options...] --outdir OUTDIR

It would:

• read Paneron dataset from current directory (can be specified with --datadir DATADIR),

• place site assets under OUTDIR,

• generate data indices as required by site runtime and place them under OUTDIR where expected.

Serving the site with local data

npx @paneron/site-builder [options...] --outdir OUTDIR \
  watch [--serve [--port PORT]] [--watch-template]

It would:

• build site assets as in the above,

• start an HTTP server under the specified PORT, serving OUTDIR.

When done, press Ctrl-C to stop serving.

Synopsis

npx @paneron/site-builder --outdir OUTDIR \
  [--debug | --verbose] \
  [--datadir DATADIR] \
  [--dataversion GITREF] \
  [--devextpath DEVEXTPATH] \
  [--forusername USERNAME] \
  [--injected-entries COMPILED_JAVASCRIPT_FILE]* \
  [--injected-assets-dir WEB_ASSETS_DIR] \
  [--injected-assets-prefix WEB_ASSETS_DIR_PREFIX] \
  [watch [--serve [--port PORT]] [--watch-template]]

Commands

watch

Watch for changes in the dataset and rebuild the site.

Options

--outdir OUTDIR

(Required) Specify path to directory for outputs. Will be created by this tool if not exists.

--debug

Enable debug logging.

--verbose

Enable verbose logging.

--datadir DATADIR

Specify path to Paneron dataset directory. Must contain panerondataset.yaml. Default: current directory.

--dataversion GITREF

Specify Git ref of Paneron dataset under DATADIR. Default: whichever ref is currently checked out, i.e. git rev-parse --short HEAD.

--devextpath DEVEXTPATH

Specify path to local development extension.

--forusername USERNAME

Specify username, for access to the register.

--injected-entries COMPILED_JAVASCRIPT_FILE

Specify path to compiled JavaScript file to be loaded. May be specified multiple times.

--injected-assets-dir WEB_ASSETS_DIR

Specify path to directory with web assets to be copied to the output directory.

--injected-assets-prefix WEB_ASSETS_DIR_PREFIX

Used with --injected-assets-dir. Specify prefix to be used when copying assets to the output directory.

--serve

Serve the built site.

--watch-template

Used under watch. Specify whether to also watch for changes in the site template directory apart from the dataset directory.

--port PORT

Used with --serve. Specify port to serve the site on. Default: 8080.

Development

Note that build is handled by esbuild, while TSC is still used for typechecking. Type errors shouldn’t be ignored, but a type error may still result in a valid build (depends on specifics).

Important scripts

• Root package’s build-self script compiles site builder

• site/spa’s clean-build script compiles front-end code

  • This is also run by the root package’s build-template script.

    Important

    This repository uses Yarn PnP, but in loose mode for the sake of spa package build script. Since ExtensionKit and RegistryKit import packages that they list only in devDependencies, in strict mode esbuild would fail with an error for every such import when bundling SPA for client-side.

Testing with local data

Common steps

1. Working from the repository root, build the site builder, making sure build-site.mjs is being output and is executable:

   > yarn run build-self ; yarn run build-template
   > ls -l build-site.mjs
   -rwxr-xr-x@ 1 username  groupname  1943914  1 Jan 13:37 build-site.mjs

Building the site artifacts with local data

2. Run ./build-site.mjs with the required parameters:

   > ./build-site.mjs --datadir DATADIR --outdir OUTDIR
   Fetch extension code from .../extension.js to OUTDIR/extension.js: 863.576ms
   Fetch package.json from .../package.json to OUTDIR/package.json: 407.994ms
   Fetch extension JS OUTDIR: 1.283s
   Scaffold site template from .../site/spa/dist into OUTDIR: 3.027s
   Fetch extension code from .../extension.js to OUTDIR/extension.js: 178.606ms
   Fetch package.json from .../package.json to OUTDIR/package.json: 87.67ms
   Importing site builder from .../site/spa/build-site.mjs: 84.967ms
   Running site builder: 754.246ms
   >

Serving the site with local data

2. Run ./build-site.mjs with the required parameters, with the watch --serve option. When done, press Ctrl-C to stop serving:

   > ./build-site.mjs --datadir DATADIR --outdir OUTDIR watch --serve --port 8080
   Fetch extension code from .../extension.js to OUTDIR/extension.js: 863.576ms
   Fetch package.json from .../package.json to OUTDIR/package.json: 407.994ms
   Fetch extension JS OUTDIR: 1.283s
   Scaffold site template from .../site/spa/dist into OUTDIR: 3.027s
   Fetch extension code from .../extension.js to OUTDIR/extension.js: 178.606ms
   Fetch package.json from .../package.json to OUTDIR/package.json: 87.67ms
   Importing site builder from .../site/spa/build-site.mjs: 84.967ms
   Running site builder: 754.246ms
   Serving on port 8080.  Access at http://localhost:8080
   ^C
   timestamp=2025-01-01T03:13:37.502Z level=WARN fiber=#3731 message="serve: Caught interrupt signal.  Stopping server..."
   >

Alternatively, after building the site, run:

> npx serve OUTDIR [--listen PORT]

Summary — Typical Development Workflow

1. Make changes to the site builder or the site template (site/spa).

2. Run the following to compile the site builder and the site template:

   > yarn run build-self && yarn run clean-build-template && \
     ./build-site.mjs --datadir DATADIR --outdir OUTDIR \
     watch --serve

3. Test the site in a browser (default at http://localhost:8080).

Release

• Remember to verify that everything runs without errors in the "Important scripts" section before testing & publishing.

• Run npm publish from the root (no need to change into a separate “dist” dir).

License

See LICENSE for license information.