# Brix documentation

> Brix 2: typed contracts, Hono servers, Preact islands, and managed workflows.

## Getting started

- [Introduction](/docs/introduction.md): One platform. A stack that works together.
- [Installation](/docs/installation.md): From an empty directory to a running application.
- [Project structure](/docs/project-structure.md): A place for every part of your application.
- [Application types](/docs/react.md): Choose full-stack Preact, managed React, or an external application host.
- [Managed React](/docs/react-managed.md): Build browser-only React SPAs and Contentful Apps.
- [External hosts](/docs/react-external.md): Add Brix bindings without replacing an existing build system.

## Pages and UI

- [Pages & routing](/docs/pages.md): Server-rendered pages with typed URLs and loaders.
- [Interactive islands](/docs/islands.md): HTML first. JavaScript where it matters.
- [HTML fragments](/docs/fragments.md): Compose independent HTML endpoints and edge-cached page shells.
- [Author fragments](/docs/fragments-authoring.md): Define fragment components, sidecars, and endpoint inputs.
- [Composition and testing](/docs/fragments-composition.md): Compose cached HTML at the edge and test transport.
- [Agent-readable Markdown](/docs/markdown.md): Semantic documents, durable Markdown URLs, and llms.txt indexes.
- [Semantic pages](/docs/markdown-pages.md): Author documents and serve localized Markdown representations.
- [Indexes and caching](/docs/markdown-indexes.md): Publish llms.txt and test representation-aware caching.
- [Panda styling](/docs/styling.md): Typed styling, semantic themes, recipes, and incremental CSS.
- [Theme and tokens](/docs/styling-theme.md): Configure semantic tokens, breakpoints, and global styles.
- [Component styling](/docs/styling-components.md): Use recipes, slots, patterns, and static extraction.
- [Shared stores](/docs/stores.md): Request-safe state shared across independently hydrated islands.
- [Browser storage](/docs/storage.md): Validated local and session storage with reactive bindings.
- [Keys and bindings](/docs/storage-bindings.md): Bind validated browser storage to components.
- [Helpers and validation](/docs/storage-helpers.md): Read, write, and test storage outside components.
- [Translations](/docs/translations.md): Typed messages across SSR, islands, fragments, and caches.
- [Contracts and loaders](/docs/translations-setup.md): Configure locales, messages, and dictionary loading.
- [Rendering and testing](/docs/translations-usage.md): Translate components and Markdown with safe cache boundaries.

## APIs and data

- [API contracts](/docs/api-routes.md): Define once. Validate and consume everywhere.
- [Contracts and handlers](/docs/api-routes-server.md): Define typed contracts and implement server routes.
- [Clients and hooks](/docs/api-routes-clients.md): Call APIs with shared transport, retries, caching, and typed failures.
- [Data caching](/docs/caching.md): Shared GET results, explicit scopes, invalidation, and DynamoDB.
- [Policies and scopes](/docs/caching-policies.md): Choose eligible reads, private partitions, freshness, and fallback.
- [Invalidation](/docs/caching-invalidation.md): Invalidate contracts and tags and understand local observers.
- [Stores and edge hints](/docs/caching-stores.md): Use DynamoDB or Fastly KV and distinguish route caching.
- [Typed results](/docs/results.md): Model expected failures and compose synchronous and async results.
- [Synchronous results](/docs/results-synchronous.md): Model tagged failures and match, transform, and chain results.
- [Async composition](/docs/results-async.md): Consume and adapt fluent ResultPromise operations.
- [OpenAPI generation](/docs/openapi.md): Generate typed contracts from specifications with drift checks.

## Contentful

- [Contentful](/docs/contentful.md): Typed CMS clients, semantic renderers, and signed webhooks.
- [Type generation](/docs/contentful-typegen.md): Generate model types and use resource guards.
- [Delivery and Management clients](/docs/contentful-client.md): Query entries, resolve links, cache reads, and synchronize content.
- [Adapters and Rich Text](/docs/contentful-rendering.md): Render CMS entries as components and semantic Markdown.
- [Live Preview](/docs/contentful-preview.md): Configure protected previews and inspector mode.
- [Webhooks](/docs/contentful-webhooks.md): Verify signatures and invalidate delivery caches.
- [Apps and uploads](/docs/contentful-apps.md): Build React App SDK and Forma 36 interfaces and upload bundles.

## Server and deployment

- [Server configuration](/docs/server.md): Authentication, middleware, CSP, assets, and observability.
- [Server setup](/docs/server-foundations.md): Assemble the server and connect cache and deployment configuration.
- [Authentication and security](/docs/server-auth-security.md): Protect routes and configure security headers and CSP.
- [Middleware and observability](/docs/server-runtime.md): Configure app state, errors, request IDs, and telemetry.
- [Environment and secrets](/docs/environment.md): Varlock schemas, generated types, 1Password, and AWS snapshots.
- [Schemas and types](/docs/environment-schema.md): Author Varlock schemas and consume validated environment types.
- [Loading and testing](/docs/environment-loading.md): Select stage, local, workspace, and script environments.
- [Secrets and snapshots](/docs/environment-secrets.md): Resolve 1Password references and upload immutable AWS snapshots.
- [Deployment](/docs/deployment.md): Build and run your production application.
- [Builds and environment](/docs/deployment-runtime.md): Understand platform output and production runtime configuration.
- [Node and AWS Lambda](/docs/deployment-node-aws.md): Run the generated Node server or native Lambda handler.
- [Cloudflare and Fastly](/docs/deployment-workers.md): Deploy bundled worker graphs and configure provider bindings.

## Project tooling

- [Storybook](/docs/storybook.md): Component catalogs with interaction and accessibility tests.
- [Stories and interactions](/docs/storybook-stories.md): Author accessible, translated, themed component stories.
- [Catalog ownership](/docs/storybook-catalogs.md): Configure application, library, and workspace catalogs.
- [Workspaces and libraries](/docs/workspaces.md): Shared packages, independent applications, and one managed toolchain.
- [Architecture and libraries](/docs/workspaces-libraries.md): Create members, share contracts, and inherit root policy.
- [Commands and deployment](/docs/workspaces-workflows.md): Run root or focused workflows and deploy independently.
- [External applications](/docs/workspaces-external.md): Adopt external hosts and configure cross-origin requests.
- [Testing](/docs/testing.md): Exercise real routes and browser interactions.
- [Routes and server behavior](/docs/testing-routes.md): Test pages, APIs, fragments, auth, and environment through the harness.
- [Components and HTTP consumers](/docs/testing-components.md): Render browser components and mock consumed HTTP with MSW.
- [E2E and hydration benchmarks](/docs/testing-e2e.md): Test complete applications and compare production hydration.
- [Dependency and Brix upgrades](/docs/releases-upgrades.md): Review release histories and apply transactional updates.
- [Publishing releases](/docs/releases-publishing.md): Configure versioning and hand exact releases to GitHub Actions.
- [Linting and formatting](/docs/linting-formatting.md): Managed rules, scoped exceptions, and workspace-root tool policy.

## Reference

- [CLI reference](/docs/cli.md): Project creation, generators, inspection, and lifecycle commands.
- [Public API reference](/docs/api-reference.md): Every public package entry point with its exported values and types.