> ## Documentation Index
> Fetch the complete documentation index at: https://docs.olonjs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# OlonJS project structure: files, folders, and conventions

> Understand the file and folder layout of an OlonJS Next.js project, where data lives, how sections are organized, and what each directory does.

An OlonJS project follows a predictable structure. Understanding where pages, collections, sections, and configuration files live helps you navigate and extend the project confidently — whether you are adding a new section component, authoring a collection, or wiring up a custom API route.

```text theme={null}
.
├── app/                        # Next.js App Router pages
│   ├── [[...slug]]/page.tsx    # Visitor-facing catch-all route
│   ├── admin/[[...slug]]/      # Studio admin route
│   └── api/                    # API routes (save-to-file, upload-asset, etc.)
├── public/
│   ├── pages/                  # Baked page JSON bundles
│   ├── collections/            # Baked collection data
│   ├── schemas/                # JSON Schema contracts per page
│   ├── config/                 # Baked site configuration (site.json)
│   ├── mcp-manifests/          # Per-page MCP manifests
│   ├── mcp-manifest.json       # Master MCP index
│   ├── sitemap.xml             # Generated sitemap
│   ├── robots.txt              # Generated robots.txt
│   └── llms.txt                # Plain-text content index for LLMs
├── src/
│   ├── collections/            # Collection schemas and types
│   │   ├── posts/              # PostSchema, PostsCollectionSchema
│   │   └── tags/               # TagSchema, TagsCollectionSchema
│   ├── components/             # Section components
│   │   ├── hero/               # Hero section (View, schema, types)
│   │   ├── posts-list/         # PostsList section
│   │   └── ...                 # Other section components
│   ├── data/
│   │   ├── pages/              # Page data JSON files
│   │   ├── collections/        # Collection data JSON files
│   │   └── config/             # site.json, theme.json, menu.json
│   └── lib/
│       ├── CollectionRegistry.ts
│       ├── ComponentRegistry.tsx
│       └── schemas.ts          # SECTION_SCHEMAS export
├── scripts/                    # Prebuild scripts (sync, bake, sitemap, etc.)
└── package.json
```

## Data directory (`src/data/`)

`src/data/` is the single source of truth for all content in an OlonJS project. Nothing here is generated — every file is human-editable and version-controllable.

* **`src/data/pages/`** — one JSON file per page (for example, `home.json`, `about.json`, `blog.json`). Each file declares the page's slug, metadata, and an ordered array of sections with their typed data payloads.
* **`src/data/collections/`** — one JSON file per collection (for example, `posts.json`, `tags.json`). Each file is an array of items validated against the collection's Zod schema.
* **`src/data/config/`** — site-wide configuration files: `site.json` (name, description, base URL), `theme.json` (colour tokens, font settings), and `menu.json` (navigation structure).

When you edit content in Studio, the changes are written back to the appropriate file in `src/data/` via the `/api/save-to-file` route.

## Public directory (`public/`)

The `public/` directory is **generated** — never edit its contents by hand.

During the prebuild step (which runs automatically before `npm run build`), OlonJS bakes everything in `src/data/` into static files under `public/`:

* **`public/pages/`** — fully resolved page bundles, including all collection relations. These are what the visitor-facing catch-all route reads at request time.
* **`public/collections/`** — collection data as static JSON endpoints, served with zero latency.
* **`public/schemas/`** — JSON Schema files derived from your Zod schemas, one per page. Used by Studio and external tooling to validate content.
* **`public/config/`** — a copy of `site.json` for use by the static client without an API round-trip.
* **`public/mcp-manifests/`** — per-page MCP manifest files that describe each page's schema to AI agents.
* **`public/mcp-manifest.json`** — the master MCP index listing all pages and their manifest URLs.
* **`public/sitemap.xml`** and **`public/robots.txt`** — generated from your page index and site configuration.
* **`public/llms.txt`** — a plain-text summary of your site's content for large language model consumption.

<Warning>
  Never edit files inside `public/pages/`, `public/collections/`, or `public/schemas/` directly. They are overwritten on every build. Make all content changes in `src/data/` instead.
</Warning>

## Section components (`src/components/`)

Each section type lives in its own folder under `src/components/`. A complete section folder contains four files:

| File | Purpose |
| - | - |
| `View.tsx` | The React server component that renders the section |
| `schema.ts` | The Zod schema that validates the section's data payload |
| `types.ts` | TypeScript types inferred from the Zod schema |
| `index.ts` | Barrel export re-exporting `View`, the schema, and the types |

The `ComponentRegistry.tsx` in `src/lib/` maps each section's `type` string (for example, `"hero"`) to its `View` component. The `schemas.ts` file exports a `SECTION_SCHEMAS` record that maps the same type strings to their Zod schemas — this is what the prebuild step and Studio use to validate and introspect section data.

To add a new section, create its folder under `src/components/`, register it in both `ComponentRegistry.tsx` and `SECTION_SCHEMAS`, then use its `type` string in any page JSON file.

## Build scripts

OlonJS ships a set of prebuild scripts in the `scripts/` directory that run automatically before every `npm run build`, in the following order:

* **`sync-pages-to-public`** — mirrors `src/data/pages/`, `src/data/collections/`, and `src/data/config/site.json` into `public/` so the static file server can read them without an API round-trip.
* **`generate-llms-txt`** — produces `public/llms.txt`, a plain-text summary of your site's content for large language model consumption.
* **`bake`** — resolves all cross-collection relations, validates all schemas, writes fully hydrated page and collection bundles to `public/`, and generates per-page MCP manifests and the master `public/mcp-manifest.json`.
* **`sitemap`** — reads the page index and generates `public/sitemap.xml`.
* **`robots`** — generates `public/robots.txt` based on your site configuration.

You can also run the prebuild step in isolation with `npm run prebuild` during development if you need to refresh the baked data without starting a full Next.js build.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.