Skip to main content
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.

​
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.
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.

​
Section components (src/components/)

Each section type lives in its own folder under src/components/. A complete section folder contains four files: 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.