Farm.js Docs

The framework for the web and agents.

Every Farm.js app serves its pages to people and to AI agents: server-rendered HTML, a Markdown copy of each page, and llms.txt, on by default. Turn on MCP and your server functions become tools agents can call. Bring any agent runtime: Eve and Cloudflare Agents plug in through Farm's open agent runtime contract, and the AI SDK, Mastra, LangGraph, and the OpenAI Agents SDK run in a plain API route. Built on Vite and Nitro, with typed routes, Server Actions, and streaming SSR. React is the default renderer, and beta Preact, Solid, Vue, and Svelte adapters use the same routing and server contracts. See Stability and Support for what 0.1 covers.

Documentation · Examples · Quick Start

✨ Built for Full-Stack Products

Experimental native rendering: Farm.js can automatically send eligible, server-only React subtrees through the Strata native renderer while safely falling back to normal React rendering for unsupported trees.

🚀 Quick Start

Try It in Your Browser

No install needed: open the playground on StackBlitz to see server rendering, client islands, and typed server calls in one page.

Create a New App

pnpm create @farm.js/app my-app --template basic --typescript
cd my-app
pnpm dev

Your app will be running at http://localhost:3000!

Use --list-templates to choose a ready-to-configure Auth0, Auth.js, Autumn, Clerk, Inngest, Trigger.dev, Polar, Resend, Stripe, Supabase, Unkey, WorkOS, or AI starter.

Manual Installation

npm install @farm.js/core react react-dom
# or
pnpm add @farm.js/core react react-dom
# or
yarn add @farm.js/core react react-dom

Create a farm.config.ts:

import { defineConfig } from "@farm.js/core";

export default defineConfig({
  deploy: {
    target: "vercel",
  },
});

Farm uses src as the source directory by default. Add srcDir only when your app uses a different directory.

defineFarmConfig remains available as a deprecated exact alias of defineConfig.

Create your first page in src/app/page.tsx:

export default function HomePage() {
  return (
    <div className="min-h-screen bg-gray-50 flex items-center justify-center">
      <h1 className="text-5xl font-bold text-blue-600">Hello from Farm.js!</h1>
    </div>
  );
}

💡 Tailwind CSS is pre-configured! Apps from create-app include it, so just use Tailwind classes. In an existing app, install tailwindcss and @tailwindcss/vite and add @import "tailwindcss"; to your stylesheet; Farm loads the Vite plugin for you.

Add a root layout in src/app/layout.tsx:

import type { LayoutProps } from "@farm.js/core";

export default function RootLayout({ children }: LayoutProps) {
  return (
    <html>
      <body>{children}</body>
    </html>
  );
}

Start the development server:

npx farm dev

📁 Project Structure

my-farm-app/
├── src/
│   └── app/
│       ├── layout.tsx          # Root layout
│       ├── page.tsx            # Home page (/)
│       ├── about/
│       │   └── page.tsx        # About page (/about)
│       └── users/
│           ├── page.tsx        # Users list (/users)
│           └── [id]/
│               └── page.tsx    # User profile (/users/123)
├── farm.config.ts
└── package.json

⚙️ Configuration

Farm.js supports a powerful configuration system via farm.config.ts:

import { defineConfig } from "@farm.js/core";

export default defineConfig({
  experimental: {
    serverComponents: true,
  },

  // Routing
  async redirects() {
    return [{ source: "/old", destination: "/new", permanent: true }];
  },

  // Custom headers
  async headers() {
    return [
      {
        source: "/:path*",
        headers: [{ key: "X-Frame-Options", value: "DENY" }],
      },
    ];
  },

  // Environment variables
  env: {
    API_URL: "https://api.example.com",
  },

  // Plugins
  plugins: [
    /* your plugins */
  ],

  // And much more...
});

See the configuration docs for all options.

Route-level Boundaries

Farm.js supports Next.js-style route boundaries with special files inside a route segment:

• loading.tsx - Route-level loading UI shown while the segment is suspended
• error.tsx - Route-level error UI shown when the segment throws during render

Example structure:

src/app/
  layout.tsx
  page.tsx
  loading.tsx
  error.tsx
  dashboard/
    page.tsx
    loading.tsx
    error.tsx

Required config:

import { defineConfig } from "@farm.js/core";

export default defineConfig({
  experimental: {
    serverComponents: true,
  },
});

How it works:

