Plugin EcosystemCopy Anchor Link

Plugins are Farm's framework extension surface. Use a plugin to change how Farm configures an app, handles requests, discovers routes, renders HTML, builds output, observes browser hydration and navigation, or responds to development events.

Use an integration for a product or service such as authentication, payments, email, analytics, or a database. Integrations own product config, endpoints, typed callers, and providers. Plugins own framework lifecycle behavior.

Official pluginsCopy Anchor Link

Each published plugin has its own setup page in this section. Use Create a Plugin when the behavior is specific to your application or package.

Community pluginsCopy Anchor Link

Community plugins are maintained by their authors outside the Farm project.

Plugin authoringCopy Anchor Link

Start with Create a Plugin for the server and build lifecycle. Add the Client Plugin API only when the plugin also needs browser hydration, navigation, error, performance, or cleanup hooks. Client plugins are an authoring capability, not a separately installed package.

What framework-focused meansCopy Anchor Link

A framework-focused plugin changes how Farm operates, rather than adding one application's business feature. It runs at stable framework boundaries and can be reused across unrelated applications.

For example, request tracing is framework-focused because it should work for pages, APIs, actions, docs, and integrations without knowing their business logic. A Stripe checkout extension is product-focused because it owns Stripe config, webhook endpoints, and a typed API.

What plugins can buildCopy Anchor Link

The lifecycle is intentionally broad enough for infrastructure and tooling without turning plugins into product modules.

A plugin can cover several lifecycle phases, but focused plugins are easier to order, test, and reuse. Product endpoints and typed product callers should remain in an integration even when that integration contributes a plugin internally.

Register a pluginCopy Anchor Link

import { defineConfig } from "@farm.js/core";
import { requestTracingPlugin } from "./src/plugins/request-tracing";

export default defineConfig({
  plugins: [requestTracingPlugin()],
});

InterfaceCopy Anchor Link

definePlugin() infers private setup state and request context across the plugin.

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

export const frameworkPlugin = definePlugin({
  name: "framework-plugin",
  enforce: "pre",

  configure(config) {},
  setup({ env }) {
    return { startedAt: Date.now() };
  },

  runtime: {
    start({ state }) {},
    context({ request, state, req }) {
      return { pathname: new URL(request.url).pathname };
    },
    before({ request, ctx, state }) {},
    after({ response, ctx, state }) {},
    error({ error, ctx, state }) {},
    close({ reason, state }) {},
  },

  router: {
    discovered(route, { state }) {},
    generated(routes, { state }) {},
    before(route, { state }) {},
    after(result, { state }) {},
  },

  render: {
    before(render, { state }) {},
    html(html, render, { state }) {},
  },

  build: {
    before(bundle, { state }) {},
    configure(buildConfig, { state }) {},
    after(result, { state }) {},
  },

  dev: {
    server(viteServer, { state }) {},
    update(update, { state }) {},
  },

  client: {
    public: { release: "2026.07" },
    setup({ public: config }) {
      return { release: config.release };
    },
    navigation: {
      rendered({ state, to }) {
        console.log(state.release, to.pathname);
      },
    },
  },
});

Only define the groups your plugin needs.

Complete lifecycle referenceCopy Anchor Link

Plugin definitionCopy Anchor Link

Both hooks receive Farm's plugin context. setup additionally receives the resolved env. Its returned state is private to that plugin instance and is not serialized to the browser.

Framework onError dispatch invokes every selected reporter in plugin order and awaits all returned promises, even if another reporter throws or rejects. Reporters can run concurrently. After all settle, the first observed reporter failure is surfaced to the dispatch caller; startup and request handling report it separately from the original failure. Keep error reporters finite: they are awaited before the caller continues.

Other parallel hooks remain fail-fast: a synchronous throw stops dispatch before later hooks are invoked and rejects with the same thrown value. Farm still observes promises from already-started hooks so their later rejections are handled. This does not wait for or cancel that work; asynchronous failures retain normal Promise.all behavior.

