llms.txt
llms.txt

Farm.js Documentation

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, KV storage, database clients, 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.
  • Fonts: Compile local or remote fonts into self-hosted, hashed assets with generated CSS and no loader runtime.
  • 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.
  • Built-in Authentication: Enable email/password auth, sessions, server helpers, and React APIs with the top-level auth framework 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, KV storage, and database access.

  • 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.
  • KV Storage: Use getStorage() for caches, settings, counters, idempotency records, and object-backed values.

Integrations

Provider integrations and custom integration contracts.

  • Integrations: Register services once, get owned routes, typed callers, providers, middleware, database models, lifecycle hooks, and validation.
  • Stripe Integration: Add checkout, portal sessions, billing status, webhooks, product catalogs, metering, and database-backed billing snapshots.
  • Autumn Integration: Add subscription, entitlement, and usage billing with schema-backed database records through the integration ORM.
  • Polar Integration: Use Polar for products, checkout, customer portals, subscriptions, webhooks, and entitlement-aware app flows.
  • Auth Integrations: Choose built-in Farm Auth or an explicit Better Auth, Auth.js, Clerk, Auth0, WorkOS, or Supabase integration.
  • 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.
  • Database and ORM Clients: Use application-owned ORM models, schema-backed integration databases, and adapter-owned data without confusing them with KV storage.

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, integration databases, 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.

Migrations

Move an existing framework app to Farm with inspectable, dry-run-first migrations.

  • Migration Overview: Choose a source framework, distinguish automated from manual migrations, and follow a safe migration workflow.
  • Migrate from Next.js: Move App Router files, common Next.js imports, middleware, scripts, and Farm setup.
  • Migrate from SvelteKit: Map SvelteKit routes, layouts, load functions, endpoints, hooks, environment variables, and adapters into Farm.
  • Migrate from Nuxt: Map Nuxt pages, layouts, server routes, data composables, middleware, runtime configuration, and Nitro output into Farm.
  • Migrate from TanStack Start: Convert TanStack Router file routes, route paths, component exports, scripts, and Farm setup.

Reference

CLI, testing, examples, and package map.

  • 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