• loading.tsx is used automatically as the Suspense fallback for that segment
• error.tsx is used automatically as the error boundary for that segment
• You do not need to import or conditionally render loading.tsx in page.tsx
• The route must actually suspend to show loading.tsx (for example: async server component, async layout, or a child wrapped by Suspense)
• loading.tsx and error.tsx do not need 'use client' unless they use client-only features like hooks or browser APIs

Example:

// src/app/dashboard/loading.tsx
export default function Loading() {
  return <p>Loading dashboard...</p>;
}

// src/app/dashboard/page.tsx
async function SlowContent() {
  await new Promise((resolve) => setTimeout(resolve, 2000));
  return <div>Dashboard ready</div>;
}

export default function DashboardPage() {
  return <SlowContent />;
}

🔌 Plugin System

Extend the framework with plugins: request hooks, HTML transforms, build and dev hooks, browser hooks, typed API routes, and their own database tables.

import { definePlugin } from "@farm.js/core";

export const myPlugin = definePlugin({
  name: "acme:my-plugin",

  runtime: {
    before({ request }) {
      // Runs before Farm's route handler. Return a Response to answer early.
    },
    after({ response }) {
      // Return a new Response to change headers or the body.
      return response;
    },
  },

  render: {
    html(html) {
      // Rewrite a page's rendered HTML.
      return html;
    },
  },
});

See the Plugin System guide for every plugin option and hook, and Create a Plugin for walkthroughs.

🎯 Core Concepts

File-based Routing

Farm.js uses Next.js App Router-style file-based routing:

• page.tsx - Creates a route
• layout.tsx - Shared UI for a route segment
• [param]/ - Dynamic route segment
• [...slug]/ - Catch-all route segment

React Server Components

Server Components run on the server and can directly access databases, file systems, or other server-only resources:

// This runs on the server
export default async function BlogPost({ params }: { params: { slug: string } }) {
  const post = await getPostFromDatabase(params.slug);

  return (
    <article>
      <h1>{post.title}</h1>
      <p>{post.content}</p>
    </article>
  );
}

Client Components

Use the 'use client' directive for interactive components:

"use client";

import { useState } from "react";

export default function Counter() {
  const [count, setCount] = useState(0);

  return <button onClick={() => setCount(count + 1)}>Count: {count}</button>;
}

📚 Documentation

Visit farmjs.dev for comprehensive documentation, guides, and API reference.

🏗️ Development

Prerequisites

• Node.js 22.13 or newer
• pnpm 8+

Setup

git clone https://github.com/farming-labs/farm.js.git
cd farm.js
./scripts/setup.sh

Development Commands

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Run tests (from root: runs tests in all packages; @farm.js/core runs Vitest)
pnpm test

# Run only @farm.js/core tests
pnpm run test:farm

# Run tests and save output to test-run.log
pnpm run test:ci
# then: cat test-run.log

# Start playground
cd playground && pnpm dev

# Start documentation
cd docs && pnpm dev

# Run example
cd examples/basic && pnpm dev

Project Structure

farm.js/
├── packages/
│   ├── farm/              # Core framework
│   ├── farm-cli/          # @farm.js/cli tools
│   ├── create-farm-app/   # App creation tool
│   ├── farm-react/        # React renderer + AOT compiler
│   └── farm-{preact,solid,vue,svelte}/  # Other renderers
├── examples/
│   ├── basic/             # Basic example
│   ├── rsc-demo/          # Server components, actions, and queries
│   └── stripe-integration/ # Typed integration usage
├── docs/                  # Documentation (Farm.js)
├── playground/            # Development testing
└── tests/                 # Integration tests

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Quick Contribution Steps

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes and add tests
4. Push and create a Pull Request

🌟 Examples

• Basic Example - Routing, boundaries, middleware, storage, and rendering modes in one app
• RSC Demo - Server components, server actions, and server queries
• React Compiler - The experimental AOT compiler side by side with baseline React
• Stripe Integration - Typed billing integration with provider-owned routes
• Solid Renderer - A Solid app on the same framework contracts
• Preact Renderer - A Preact app on the same framework contracts
• Vue Renderer - A Vue app on the same framework contracts
• Svelte Renderer - A Svelte app on the same framework contracts

🔗 Ecosystem

• Vite - Build tool and development server
• React - UI library with Server Components
• TypeScript - Type safety and developer experience

📄 License

MIT © Farming Labs

🙏 Acknowledgments

Farm.js is inspired by:

• Next.js - For the excellent App Router API design
• Vite - For the incredible development experience
• @lazarv/react-server - For RSC implementation insights
• Remix - For web-first development principles

Documentation • Examples • Contributing

Made with ❤️ by Farming Labs team