# alacris-go

> Render alacris web components from Go and templ. Typed Go wrappers generated
> from your define() calls, the alacris runtime vendored and served from Go with
> no npm, a Material Design 3 design system in the module (`Config.UI`), and an
> optional layer that makes the server authoritative over component state: one
> property write per change, with no HTML on the wire.

A component's shadow content is produced by setup() in the browser, so the
server renders the element, its attributes, and its light-DOM slot children,
never the component's internals. Every prop crosses as an attribute, objects
and arrays included, because alacris coerces using the type of the prop's
default and parses object defaults with JSON.parse.

Three layers plus an optional desktop host, each usable alone: `alacris`
(render, stateless), `gen` + the `alacris-go` CLI (typed wrappers), `live`
(server-driven props and component events over SSE and POST), `app` (the same
live handler in an OS webview).

## Start here

- [What is alacris-go?](https://bmartel.github.io/alacris-go/start/what-is-alacris-go/): The model, what a server can and cannot render, why every prop can be an attribute, and the live Kanban example.
- [Installation](https://bmartel.github.io/alacris-go/start/installation/): go get, serving the runtime, Config.UI, script tags, caching and the dev build.
- [Your first component](https://bmartel.github.io/alacris-go/start/first-component/): Write a component, generate its wrapper, render it from templ.
- [Upgrading](https://bmartel.github.io/alacris-go/start/upgrading/): What changed between releases. 0.2.0 moved the live session credential from the URL into a cookie.

## Guides

- [Rendering elements](https://bmartel.github.io/alacris-go/guides/rendering/): The Element API: props, attributes, classes, styles, slots, children, and Pending.
- [Props and encoding](https://bmartel.github.io/alacris-go/guides/props/): The encoding table, booleans, the safe-integer limit, attribute naming, custom types.
- [Generating wrappers](https://bmartel.github.io/alacris-go/guides/codegen/): What the generator emits, what it refuses to guess, the manifest escape hatch, naming.
- [Theming](https://bmartel.github.io/alacris-go/guides/theming/): Custom properties, VarSet contracts, @cssprop, Config.Theme, what inline CSS is refused.
- [Alacris UI](https://bmartel.github.io/alacris-go/guides/alacris-ui/): Sixty-eight Material Design 3 components, the catalog, composing chips with autocomplete, and a theme engine driven from Go.
- [Live: props from the server](https://bmartel.github.io/alacris-go/guides/live-props/): Sessions, Handle.Set, batching, broadcasting, and when SetHTML is the right tool.
- [Live: actions from the page](https://bmartel.github.io/alacris-go/guides/live-actions/): Forwarding CustomEvents to typed Go handlers, per-session handlers, error handling.
- [Sessions and reconnects](https://bmartel.github.io/alacris-go/guides/sessions/): The cookie that carries the capability, the page id that does not, OnOpen, buffering, TTL, per-page state.
- [Deploying](https://bmartel.github.io/alacris-go/guides/deploying/): Caching, CSP, proxy buffering, session affinity, shutdown.
- [Desktop apps](https://bmartel.github.io/alacris-go/guides/desktop/): Same live handler in an OS webview. Host token, no JS bindings. Nested module, `-tags desktop`.

## Reference

- [Go API](https://bmartel.github.io/alacris-go/reference/api/): Every exported type and function across the alacris, gen, live, ui, and app packages.
- [CLI](https://bmartel.github.io/alacris-go/reference/cli/): generate, check, manifest, and app init|dev|build.
- [JSDoc tags](https://bmartel.github.io/alacris-go/reference/jsdoc/): @prop, @fires, @slot, @cssprop, @goname, @goimport, and the type vocabulary.
- [Wire protocol](https://bmartel.github.io/alacris-go/reference/wire-protocol/): Endpoints, SSE frame format, the five patch operations, the action payload.
- [Security](https://bmartel.github.io/alacris-go/reference/security/): What is handled, and the three things that are yours.
- [Performance](https://bmartel.github.io/alacris-go/reference/performance/): Bytes, server cost, and why each() must sit outside conditionals.
- [Limitations](https://bmartel.github.io/alacris-go/reference/limitations/): What it will not do, and when to use something else.
- [AI agents](https://bmartel.github.io/alacris-go/reference/agents/): The drop-in AGENTS.md and how these docs stay honest.

## Optional

- [AGENTS.md](https://bmartel.github.io/alacris-go/AGENTS.md): Drop-in conventions file for coding agents.
- [Go package documentation](https://pkg.go.dev/github.com/bmartel/alacris-go): Generated API reference.
- [Source](https://github.com/bmartel/alacris-go): Repository, including the runnable live Kanban board in examples/todo.
- [alacris](https://bmartel.github.io/alacris/): The web component runtime itself. Read this for writing component internals.