Architecture Overview

Relevant source files

The following files were used as context for generating this wiki page:

• ARCHITECTURE.md
• AGENTS.md
• README.md
• packages/farm/src/tests/docs-handler.test.ts
• packages/create-farm-app/src/index.ts
• CONTRIBUTING.md

Farm.js is a full-stack framework designed for building product-integrated applications. It leverages Vite for development, Nitro for production deployment, and supports React Server Components (RSC) with streaming SSR as its default rendering model. The framework is built as a monorepo, providing a unified developer experience across routing, rendering, and third-party integrations.

Sources: ARCHITECTURE.md:7-10, AGENTS.md:3-6, README.md:9-12

Core Monorepo Structure

The project organizes its functionality into distinct packages within the packages/ directory to maintain clear boundaries between the core framework, CLI tools, and renderers.

Package Responsibilities

Package	Purpose	Key Components
packages/farm	Core Framework (@farm.js/core)	Routing, Server Rendering, Client Runtime, Vite Plugin
packages/farm-cli	Command Line Interface (@farm.js/cli)	farm dev, farm build, Scaffolding
packages/create-farm-app	Project Generator	Templates, Interactive Setup
packages/farm-react	React Renderer	RSC Support, AOT Compiler
packages/farm-content	Content Management	Markdown/MDX Loading, Assets

Sources: ARCHITECTURE.md:25-50, AGENTS.md:46-60, CONTRIBUTING.md:25-33

System Architecture

The high-level architecture connects the developer experience to the build system and production runtime through a series of internal managers and plugins.

Request Lifecycle

Farm.js handles requests differently depending on whether the environment is in development or production.

Development Flow

1. Interception: The Vite dev server receives the request; Vite middleware intercepts non-asset requests.
2. Matching: The Route Manager matches the URL to file-based routes (e.g., page.tsx).
3. Rendering: The Server Renderer loads and renders React Server Components.
4. Streaming: HTML is streamed to the client along with the RSC payload.
5. Hydration: The Client Runtime hydrates the application for interactivity.

Sources: ARCHITECTURE.md:76-83

Production Flow

1. Optimization: The build process generates optimized bundles using Vite and Nitro.
2. Discovery: Static analysis identifies all routes and dependencies.
3. Serving: The production runtime serves pre-built or dynamically rendered pages via Nitro-backed deployment targets.

Sources: ARCHITECTURE.md:85-91, AGENTS.md:3-6

Routing Logic

The Route Manager implementation in packages/farm/src/routing/ follows file-based routing semantics similar to the Next.js App Router. It supports page.tsx, layout.tsx, and dynamic segments.

Feature Implementation: Documentation Engine

Farm.js includes a built-in documentation handler capable of serving Markdown and MDX content with specialized features like social image generation and search.

• Docs Handler: Routes enabled documentation trees through getFarmDocsDocumentNavigationMatchers.
• Social Images: Renders versioned social images with cache validators (e.g., opengraph-image.svg?v=...).
• Security: Implements Content Security Policy (CSP) nonces and static hashes for script tags within documentation pages.

Sources: packages/farm/src/tests/docs-handler.test.ts:24-40, packages/farm/src/tests/docs-handler.test.ts:316-330, packages/farm/src/tests/docs-handler.test.ts:586-597

Design Principles

The architecture adheres to several core "Product Contracts" and maintainer preferences:

• Fast Feedback: Development transforms and HMR must remain lightweight.
• Predictable Boundaries: Server secrets and code must remain isolated from the client.
• Typed Conventions: APIs and route behavior must fail at build or type-check time if inconsistent.
• Web-platform Semantics: Use native Request, Response, and URL objects instead of framework-specific substitutes.

Sources: AGENTS.md:12-30

Project Scaffolding

The create-farm-app package manages project initialization. It supports various templates and allows users to select different renderers during the interactive setup.

// Example of template detail structure used for scaffolding
const templateDetails: Record<string, TemplateDetails> = {
  basic: {
    title: "Basic starter",
    description: "A minimal Farm.js app with built-in Tailwind support",
    instructions: ["Tailwind is enabled by default."],
  },
  ai: integrationTemplate({
    title: "AI starter",
    provider: "ai",
    route: "/integrations/ai",
  })
};

Sources: packages/create-farm-app/src/index.ts:33-40, packages/create-farm-app/src/index.ts:77-83

Summary

The Farm.js architecture centralizes framework contracts in @farm.js/core to ensure consistency across the CLI, renderers, and integrations. By leveraging Vite for its development server and Nitro for its production runtime, the framework provides high-performance full-stack capabilities with a focus on type safety and React Server Components.