> For the complete documentation index, see [llms.txt](https://docs.fritesai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fritesai.com/development/local-development.md).

# Local development

This page covers working in the frites repository itself: prerequisites, the root scripts, and the build order. For the monorepo layout, see [repository-structure.md](/development/repository-structure.md).

## Prerequisites

* **Node.js >= 22** (`engines.node` in the root `package.json`).
* **pnpm 10.24.0**: the repo pins `packageManager: "pnpm@10.24.0"`, so use Corepack or install that version.

Install dependencies from the repo root:

```bash
pnpm install
```

Only `esbuild` is allowed to run a postinstall build (`pnpm.onlyBuiltDependencies`), keeping installs deterministic.

## Root scripts

All scripts are defined in the root `package.json` and run from the repo root.

| Script       | Command           | What it does                                                                                                 |
| ------------ | ----------------- | ------------------------------------------------------------------------------------------------------------ |
| `build`      | `pnpm build`      | Builds the publishable packages in dependency order (see below).                                             |
| `clean`      | `pnpm clean`      | Removes every `dist/` and `*.tsbuildinfo` under `apps/*` and `packages/*`.                                   |
| `prepack`    | runs `pnpm build` | Lifecycle hook so a publish always ships fresh `dist/`.                                                      |
| `typecheck`  | `pnpm typecheck`  | `tsc --noEmit` across the whole workspace (no emit; see [testing.md](/development/testing.md)).              |
| `test`       | `pnpm test`       | `vitest run`: the unit suite. See [testing.md](/development/testing.md).                                     |
| `test:watch` | `pnpm test:watch` | `vitest` in watch mode.                                                                                      |
| `gateway`    | `pnpm gateway`    | Runs the gateway from source via `tsx apps/gateway/src/index.ts`.                                            |
| `mcp`        | `pnpm mcp`        | Runs the MCP server from source via `tsx apps/mcp/src/index.ts`.                                             |
| `frites`     | `pnpm frites`     | Runs the CLI from source via `tsx apps/cli/src/index.ts`.                                                    |
| `eval`       | `pnpm eval`       | Runs the value-gate harness (`tsx eval/value-gate.ts`). See [evaluation.md](/development/evaluation.md).     |
| `bench`      | `pnpm bench`      | Runs the bench-matrix harness (`tsx eval/bench-matrix.ts`). See [evaluation.md](/development/evaluation.md). |

The `gateway`, `mcp`, `frites`, `eval`, and `bench` scripts all run TypeScript directly with [`tsx`](https://github.com/privatenumber/tsx). No build step is required to run a surface locally.

## Build order

`pnpm build` compiles only the five publishable packages, and it does so in a fixed order so each package's dependencies are built before it:

```
core → agents → isolation → gateway → cli
```

```json
"build": "pnpm --filter @frites/core build && pnpm --filter @frites/agents build && pnpm --filter @frites/isolation build && pnpm --filter @frites/gateway build && pnpm --filter @frites/cli build"
```

Each package's own `build` script is `tsc -p tsconfig.build.json`, which emits `dist/` (declarations + source maps) from `src/`.

`@frites/mcp` is **not** in the build chain: it is private and runs straight from TypeScript via `tsx` (the `mcp` script), so it has no `dist/`. See [release-and-packaging.md](/development/release-and-packaging.md) for the full publish/build distinction.

## Config files used in development

| File                        | Purpose                                                                                                                                                                        |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `pnpm-workspace.yaml`       | Declares the `apps/*` and `packages/*` workspace globs.                                                                                                                        |
| `tsconfig.json`             | Root TS config (`noEmit`, strict, ES2023/ESNext, Bundler resolution) plus `paths` aliases for `@frites/core`, `@frites/isolation`, `@frites/agents`. Used by `pnpm typecheck`. |
| `<pkg>/tsconfig.build.json` | Per-package build config extending the root; flips `noEmit` off, emits declarations + source maps into `dist/`, and excludes `test/`.                                          |
| `vitest.config.ts`          | Test runner config: Node environment, include globs for `packages/*/test` + `apps/*/test`, and the same `@frites/*` source aliases.                                            |

The `@frites/*` path aliases in both `tsconfig.json` and `vitest.config.ts` point at each package's `src/index.ts`, so typecheck and tests resolve workspace packages from source, and you do not need to build before running `pnpm typecheck` or `pnpm test`.

## Runtime configuration

frites itself reads `.frites/config.json` in the repo, layered over `~/.frites/config.json` (global). That is application configuration, not build tooling. Manage it with `frites config` and see [reference/configuration.md](/reference/configuration.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.fritesai.com/development/local-development.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.