# Rat

> Rat is a minimal web framework and language where one .rat file is a server, a page, and its styles - reactive pages with no JS to write, no build step, one Go binary. Every callable is `name.method(args)`: builtins, services, the built-in SQLite layer, JSON APIs, Python modules (Tail), and browser JS libraries (Inverse Tail) all dispatch through the same primitive.

Start here:

- [Rat for AI models](https://rat-lang.com/llms-full.txt): the complete dialect guide plus every documentation page in one file - read this before writing any Rat code
- [Documentation](https://rat-lang.com/documentation): human docs; every page has live runnable examples

## Basics

- [Setup](https://rat-lang.com/documentation/basics/setup): Rat ships as a single binary with no runtime or package manager.
- [Hello world](https://rat-lang.com/documentation/basics/hello_world): The smallest meaningful Rat file.
- [Interpolation](https://rat-lang.com/documentation/basics/interpolation): `[expr]` is Rat's one read mechanism.
- [HTML attributes](https://rat-lang.com/documentation/basics/html_attributes): Every HTML attribute is authored with bracket syntax.
- [Reactivity](https://rat-lang.com/documentation/basics/reactivity): `> page` state lives in the browser.
- [Pups (components)](https://rat-lang.com/documentation/basics/pups): A pup is any `.rat` file under `pups/`.
- [Services](https://rat-lang.com/documentation/basics/services): A service is a named singleton declared in `main.rat` with its own state and methods.
- [State tiers](https://rat-lang.com/documentation/basics/state_tiers): Rat has five state tiers, each with a different lifetime and visibility.
- [Functions](https://rat-lang.com/documentation/basics/functions): A top-level `> name[params]` declares a function.
- [Guards and loops](https://rat-lang.com/documentation/basics/guards_and_loops): Rat has no `if`/`else` keyword.

## Pages

- [Routing](https://rat-lang.com/documentation/pages/routing): Routes come from the filesystem.
- [Dynamic routes](https://rat-lang.com/documentation/pages/dynamic_routes): Wrap a path segment in square brackets to make it dynamic.
- [Main shell](https://rat-lang.com/documentation/pages/main_shell): `main.rat` at the project root is the document shell: the header, footer, nav, and anything every page needs.

## Styling

- [Style blocks](https://rat-lang.com/documentation/styling/style_blocks): Rat has two ways to write CSS: a section header that takes a selector (`> [selector]`) with declarations indented under it, or full-file blocks under `styles/` for global rules.
- [CSS variables](https://rat-lang.com/documentation/styling/css_variables): Declare design tokens once in `:root` and reuse them anywhere via `var(--name)`, or via the shorter `[name]` form, which Rat rewrites to `var(--name)` at parse time.
- [Inline styles](https://rat-lang.com/documentation/styling/inline_styles): The `style` attribute writes inline CSS.

## Data

- [Models](https://rat-lang.com/documentation/data/models): A model is a table definition: name, fields, types, and attrs.
- [Databases](https://rat-lang.com/documentation/data/databases): A `> database` block declares a connection.
- [Queries](https://rat-lang.com/documentation/data/queries): Every declared model gets a CRUD surface on its database global.

## API

- [API files](https://rat-lang.com/documentation/api/api_files): A `.rat` file under `api/` becomes an HTTP endpoint under `/api/`.
- [Public endpoints](https://rat-lang.com/documentation/api/public_endpoints): Not every function in an `api/` file should be reachable over HTTP, such as internal helpers, write-side mutations, or anything that bypasses auth.

## Forms and uploads

- [Forms](https://rat-lang.com/documentation/forms_and_uploads/forms): Forms in Rat are just `> page` state plus event handlers.
- [File uploads](https://rat-lang.com/documentation/forms_and_uploads/file_uploads): Binary uploads use the dedicated endpoint `/__rat__/upload`, separate from the JSON call path.

## Realtime

- [Channels](https://rat-lang.com/documentation/realtime/channels): A channel is a named publish/subscribe topic.

## Dev workflow

- [CLI](https://rat-lang.com/documentation/dev_workflow/cli): The `rat` binary does everything: create a project, run the dev server, build static HTML, install dependencies, and run database tooling.
- [Script mode (rat run)](https://rat-lang.com/documentation/dev_workflow/scripts): `rat run script.rat [args...]` executes a single `.rat` file's `> main[args]` against the same eval engine the dev server uses.
- [Settings](https://rat-lang.com/documentation/dev_workflow/settings): Project-wide configuration lives in `settings.rat`.
- [Parser errors](https://rat-lang.com/documentation/dev_workflow/errors): The parser flags common dialect mistakes with a one-line did-you-mean hint, so a misleading `unexpected token` message points you straight at the documented fix.
- [Hot reload](https://rat-lang.com/documentation/dev_workflow/hot_reload): Save a file and the browser updates.

## Advanced

- [Tail (Python)](https://rat-lang.com/documentation/advanced/tail): Rat's dispatch call, `name.method(args)`, works the same whether the callee is a builtin, a service, a DB handle, or a function in another runtime.
- [Inverse Tail (JS)](https://rat-lang.com/documentation/advanced/inverse_tail): Tail handles "server-side Rat calls foreign code"; Inverse Tail handles "browser-side Rat (page-tier, compiled to JS) calls foreign code that already lives in the page." It uses the same …
- [Middleware](https://rat-lang.com/documentation/advanced/middleware): A middleware is a service with two extras: a route pattern (`match: '/...'`) and lifecycle hooks (`before[req]`, `after[req]`, `on_start[]`, `on_shutdown[]`).
- [Location transparency](https://rat-lang.com/documentation/advanced/location_transparency): The same pure-computation call produces the same result regardless of which host runs it.

## Builtins

- [Logging](https://rat-lang.com/documentation/builtins/logging): `log`, `debug`, and `error` are the three console builtins.
- [Inspection](https://rat-lang.com/documentation/builtins/inspection): Five builtins for inspecting values.
- [Strings](https://rat-lang.com/documentation/builtins/strings): The string builtins cover the basics every web app needs: case folding, whitespace trimming, splitting and joining, substring search and replace, prefix and suffix checks, padding for column …
- [Math](https://rat-lang.com/documentation/builtins/math): Nine numeric builtins.
- [Conversion](https://rat-lang.com/documentation/builtins/conversion): Builtins for moving values between kinds.
- [Collections](https://rat-lang.com/documentation/builtins/collections): The array and map builtins.
- [Encoding](https://rat-lang.com/documentation/builtins/encoding): Three pairs of builtins for the encodings every web app eventually needs.
- [HTTP](https://rat-lang.com/documentation/builtins/http): Five members on the `http` namespace for outbound requests: `http.get`, `http.post`, `http.put`, `http.delete`, and `http.request` for arbitrary methods.

## Namespaces

- [JSON](https://rat-lang.com/documentation/namespaces/json): Two members on the `json` namespace: `json.parse` turns a JSON string into a Rat value, and `json.stringify` goes the other way.
- [Date](https://rat-lang.com/documentation/namespaces/date): Five members on the `date` namespace.
- [Regex](https://rat-lang.com/documentation/namespaces/regex): Four members on the `regex` namespace.
- [Bit](https://rat-lang.com/documentation/namespaces/bit): Bitwise operations live on the `bit` namespace instead of infix operators, because every bitwise symbol is already spoken for in the dialect - `&` is logical and, `|` is logical or, `<<` is …

## Security

- [Publishing a Rat app](https://rat-lang.com/documentation/security/publishing): Rat ships a hardened substrate, but a few things have to be wired up per deploy: secrets, TLS, prod mode, and the populators that turn rate limiting and audit logging on.
- [Threat model](https://rat-lang.com/documentation/security/threat_model): Rat draws a deliberate line between framework substrate and per-app code.
- [Sample configs](https://rat-lang.com/documentation/security/samples): Minimal, copyable templates for the most common deploy shapes.

## Native apps

- [Desktop & mobile apps](https://rat-lang.com/documentation/native/desktop_and_mobile): A Rat app is already a Go HTTP server with SSE reactivity.
- [Native services](https://rat-lang.com/documentation/native/native_services): Native services are built-in globals whose backend touches the host: the filesystem, OS notifications, the share sheet, the system tray.