Configuration

A Zigapagos project is configured in two places: zigapagos.ziggy describes the site, and the zigapagos release invocation that builds it declares the islands and SPAs to compile.

zigapagos.ziggy

Site {
    .title = "My Site",
    .host_url = "https://example.com",
    .url_path_prefix = "",
    .content_dir_path = "content",
    .layouts_dir_path = "layouts",
    .assets_dir_path = "assets",
    .deploy_target = "zigbase",
}

.title is available in every layout as $site.title.

.host_url is the origin used to build absolute URLs — canonical links, feeds, and social metadata.

.url_path_prefix is the subpath the site is served from. On GitHub project pages this is the repository name. Set it and then never hand-write an internal URL: $site.page('docs/overview').link() and $site.asset('style.css').link() apply the prefix, and a literal /docs/ does not, so a hardcoded link works locally and 404s in production.

.content_dir_path, .layouts_dir_path and .assets_dir_path are relative to the project root.

.deploy_target selects which host configuration the build emits — zigbase, nginx, or apache. See native SPAs for what each one generates.

The build invocation

zigapagos is a standalone executable, so a project’s build is one command rather than a build graph — nothing here needs a Zig toolchain. Keep that command in a build.sh at the project root so the entries are declared in exactly one place; zigapagos init --from-astro scaffolds one for you.

#!/usr/bin/env bash
set -euo pipefail
cd "$(dirname "$0")"

exec zigapagos release \
  --force \
  --output=public \
  --island=components/Counter.island.tsx \
  --spa='app/app.spa.tsx|/app' \
  --spa-not-found=app \
  "$@"

--island=SRC names one island source as a path relative to the project root, and that path is what an <island src="…"> attribute must match. Repeat the flag once per island.

--spa=SRC|BASE registers a native SPA. BASE must equal the base exported from the .spa.tsx module. The build validates the match and fails loudly if they diverge, because a mismatch produces an application whose router and whose prerendered shells disagree about where they live.

--spa-not-found=NAME names which SPA owns the site-wide 404.html, by file basename without the .spa.tsx suffix. Set it explicitly when there is more than one SPA; otherwise declaration order decides, which is not a property you want a deployment to depend on.

--output=DIR is the output tree (default public/), and --force lets the build overwrite one it did not create. Run zigapagos release --help for the rest.

A note on failure and partial output

Build failures write the output tree in place, so a failure partway through leaves a partially updated site. The pass order limits the damage — SPA validation runs before any page is written — but it is not atomicity. Build to a staging directory if you are deploying by syncing the output tree.