Quick start

Choose your starting point

This walkthrough starts with init --minimal: one content page, one HTML layout, and plain CSS. It ships no JavaScript, fonts, or demo dependencies. For an application, add native SPA routes; for an integrated backend, follow Building applications. The same commands work for direct development and coding agents. No AI account is needed. A complete paired application starter remains planned work.

Install

zigapagos is a standalone executable. You do not need a Zig toolchain to build a site — nothing in a Zigapagos project is compiled from Zig source.

The shortest path is npm, which brings everything a site can need in one install:

npx zigapagos init --minimal

npx runs the scaffold in your current directory; start in an empty project directory. It does not install a global command. If you use this option, prefix the subsequent zigapagos commands below with npx too (for example, npx zigapagos release), and skip the Generate a site step.

That pulls @zigapagos/cli, which ships the binary, the @z/runtime sources, the Bun sidecar, and Bun and ZigBase as optional dependencies. It needs Node 18 or newer to run the launcher, and covers everything: content sites, islands, native SPAs and the dev loop.

Prefer a bare binary? Download one from the releases page — x86_64 and arm64 builds for Linux (musl) and macOS — and put it on your PATH. That archive is the binary and nothing else, which is enough for a content-only site but not for islands or SPAs; those additionally need Bun and the @z/runtime tree, and the npm install is the way to get both. The full rule, per command, is in runtime dependencies.

Generate a site

mkdir my-site && cd my-site
zigapagos init --minimal

Edit content/index.smd, layouts/page.shtml, and assets/style.css. The layout uses ordinary HTML with a few SuperHTML attributes to insert the page title, content, and asset URL. Start with the included CSS or replace it with your own styles, CSS framework, or design system. No framework is required. Generated AGENTS.md instructions are available if you use a coding agent; the same commands work directly in your terminal.

For a complete content-site example, use zigapagos init without --minimal. That writes a sample site: a homepage, an about page, a blog section, a devlog, the layouts that render them, and the assets they reference. It is worth reading before deleting — the sample copy demonstrates SuperMD syntax you will otherwise have to look up.

Start a browser-local application

Use zigapagos init --app for a small task application with navigation, a labelled form, loading/empty/error states, and ordinary CSS. Its landing page remains static. This demo saves tasks in one browser; it provides no sign-in, server database, or synchronization.

The npm launcher supplies the runtime location. For a standalone binary, use zigapagos init --app --runtime-path=../zigapagos/runtime and first install that runtime’s dependencies with bun install --frozen-lockfile in its directory. Then run bun install, bun run check, and bun run build in the new project. The generated README explains bun run dev, npx usage, and moving the explicit local runtime dependency to another machine. Keep the workspace layout available.

The application guide explains the backend boundary. An API-backed or ZigBase-paired starter remains separate planned work.

Write a page

A content file opens with a Ziggy frontmatter block. Two fields are required:

---
.title = "About",
.layout = "page.shtml",
---

.title is the page’s title and .layout names the template in layouts/ that renders it. Every other field has a default — .description and .author are empty, .date is the Unix epoch, .draft is false, .tags, .aliases and .alternatives are empty lists — so add one when something reads it, not by habit. A blog post needs .date because the listing layout renders it for each entry; a landing page usually needs neither a date nor an author, and the scaffold init writes reflects that.

Run the development server

zigapagos dev

dev needs no arguments: it builds the site into public/, serves that tree at http://127.0.0.1:1990 with ZigBase — downloading the pinned release the first time if you have none — and rebuilds when you edit content, layouts, or assets. The page in your browser refreshes itself.

Run zigapagos with no command and you get the help menu, not a server; every command is explicit.

Build and deploy

zigapagos release
zigapagos doctor public --strict

Set .host_url in zigapagos.ziggy to your production origin before deploying. Upload the contents of public/ to a static host. The minimal starter needs no application server or client runtime.

Add an island

Create components/Hello.island.tsx:

import { useState } from "@z/runtime";

export interface Props { name: string }

export default function Hello({ name }: Props) {
  const [waves, setWaves] = useState(0);
  return (
    <button onClick={() => setWaves(waves + 1)}>
      Hello {name} — waved {waves} times
    </button>
  );
}

Declare it on the build command:

zigapagos release --island=components/Hello.island.tsx

Once a project has more than one, keep that invocation in a build.sh so the entries are declared in one place — see configuration.

And use it in a layout — not in a .smd file, which rejects raw HTML:

<island src="components/Hello.island.tsx" client:visible prop-name="world"></island>

Rebuild. The button is server-rendered into the HTML, and hydrates when it scrolls into view.

The tutorial builds something real. Islands is the full reference for directives, props, and slots.