Iwf Guide

Installation

This page gets the framework and the canonical example running locally. The canonical example is the best first app to study because it uses the real Iwf build pipeline.

1. Enter The Development Shell

From the repository root:

nix develop

Use the Nix shell when possible. It gives you the Idris toolchain and the local PostgreSQL setup expected by the checks.

2. Build The Framework

Still from the repository root:

pack typecheck iwf

iwf is a library package. Applications provide their own executable.

3. Run The Canonical App

The canonical app lives in examples/canonical. It is a RealWorld-style app with HTML pages, JSON routes, authentication, generated schema rows, TypedSQL, IDRX views, OpenAPI docs, jobs, mail previews, uploads, Stripe payloads, i18n, and Auto Refresh.

cd examples/canonical
devenv up

devenv up starts PostgreSQL, the canonical server, and the local watchers used by the example. On repeat runs it starts the last successful server quickly and rebuilds in the background.

Useful commands inside examples/canonical:

iwf-build
iwf-test
iwf-ensure-db
iwf-kill-orphans
./build/exec/canonical-demo serve
./build/exec/canonical-demo openapi

4. Run The Main Check

From the repository root:

iwf check

iwf check runs the normal repository and canonical app verification sequence: IDRX checks, generated-code checks, TypedSQL surface checks, framework specs, compile fixtures, canonical schema/typegen/build checks, canonical HTTP end-to-end checks, and OpenAPI checks.

TypedSQL is PostgreSQL-backed, so this command needs DATABASE_URL or IWF_DATABASE_URL. The canonical app's development setup exports this for you.

To see the sequence without running it:

iwf check --dry-run

For a smaller loop, run focused acceptance groups:

tests/scripts/acceptance shell htmx-fragments typed-forms typedsql-postgres auto-refresh-races

5. Editor Setup

Starter apps generated by iwf new include the app build and check scripts used by iwf build and iwf check. The build path installs the local framework into .iwf/idris2 and sets the Idris package path for the app build.

The canonical example's Nix/devenv setup provides the same package-path environment for that app.

Create a small app with Your First Project.