Introduction

What Crisptastic is

Crisptastic is a web framework for sites that have outgrown static hosting.

You write a folder of pages the way you would for a static site generator. Pages are text files with a small template syntax. Unlike a static generator, Crisptastic runs a page on the server for each request, so the output can depend on the URL, the form that was submitted, the visitor's cookies and session, and data fetched from other services.

You then ship the whole site as one encrypted, signed file (a Capsule) to a host: a single program that serves many sites, choosing the site by domain, behind your reverse proxy.

You do not write or operate an application server for your site, or build a runtime image, or manage per-site proxy configuration.

The pieces

Piece	What it is
Page	A .crisp file. Its name decides its URL and content type.
Partial	A .crisp file whose name starts with _. Included by other pages; never served.
Directive	An @-prefixed instruction in a page: @if, @for, @include, @fetch, @session, ...
crisptastic.toml	Optional site configuration: domains, environment, integrations.
Integrations	Ready-made helpers for Auth0, Stripe, S3 and Cloudflare Images, plus a few experimental capabilities.
Capsule	The deployable unit: your site's files and secrets, signed and encrypted.
Host	crisptastic host, the production server. Many sites per process.
Fabric	An optional in-memory cluster of hosts that keeps sites running when a node is lost. Preview.

A page in thirty seconds

{{-- blog/[slug].html.crisp  ->  /blog/:slug --}}
@fetch post = get_json("https://api.example.com/posts/" + request.route.params.slug)

@if (post.ok) {
  <h1>{{ post.value.title }}</h1>
  {{~ post.value.html }}
} @else {
  @status 404
  <p>No such post.</p>
}

• The file name gives the route /blog/:slug and text/html.
• @fetch calls an HTTPS JSON API. A failure does not throw; the page checks post.ok.
• {{ ... }} prints HTML-escaped values; {{~ ... }} prints trusted markup.
• @status sets the response code.

How a request flows

browser --HTTPS--> your reverse proxy --HTTP--> crisptastic host
                                                     |
                                   choose site by domain (exact match)
                                                     |
                      static asset?  --> serve it
                      route match?   --> run the page: fetches, effects, output
                      otherwise      --> 404 page

During a page run, @fetch and @call do outbound work, and @session, @cookie, @status and @redirect record effects. After the page finishes successfully the host applies the effects and sends the response. If the page fails, none of its effects are applied and the visitor gets a 500 page.

What it is not

• Not a static site generator. Pages execute per request and can differ per visitor.
• Not a backend framework. There are no models, ORM, background jobs or custom server code. Your records live in your own API or database service, and pages read them over HTTPS. If you need your own server logic, run that as a separate service and call it.
• Not a container platform. A Capsule is one site's files, not an arbitrary process.
• Not a database server. Sessions are local files, and a site on a single host can have one embedded store that only it can reach. Anything bigger belongs in your own service.
• Not a hosted service. You operate the host yourself.

Choosing whether it fits

Crisptastic is a good match when:

• the site is mostly pages and forms, perhaps with sign-in, payments or uploads handled by the supported providers;
• data lives behind HTTPS APIs you already have;
• you are comfortable operating one Linux service and a reverse proxy.

Look elsewhere (or talk to the maintainers first) when you need server-side state beyond a session or a single-host embedded store, long-running or background work, WebSockets, response streaming, per-user authorization enforced outside the page, sites from mutually untrusted tenants on one host, or a mature, certified platform. See Known gaps for the honest list.

How this documentation is organised

Section	Chapters
Start	Quickstart, Build a small site, Read from an API, A guestbook, Keep a form honest, Ship it
Build pages	Project layout and routing, Pages and templating, Request data, sessions and forms, Fetching and shaping data, Capabilities and integrations
Reference	Cheatsheet, Configuration, Command-line
Ship and operate	Deploying, Running a host, Clustering, Security model
Honesty	Known gaps and differences

A word on terms. Crisp is the page syntax, the part of this project you write. You will see the .crisp extension everywhere. Crisptastic is the framework and server that runs it.