Skip to content
brix.v2.15.0+b120c49

Search documentation

Loading search…

    Documentation menu
    Docs / Getting startedRead Markdown
    On this page

    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 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 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: