llms.txt
llms.txt

Farm.js Documentation

4 min read

Farm.js docs are served from the Farm docs runtime. The same markdown files power human pages, markdown routes, llms.txt, sitemap output, search, and agent discovery through /api/docs.

Start

Create an app and learn the files that matter.

  • Getting Started: Create a Farm.js app, understand the files that matter, and run the development server.
  • Project Structure: The compact file layout Farm expects, plus the optional files you add only when the app needs them.
  • Configuration: Use farm.config.ts as the single project control plane for source paths, integrations, docs, storage, deployment, and framework behavior.

Core

Routes, rendering, layouts, and request flow.

  • Routing: Farm uses an app directory routing model with static routes, dynamic segments, catch-all routes, and typed navigation.
  • Layouts and Route Boundaries: Wrap routes with root and nested layouts, then use loading, error, and not-found files for route-level UX.
  • Rendering Model: Choose dynamic rendering, static rendering, ISR, or PPR with route-level exports and config.
  • Middleware: Run request behavior before routes, pass request-scoped data to pages, and short-circuit with redirects or responses.
  • Environment Functions: Remove server-only or client-only implementations from the opposite bundle while preserving one typed interface.

Data and APIs

Typed params, API routes, API callers, and storage.

  • Query and Params: Parse search params and route params with typed helpers on the server and synchronized state on the client.
  • API Routes: Expose HTTP handlers from src/app/api and validate input with schemas before handler code runs.
  • API Client: Call app API routes with api.hello.get style inference, cache policies, invalidation, retries, callbacks, and optimistic updates.
  • Server Queries: Define typed server reads once, deduplicate requests, prefetch browser data, use SWR, and share invalidation keys with routes and APIs.
  • Storage: Use Farm storage clients for key-value data and pass storage clients to framework features and integrations.

Integrations

Provider integrations and custom integration contracts.

  • Integrations: Register services once, get owned routes, typed callers, providers, middleware, storage access, lifecycle hooks, and validation.
  • Stripe Integration: Add checkout, portal sessions, billing status, webhooks, product catalogs, metering, and storage-backed billing snapshots.
  • Autumn Integration: Add subscription, entitlement, and usage billing while keeping Farm's integration API and storage layer.
  • Polar Integration: Use Polar for products, checkout, customer portals, subscriptions, webhooks, and entitlement-aware app flows.
  • Auth Integrations: Use Better Auth, Auth.js, Clerk, Auth0, WorkOS, or Supabase without hand-rolling every auth route.
  • Email Integration: Render React Email templates, send with Resend, schedule messages, preview templates, and receive webhooks.
  • Jobs Integration: Define typed tasks once and run them through Trigger.dev or Inngest with trigger, schedule, batch, status, and cancel APIs.
  • Unkey Integration: Create, verify, revoke, update, and delete API keys, plus protect routes with key verification and rate-limit checks.
  • UI Registry: Opt into shadcn-style UI scaffolds for built-in integrations when you want working screens with the integration setup.
  • ORM Storage for Integrations: Pass one storage client through farm.config.ts and let integrations use ctx.args.db through the unified farming-labs/orm-style API.

Runtime

Cache, PPR, observability, instant preview, and deployment output.

  • Post-response Work: Schedule short server work with after() without delaying the response.
  • Cache and PPR: Use shared runtime cache helpers, tag/path invalidation, ISR-style revalidation, and static shell caching for PPR pages.
  • Observability: Listen to Farm runtime events for server lifecycle, route matching, rendering, API routes, integrations, storage, cache, PPR, builds, plugins, and errors.
  • DevTools and Doctor: Inspect the resolved app runtime in the browser and run the same diagnostics from the terminal or CI.
  • Cron: Map portable UTC schedules to ordinary API routes, run them locally, and compile them to deployment-native triggers.
  • Instant Preview: Expose the current local app through a public URL for sharing, webhooks, OAuth callbacks, and external testing.
  • Deployment: Build deployable output with Farm's deploy config and Nitro presets, from first-class targets to custom Nitro output.

Content

Docs runtime, markdown mirrors, and OpenAPI.

  • Docs Engine: Serve a @farming-labs/docs-inspired docs runtime from Farm config, including human pages and agent-readable API routes.
  • Markdown Mirrors: Expose markdown versions of app pages so agents, crawlers, docs tools, and support workflows can read rendered content as text.
  • OpenAPI Reference: Generate and publish API reference docs from Farm API route metadata, with Scalar-style presentation.

Extending

Plugin system and lifecycle hooks.

  • Plugin Ecosystem: Extend server and browser behavior across config, requests, routing, rendering, hydration, navigation, builds, and HMR.
  • Create a Plugin: Build a plugin with definePlugin when app behavior belongs in reusable framework lifecycle hooks.
  • Client Plugins: Attach typed hydration, navigation, error, performance, and cleanup hooks through a browser-safe module.

Reference

CLI, migrations, examples, and package map.

  • Migrations: Move Next.js and TanStack Router apps with dry-run codemods, then run schema/provider commands.
  • CLI: Use the Farm CLI to run, build, generate types, migrate apps, deploy output, and add integrations.
  • Examples: Use the examples folder as executable docs for routing, RSC, docs, markdown, auth, billing, email, jobs, and API keys.
  • Reference: A compact map of the main package exports and where to learn more.
Last updated at