Iwf Guide

Getting Started With Iwf

Iwf is a full-stack Idris web framework. One Idris codebase owns routes, controllers, HTML, forms, JSON APIs, SQL, tests, and development tooling.

Iwf is inspired by the productive shape of IHP, but it is not an IHP compatibility layer. The guide below focuses on the code you write in an Iwf app first. Internals and roadmap details are linked later.

Learning Path

If you are new to Iwf, follow these pages in order. Each page builds on the previous one.

1. Getting Started

• Installation: enter the development shell, build the framework, run the canonical app, and run the main checks.
• Your First Project: generate a small app, change the first page, add a route, add a schema table, and see where generated code lives.
• First CRUD Feature: build one article feature with a path route, form, table, TypedSQL query, validation, auth, live fragment, and iwf check.
• Architecture: understand the normal Application/, Config/, and Web/ layout.
• Config and Server: configure ports, sessions, database access, logging, request limits, and server startup.

2. Core Concepts

• Routing: map URLs to Idris handlers and generate links from the same route values.
• Controllers: handle requests, render pages and fragments, redirect users, and protect routes.
• Views and IDRX: write HTML-like .idrx files that compile into checked Idris.
• Forms and Validation: build route-backed forms, preserve submitted values, and show field errors.
• Database and Migrations: define the schema in PostgreSQL SQL, generate Idris row types, run migrations, and use the runtime database pool.
• TypedSQL: write raw SQL that PostgreSQL describes before the Idris module compiles.

3. Common App Features

• JSON API and OpenAPI: reuse route metadata for JSON endpoints and Swagger/OpenAPI docs.
• Sessions, Cookies, Flash, and CSRF: use signed sessions, flash messages, raw cookies, and CSRF protection.
• Authentication and Authorization: add login, current-user lookup, route guards, Basic Auth, OAuth/passkey adapter boundaries, and account safety helpers.
• Jobs, Scripts, and Mail: run background jobs, app-context scripts, typed mail, and development mail previews.
• File Uploads and Storage: decode multipart uploads and store files locally or through S3-compatible storage.
• Integrations, I18n, and Payments: add translations, locale selection, Stripe Checkout, webhooks, OAuth, and passkey integration boundaries.

4. Frontend

• HTMX, Auto Refresh, and Modals: use the default boosted shell, modal host, fragment rendering, and scoped live refresh.
• Assets and Styling: serve framework assets, app assets, fingerprinted files, Basecoat defaults, and development reload helpers.
• Navigation, Pagination, and SEO: render navigation, breadcrumbs, pagination, page head metadata, OpenGraph tags, and sitemaps.

5. Going Further

• Dependent Routes and Forms: learn how the dependent types connect pathTo, request decoding, and IDRX form checks.
• PostgreSQL Runtime Architecture: read the database adapter contract and current helper implementation.
• Internal Technical Architecture: read the maintainer-level architecture, code organization, subsystem boundaries, and known shortcomings.
• IHP Migration Notes: compare Iwf's public surface with IHP and see which IHP features are intentionally out of scope.

6. Production and Maintenance

• Security and Deployment: validate production config, install security headers, use RLS request context, and follow the deployment checklist.
• Testing and Debugging: run framework tests, acceptance harnesses, route tests, diagnostics, and browser request debugging.
• Troubleshooting: fix common setup, build, browser, Auto Refresh, TypedSQL, asset, and OpenAPI problems.

What Iwf Gives You

• Typed routes with typed path, query, JSON body, form body, and multipart body decoding.
• pathTo and redirect helpers that reuse the same route values used by dispatch.
• Direct .idrx HTML that turns into checked Idris source.
• A default htmx/morphdom/Basecoat shell with stable main content, flash, modal, and Auto Refresh hosts.
• HTML pages, HTMX fragments, JSON endpoints, and OpenAPI docs from route metadata.
• PostgreSQL schema typegen, migrations, fixtures, generated model records, TypedSQL, and pool-backed runtime execution.
• Auth, signed cookie sessions, CSRF, flash, authorization helpers, jobs, mail, uploads, Stripe helpers, i18n, SEO, pagination, navigation, and test helpers.
• iwf check for the canonical repository and app verification path.

What Iwf Does Not Try To Be

Iwf intentionally does not provide an IHP compatibility layer, query-builder DSL, model-backed forms, generated relationship helpers, validation metadata on generated database rows, IHP DataSync, public typed WebSocket routing, server-side components, a first-class NPM/Yarn workflow, a browser IDE, or compatibility shims for renamed APIs.

Next

Start with Installation.