logo logo
Development meta


Securepub developers need these things:

direnv         https://github.com/direnv/direnv
fswatch        https://github.com/emcrisostomo/fswatch
jq             https://github.com/jqlang/jq
just           https://github.com/casey/just
overmind       https://github.com/DarthSim/overmind
pnpm           https://github.com/pnpm/pnpm
python         https://www.python.org/downloads
zola           https://github.com/getzola/zola

Software Stack

Securepub is a static site built on the "zbetezu" stack:

Software Role
Zola ↗︎ Generates a static HTML site from Markdown and templates.
Bulma ↗︎ Provides CSS styling for HTML.
Elm ↗︎ Crash-free user interaction.
Typescript ↗︎ Integration with browser APIs and third-party packages.
Effect-ts ↗︎ Asynchronous execution of workflows.
Zod ↗︎ Validation of json structures read and written to Userbase.
Userbase ↗︎ Private and secure cloud storage.

See the setup section for information on setting up a development enviroment.

Building Securepub

The Securepub build process installs components it needs with pnpm except for items shown in bold (e.g. Zola ↗︎) which are expected to be present in the environment.

A cursory check is done for required components each time a build is done.

Package Role
Just ↗︎ "top level" build and development CLI.
Nodejs ↗︎ Used by Elm, Pnpm and the json-to-elm ↗︎ code generator.
Pnpm ↗︎ Installs Bulma, Elm, Typescript, Effect-ts, Zod and Userbase.
Builds individual Elm and Typescript project workspaces.
Python︎ ↗︎ Synchronizes files and converts yaml frontmatter to json.
Jq ↗︎ Helps build and post-process Javascript generated by Elm.
Tsc ↗︎ Typescript module type checking.
Esbuild ↗︎ Typescript module transpilation and bundling.
json-to-elm ↗︎ json-to-elm generates json decoders for Elm.
awk, ex, bash Build scripting.

Note: awk and bash should be present on any reasonable Unix system but ex might be missing from minimal distros used for build containers. On Alpine linux it is part of the vim package.

The build section explains how the build is done.

Interactive Development

The following additional software is required for interactive development.

A cursory check is done for required components each time interactive development is started.

Package Role
Direnv ↗︎ A direnv .envrc file manages the workspace $PATH.
Overmind ↗︎ Supervises zola, esbuild, tsc and the .sync.py script.
Fswatch ↗︎ The python .sync.py script uses fswatch to detect file changes.

The interactive development section explains how interactive development works.