> [Agent navigation index](/llms.txt)

# Introduction

Brix is an opinionated web platform for server-rendered Hono and Preact applications. It combines typed routes, selective hydration, testing, and project workflows behind one pinned `brix` command.

## Build your first feature

Start with [installation](/docs/installation.md), then build a [page](/docs/pages.md) that loads data and
returns HTML. Add an [interactive island](/docs/islands.md) when a button or form needs browser code,
and an [API endpoint](/docs/api-routes-server.md) when that interaction needs to read or change server
data. The [project structure](/docs/project-structure.md) guide explains where those files belong.

If you are bringing an existing React frontend rather than building a server-rendered Preact
application, start with [application types](/docs/react.md) instead.

## Release status

Brix 2 is stable and distributed from a private Git repository. New projects use the stable channel
by default and record the resolved exact version; they do not follow the channel afterward. Review
release changes before [upgrading that pin](/docs/releases-upgrades.md).

Every developer and CI job needs Git and SSH access to the private Brix repository. The installer
uses the caller's SSH identity; it does not make the framework public.

## What Brix provides

A full-stack Brix application combines:

- Hono application infrastructure and server-side rendering
- Preact components with opt-in interactive islands
- typed page and API contracts shared across boundaries
- route discovery from conventional feature directories
- managed Vite, Vitest, Playwright, Storybook, Oxfmt, Oxlint, TypeScript, and Panda CSS
- a project-pinned `brix` command for development through deployment

Brix also supports libraries, UI libraries, workspaces, and browser-only React applications. The SSR
pages, islands, fragments, and server features described in these docs use the full-stack Hono and
Preact application type; see [application types](/docs/react.md) for the React alternatives.

## The application boundary

A generated application keeps framework wiring in three small files. Browser-safe contract and URL
factories live in `src/brix.ts`, which components, islands, and contracts import as `#brix`:

```ts
import { defineBrix } from "brix/contracts";

export const brix = defineBrix();
export const { createApiContract, createPageContract, executeApi, getPath } = brix;

```

Server-only route factories and integrations live in `src/brix.server.ts`, imported as
`#brix/server`. The `"use server"` directive makes any browser import of this module fail the build:

```ts
"use server";

import { defineBrixServer } from "brix/server";
import { brix } from "./brix.ts";
import { env } from "./env.server.ts";

export const brixServer = defineBrixServer(brix, { env });
export const { createApiRoute, createFragment, createPageRoute } = brixServer;

```

The application entry, `src/app.ts`, delegates infrastructure to Brix:

```ts
import { createBrixApp } from "brix/server";
import { brixServer } from "./brix.server.ts";

export const app = createBrixApp(brixServer);

```

`createBrixApp` owns route assembly, SSR, assets, request IDs, security headers, cross-origin
mutation protection, request-body limits, and default error handling. Feature modules define
contracts, routes, components, and tests rather than rebuilding that infrastructure.

These are excerpts showing the three boundaries, not replacement files for a generated project.
Keep its complete factory exports; [project structure](/docs/project-structure.md) shows that setup. During development and production builds, Brix discovers feature routes and
assembles them around the application entry, so you do not maintain a route-registration barrel.

## The normal workflow

Use Brix commands rather than invoking its underlying tools directly:

```sh
brix dev    # development server with hot reloading
brix check  # formatting, lint, types, and project structure
brix test   # unit, route, and browser tests
brix build  # production output for the configured platform

```

The project records one exact Brix version. Normal commands execute that installed version, keeping
the framework and toolchain aligned. Use `brix add page|api|response|fragment|island|store` to
generate correctly shaped feature files; see the [CLI reference](/docs/cli.md) for every command.

## Where to go next

Once the first feature works, cover it with [tests](/docs/testing.md) and choose a
[deployment target](/docs/deployment.md).

The rest of the platform is organized by the work it supports:

- Compose [HTML fragments](/docs/fragments.md) and [agent-readable Markdown](/docs/markdown.md).
- Build interfaces with [Panda themes](/docs/styling.md), [shared stores](/docs/stores.md),
  [browser storage](/docs/storage.md), [translations](/docs/translations.md), and [Storybook](/docs/storybook.md).
- Configure [servers](/docs/server.md), [data caching](/docs/caching.md), and [environment secrets](/docs/environment.md).
- Integrate [Contentful](/docs/contentful.md) and [OpenAPI services](/docs/openapi.md), with [typed results](/docs/results.md).
- Own [React applications](/docs/react.md), [multi-application workspaces and libraries](/docs/workspaces.md),
  [dependency upgrades](/docs/releases-upgrades.md), and [publishing releases](/docs/releases-publishing.md).
- Look up the [CLI](/docs/cli.md) or the complete [public export inventory](/docs/api-reference.md).
