TL;DR
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.