In development, a native Vite restart keeps the same Farm plugin runtime and instrumentation alive; it does not rerun setup or dispose resources registered with lifecycle.onShutdown(). Awaiting the Farm dev server's close() waits for an in-progress restart, closes the current Vite server, and then awaits plugin cleanup and instrumentation shutdown exactly once. Cleanup errors reject close(). New restart requests are rejected once final shutdown begins.

If initial development-server creation fails, Farm awaits cleanup of the resources it has created before rejecting: Vite's server once configureServer begins (even if a Vite hook fails before the server is returned), registered plugin shutdown hooks and disposers, and instrumentation. This includes failures in configureServer, its returned post hook, and middleware-mode buildStart. A failing onError hook or cleanup step is reported separately and does not replace the original startup error or skip the remaining cleanup.

Development startup failures are sent to onError before cleanup: errors during creation use phase: "createServer", while errors when listening (such as an occupied port) or running runtime.start use phase: "startDevServer". A creation failure is not reported again by the startup wrapper. Async error hooks are awaited while plugin resources are still available; a failed error hook does not prevent cleanup or replace the startup error.

Runtime hooksCopy Anchor Link

Runtime request hooks apply to page, API, server-action, integration, docs, asset, and general requests. Use runtime.endpoints when a plugin owns a small exact URL and should not make unrelated static pages dynamic. Endpoint paths are application-relative, automatically honor basePath, and do not accept route parameters or wildcards.

Direct api calls from createApiClients() invoke an endpoint inside the current request; they do not create another plugin request lifecycle. Endpoint middleware still runs. Use endpoint middleware for authorization needed by both direct and HTTP callers.

Runtime event valuesCopy Anchor Link

Router hooksCopy Anchor Link

Router hooks are useful for diagnostics, conventions, manifests, and instrumentation. They should not silently replace application authorization or handler-level validation.

Render hooksCopy Anchor Link

Adding render.html requires Farm to buffer the final document. Prefer render.before when observation is enough and preserving streaming matters.

Build hooksCopy Anchor Link

Development hooksCopy Anchor Link

Development hooks do not run as part of the deployed request lifecycle.

Client lifecycleCopy Anchor Link

The optional client property keeps browser behavior under the same plugin identity and ordering as its server hooks. Farm extracts the known lifecycle hooks into its generated browser runtime without copying the server plugin, server setup state, or private environment values.

client: {
  public: {
    release: "2026.07",
  },
  setup({ public: config }) {
    return { release: config.release };
  },
  navigation: {
    rendered({ state, to }) {
      console.log(state.release, to.pathname);
    },
  },
},

Farm runs client.setup once, surrounds initial hydration, emits navigation phases from the active router, isolates hook failures, aborts superseded navigation sessions, and closes plugins during page hide or HMR disposal.

Only JSON-safe values in client.public enter the browser bundle. Server setup state, request context, and private environment values never cross this boundary. See Client Plugins for the complete interface and security model.

Runtime flowCopy Anchor Link

For each application request, Farm runs the runtime hooks in this order:

1. An exact runtime.endpoints match runs before ordinary request context and routing.
2. Otherwise, every runtime.context creates request-local values.
3. Every runtime.before runs in plugin order.
4. Farm calls the page, API route, or integration handler unless a plugin returned a Response.
5. Every runtime.after can transform the response, including an endpoint response.
6. runtime.error observes an error if any preceding phase throws.

runtime.before may return a new Request, return a Response to short-circuit, or return nothing. A short-circuit response still passes through runtime.after. runtime.after may return a new Response or return nothing.

Runtime hooks use Web APIs, so the same plugin works in development and universal production builds. The event includes kind, route metadata, the request AbortSignal, and waitUntil() for background work supported by the host.

An endpoint is intentionally isolated from runtime.context and runtime.before. Perform any endpoint-specific authentication inside its handler. Global runtime.after and runtime.error hooks still observe endpoint responses and failures.

State and contextCopy Anchor Link

There are three different kinds of plugin data:

Farm merges all runtime.context results before running runtime.before. Context keys must be unique; Farm throws and names both plugins when two plugins return the same key.

ctx remains server-only. To expose a safe value to a page, write it to req explicitly:

