Content Management (CMS)
Relevant source files
The following files were used as context for generating this wiki page:
Content Management in Farm.js enables you to manage typed content collections from local files or remote providers. The system provides a unified pipeline for loading, validating, and transforming content into server modules that are accessible within the application.
Content Collections Architecture
Farm.js organizes content into Collections. Each collection defines a source (local files or remote APIs), a validation schema, and optional transformation logic. The loader processes these collections during the build or development phase to generate stable, typed data structures.
The diagram shows the sequence from raw source ingestion to the generation of the server-side content module.
Sources: packages/farm-content/src/loader.test.ts:55-75, packages/farm-content/src/loader.test.ts:167-175
Core Components
| Component | Description |
|---|---|
collection() | Defines the configuration for a content group, including source and schema. |
files() | A local source driver that matches files using glob patterns. |
remote() | A driver for "Bring Your Own CMS" scenarios, using fetch-based callbacks. |
loadContentCollections | The main orchestration function that iterates through collections and processes entries. |
writeContentServerModule | Generates the final .mjs module containing the processed content. |
Sources: packages/farm-content/src/loader.test.ts:55-75, packages/farm-content/src/byo-source.test.ts:47-65
Local Content Processing
The system processes local Markdown (.md), MDX (.mdx), and JSON files found within the project structure.
Frontmatter Handling
Farm.js supports YAML and JSON frontmatter blocks. It strictly rejects executable language aliases (like javascript or js) within frontmatter delimiters to ensure security and predictability.
- YAML: Supports standard keys, including dates and arrays.
- JSON: Supported when the
---jsondelimiter is used. - Security: Frontmatter containing logic or symbol keys is rejected during serialization.
Sources: packages/farm-content/src/frontmatter.test.ts:28-48, packages/farm-content/src/loader.test.ts:145-155, packages/farm/src/app-markdown-runtime.ts:63-95
Asset Management
When content references local assets (e.g., ./hero.svg), the CMS loader automatically resolves them.
- It validates the existence of the asset.
- It detects image dimensions for supported formats.
- It transforms local paths in the content body into generated internal asset markers (e.g.,
__FARM_CONTENT_ASSET_). - It emits hashed URL imports in the final server module.
Sources: packages/farm-content/src/loader.test.ts:193-245, packages/farm-content/src/loader.test.ts:333-350
Remote CMS Integration
Farm.js allows integration with external CMS providers (like Sanity or WordPress) using the remote() source driver. This implementation requires two primary callbacks:
fetch: Retrieves data from the external API and maps it to a standard entry format (ID, data, and optional body).update: (Optional) Handles mutations, allowing the application to write back to the CMS using typed patches.
The sequence shows how a mutation initiated in the Farm.js runtime is propagated to a remote provider via the update callback.
Sources: packages/farm-content/src/byo-source.test.ts:55-70, packages/farm-content/src/byo-source.test.ts:129-138
Documentation (Docs) System
A specialized implementation of the CMS is used for the framework's documentation engine. It provides advanced features for rendering structured technical content.
Features and Configuration
The docs engine utilizes a specific handler created via createFarmDocsHandler and is configured through resolveDocsConfig.
- Navigation: Generates sidebars with support for folders, icons, and labels.
- Table of Contents (TOC): Automatically extracts headings while omitting those inside code fences.
- Social Images: Generates versioned OpenGraph images (
opengraph-image.svg) with cache validators based on page content. - Last Modified: Prioritizes Git commit history over filesystem timestamps to determine the "Last updated" date.
Sources: packages/farm/src/tests/docs-handler.test.ts:108-145, packages/farm/src/tests/docs-handler.test.ts:175-195, packages/farm/src/tests/docs-handler.test.ts:400-435
Agent Discovery
The CMS exposes discovery routes to allow AI agents to navigate content efficiently:
llms.txt: A structured index of documentation pages.AGENTS.md: Specific instructions for AI agents..well-known/agent.json: A capability manifest for discovery.
Sources: packages/farm/src/tests/docs-handler.test.ts:535-560, packages/farm/src/tests/llms-txt.test.ts:10-40
Validation and Serialization
Content data is subject to strict serialization rules to ensure it can be safely transferred between server and client boundaries.
- Supported Types: Dates, BigInts, and null-prototype objects.
- Prohibited Types: Getters, setters, symbol keys, circular references, and sparse arrays.
- Schema Enforcement: Validation errors include the collection name, file path, and specific line/column numbers for body assets.
Sources: packages/farm-content/src/loader.test.ts:133-165, packages/farm-content/src/loader.test.ts:316-328