Plugin Ecosystem

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 plugins

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.

Plugin authoring

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 means

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 build

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 plugin

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

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

Interface

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 reference

Plugin definition

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.

Runtime hooks

Runtime hooks apply to page, API, server-action, integration, docs, asset, and general requests. Use the event's kind and route values when behavior should apply only to part of the application.

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 values

Router hooks

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

Render hooks

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

Build hooks

Development hooks

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

Client lifecycle

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 flow

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

1. Every runtime.context creates request-local values.
2. Every runtime.before runs in plugin order.
3. Farm calls the page, API route, or integration handler unless a plugin returned a Response.
4. Every runtime.after can transform the response.
5. 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.

State and context

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.

Ordering

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 integration

How the ecosystem composes

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 plugins

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.

Legacy hooks

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 checklist

• 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.