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

# 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

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

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

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

```

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

```ts
"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:

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

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

```

## Imports and boundaries

Generated applications provide aliases for deliberate boundaries:

```ts
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](/docs/linting-formatting) for managed defaults and configuration.

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

```ts
import { defineBrixConfig } from "brix/vite";

export default defineBrixConfig();

```

Use `brix check` to validate structure, imports, exports, formatting, lint, and types. Continue with [pages](/docs/pages), [API routes](/docs/api-routes), and [islands](/docs/islands).