runtime: {
  context({ req }) {
    const traceId = crypto.randomUUID();

    req.set("traceId", traceId, { exposeToPage: true });
    req.set("internalToken", "server-only");

    return { traceId };
  },
},

Only values marked exposeToPage: true appear in props.context?.data. Farm preserves the request store when a plugin returns a transformed Request, buffers a request body, or clones a request for production dispatch. Private values stay private; these replacements do not expose them to page props or another request.

OrderingCopy Anchor Link

Set enforce only when hook order is part of the plugin contract:

definePlugin({ name: "auth-context", enforce: "pre" });
definePlugin({ name: "metrics" });
definePlugin({ name: "response-reporting", enforce: "post" });

Farm runs pre plugins first, normal plugins second, and post plugins last. Hooks that transform a shared value run serially in that order.

Plugin or integrationCopy Anchor Link

How the ecosystem composesCopy Anchor Link

Plugins can be local to one repository, published as packages, bundled by a Farm layer, or contributed internally by an integration. They all enter the same ordered lifecycle.

import { defineConfig } from "@farm.js/core";
import { securityPlugin } from "@acme/farm-plugin-security";
import { tracingPlugin } from "@acme/farm-plugin-tracing";
import { routePolicyPlugin } from "./src/plugins/route-policy";

export default defineConfig({
  plugins: [
    securityPlugin({ csp: true }),
    tracingPlugin({ service: "storefront" }),
    routePolicyPlugin,
  ],
});

Each plugin owns its private state. At runtime, ctx is the read-only aggregate of plugin context results, while req is the explicit mutable request store shared with other server lifecycle code. Use stable, namespaced plugin names and context keys so independently published plugins compose without hidden shared globals or collisions.

Built-in pluginsCopy Anchor Link

Farm includes plugins for logging, compression, redirects, rewrites, headers, and environment helpers. Register them from @farm.js/core/plugin/server.

The production compression plugin negotiates Brotli or gzip from Accept-Encoding, streams the encoded response body, adds Vary: Accept-Encoding, and removes the identity Content-Length. Responses that are already encoded, partial, marked no-transform, or sent as server-sent events are left unchanged.

Dynamic Brotli responses use compression quality 5 to balance response latency and transfer size. Both Brotli and gzip flush each chunk so streaming content can arrive before the response finishes. Gzip keeps its existing compression level; this setting does not change precompressed static assets or compression managed by a deployment platform.

Compression applies to media types that actually shrink: every text/* type, application/json, application/javascript, application/xml, application/wasm, application/x-ndjson, any +json or +xml type such as image/svg+xml or application/manifest+json, and the uncompressed font formats (font/ttf, font/otf, application/vnd.ms-fontobject). Already compressed payloads are skipped, so images, video, audio, archives, PDFs, Office documents, font/woff, font/woff2 and application/octet-stream are streamed through untouched with their identity Content-Length and strong ETag intact. A response with no Content-Type is also left alone, since its bytes may already be compressed. Set a Content-Type when a route returns text that should be compressed.

Legacy hooksCopy Anchor Link

Existing flat hooks such as beforeRequest, afterResponse, beforeApiHandler, afterRender, beforeBundle, and shutdown remain supported. They are deprecated where a structured equivalent exists. New plugins should use the grouped interface; do not define both versions of the same phase in one plugin because Farm will run both.

The Node-specific beforeRequest and afterResponse hooks remain available as compatibility escape hatches. Prefer runtime.before and runtime.after for portable plugins.

Production checklistCopy Anchor Link

• Give every plugin a stable, namespaced name.
• Keep per-request hooks fast and cancellation-aware.
• Return a new Request or Response instead of mutating Web objects.
• Never place credentials or secrets in page-exposed request data.
• Use waitUntil() only for work that may safely outlive the response.
• Make runtime.error resilient; an error reporter must not hide the original failure.
• Release timers, sockets, and watchers in runtime.close. Long-running Node output invokes it for handled shutdown signals; serverless and edge hosts remain platform-specific.
• Test server and client hook ordering, short circuits, transformed bodies and headers, context collisions, hydration, SPA navigation, and production output.

Continue with Create a Plugin for complete examples.