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, then build a page that loads data and returns HTML. Add an interactive island when a button or form needs browser code, and an API endpoint when that interaction needs to read or change server data. The project structure 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 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.
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
brixcommand 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 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:
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:
"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:
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 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:
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 for every command.
Where to go next
#Once the first feature works, cover it with tests and choose a deployment target.
The rest of the platform is organized by the work it supports:
- Compose HTML fragments and agent-readable Markdown.
- Build interfaces with Panda themes, shared stores, browser storage, translations, and Storybook.
- Configure servers, data caching, and environment secrets.
- Integrate Contentful and OpenAPI services, with typed results.
- Own React applications, multi-application workspaces and libraries, dependency upgrades, and publishing releases.
- Look up the CLI or the complete public export inventory.