Project Structure

Brix applications organize product code by feature while reserving a few top-level files for browser-safe and server-only framework wiring.

A typical application

src/
  app.ts
  brix.ts
  brix.server.ts
  env.server.ts
  test/
    harness.ts
  features/
    booking/
      api/
        fetchBooking/
          contract.ts
          route.ts
          route.test.ts
      pages/
        bookingDetails/
          contract.ts
          Page.tsx
          route.ts
          route.test.ts
      components/
        BookingCard.tsx
      BookingActions.tsx
vite.config.ts
package.json

Keep tests beside the code they exercise. Features can also contain stores, schemas, and domain modules in descriptive local directories.

Framework wiring

src/brix.ts is browser-safe and defines project-bound contract and URL factories:

import { defineBrix } from "brix/contracts";

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

src/brix.server.ts is the server boundary:

"use server";

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

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

src/app.ts should stay infrastructure-only:

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

export const app = createBrixApp(brixServer);

Feature route conventions

Brix discovers page routes at src/features/<feature>/pages/<name>/route.ts and API routes at src/features/<feature>/api/<name>/route.ts.

Each route module exports exactly one runtime value named *PageRoute or *ApiRoute. Page component modules export exactly one named runtime component ending in Page. Type-only exports are allowed.

Generate a correctly shaped slice instead of assembling it by hand:

brix add page bookingDetails --feature booking
brix add api fetchBooking --feature booking

Imports and boundaries

Generated applications provide aliases for deliberate boundaries:

import { createPageContract } from "#brix";
import { createPageRoute } from "#brix/server";
import { testPage } from "#brix/test";
import { BookingCard } from "#/features/booking/components/BookingCard.tsx";

Use ./ within one directory and #/ across feature directories. Do not import server modules into browser-safe contracts or islands. Import framework-owned dependencies through Brix facades such as brix/zod and brix/hooks.

Managed Panda styling

Brix enables Panda CSS by default. Import generated utilities from #brix/panda/css and define an optional named theme export in src/theme.ts with defineBrixTheme from brix/panda. Brix owns extraction, generated utility types, and stylesheet injection; do not add a separate Panda config or PostCSS setup.

During development, source edits re-extract only changed files. Unchanged styles do not rewrite CSS or regenerate utility types. Added and deleted files update the stylesheet, while theme changes rebuild the styling context and utilities, including changes to imported theme dependencies outside src/.

Island edits use Preact Fast Refresh and preserve compatible hook state. Changes to server-rendered pages or routes outside an island boundary intentionally reload the page. Production builds still extract the complete application stylesheet.

Tool configuration

Standalone projects own .node-version, oxfmt.config.mts, and oxlint.config.mts. Workspace members inherit those files and Git hooks from the workspace root; do not copy generated defaults into every member. Prefer root-relative overrides for member-specific formatting or lint policy. See linting and formatting for managed defaults and configuration.

The generated vite.config.ts composes the supported application build:

import { defineBrixConfig } from "brix/vite";

export default defineBrixConfig();

Use brix check to validate structure, imports, exports, formatting, lint, and types. Continue with pages, API routes, and islands.