Farm.js

Upgrading to 0.1

Farm 0.1.0 is the first stable release. It follows 0.1.0-beta.108 and carries the stability policy: patch releases keep stable APIs working, and a minor release removes a stable API only after deprecating it first.

Upgrade the packages

Run the upgrade command from the app root:

farm upgrade --latest

It moves every published @farm.js/* dependency to its latest tag with the app's package manager. Packages in the shared release group, such as @farm.js/core, @farm.js/cli, @farm.js/devtools, and the integrations, move to 0.1.0. Renderer packages and plugins that are still in beta move to their newest beta, which is what their latest tag points to. Preview the commands first with farm upgrade --latest --dry-run.

To upgrade by hand, drop the @beta tag and keep every shared-group package on the same version. The integration packages pin @farm.js/core exactly, so mixing versions produces peer conflicts:

pnpm add @farm.js/core@latest
pnpm add -D @farm.js/cli@latest @farm.js/devtools@latest

pnpm 10.16 and newer can hold back versions published in the last day through minimumReleaseAge. Templates add @farm.js/* to minimumReleaseAgeExclude; add the same entry to your pnpm-workspace.yaml if an upgrade right after a release resolves an older version.

Behavior changes

These changes landed between the last beta and 0.1.0. Most apps need no code change.

  • React streaming on Node targets. With React 19, production servers on Node presets now stream through renderToPipeableStream, the same primitive development uses. Earlier betas used React's Web stream on Node when it was available. Response bodies are unchanged.
  • React on edge targets. Edge presets bundle React DOM's edge server build (server.browser on React 18) instead of its Node build. Cloudflare module Workers now bundle React instead of failing at startup with No such module "react".
  • Content Security Policy nonces and hashes. Enable security.csp.nonce for a strict script policy. Farm generates a per-request nonce for dynamic HTML and gives it to its own scripts and the renderer's streaming scripts. App-authored inline scripts run only when they pass getCspNonce() as their nonce. Fully prerendered pages stay static and receive per-page SHA-256 hashes for the same scripts instead. See Content Security Policy.
  • Caller-owned databases. storage.dispose() no longer closes a database you passed to databaseStorage(database). Databases Farm creates from storage configuration are still closed by Farm.
  • DevTools version. @farm.js/devtools is now released with core and shares its version.

Behavior changes within 0.1

The section above covers the last beta to 0.1.0. These landed in later 0.1 patches. Each names the release that introduced it, so skip anything at or below the version you are coming from.

Agent surfaces answer by default

At 0.1.0 these were off unless you opted in. An app with no agent block now answers all of them:

SurfaceSinceWhat it serves
Markdown mirrors, llms.txt, JSON-LD0.1.28Every static page as Markdown, by .md or Accept: text/markdown, plus an index of them
/.well-known/farmjs.json0.1.32, sections configurable from 0.1.42Farm's version, the installed @farm.js/* packages, the renderer, base path, integrations by category, and plugin names. From 0.1.63, the app's public site URL
/sitemap.xml0.1.36Your static pages, when the docs engine is not serving its own
/mcp0.1.36A read-only MCP server that lists, searches and reads your public pages

None of this serves content an anonymous visitor could not already reach. A page behind a guard answers the guard's own response to a Markdown request, and llms-full.txt keeps its entry without a body, because the generated files are built from requests that carry no cookies or credentials. Nothing new is writable, and discovery never grants permission.

A guarded page's title and description do still appear in llms.txt, since those come from the metadata you wrote rather than from the page's content. Use exclude below to drop the route entirely when even that is too much.

That is still a larger public surface than the app had at 0.1.0, which matters for an internal tool or a staging deployment. Turn off what you do not want:

farm.config.ts
export default defineConfig({
  agent: {
    llmsTxt: false,
    sitemap: false,
    mcp: false,
    jsonLd: false,
    manifest: false,
  },
});

To keep the surfaces but hide a route from the generated indexes, exclude it instead: agent: { llmsTxt: { exclude: ["/account"] } }. See agent readiness.

The site URL in /.well-known/farmjs.json is the one environment value the manifest serves. It is FARM_SITE_URL when set, otherwise the production address the host gives the server (Vercel, Render, Railway), and only ever a public https origin. On Vercel a preview deployment names the production site. agent: { manifest: { site: false } } serves site: null and keeps the rest.

Configuration that is now rejected

These were accepted and silently did nothing. They now fail when the config, an integration, or a middleware file loads, so an app that carried one builds today and fails after the upgrade.

  • Regex matcher strings (0.1.39, with more forms in 0.1.40). Next-style strings such as /((?!api|_next).*) compiled to a literal that matched no path, so the middleware never ran. Pass a RegExp instead. The error names the matcher.
  • createEndpoint's use option (0.1.40). It was ignored. Pass middleware instead.

Requests and flags that are now refused

These worked before and now refuse, because the old behavior could hand a credential or a scheduled task to someone else.

  • farm preview with a gateway you run (0.1.60). A Farm.js Infrastructure key (FARMJS_API_KEY, or one farm login saved) only goes to the hosted gateway, https://preview.farmjs.dev. A self-hosted gateway needs --trust-gateway on farm preview, farm login and farm whoami, and its URL must be https unless it is on localhost. A key already saved for a gateway is still reused there without the flag.
  • @farm.js/agent's cron route on Vercel (@farm.js/agent 0.1.0-beta.2). /_vercel/cron answers 401 without Authorization: Bearer $CRON_SECRET, and refuses every request while CRON_SECRET is unset. Set it in the Vercel project; the build warns when it is missing.
  • @farm.js/agent's basePath outside /api (@farm.js/agent 0.1.0-beta.1, with core 0.1.50). Agent routes are API routes now, so the app's middleware and guards run first. Any other basePath throws when the config loads.

Development runs middleware for API routes

From 0.1.50, farm dev runs app middleware for API routes, as production already did. A middleware that redirects or rewrites every path now reaches /api/* in development too. Scope it with its config.matcher or exclude.

Pages a middleware matcher cannot reach are prerendered

Before 0.1.60, any middleware file above a static page kept that page rendered per request. Now a middleware file whose export const config = { matcher } is literal, and provably cannot match the page, no longer does, so the page is prerendered at build like any other static page. The runtime never ran that middleware there either. A matcher Farm cannot read at build (a function, a computed value) keeps the page rendered per request.

FARM_VITE_BUILDER=rollup

Removed in 0.1.14, when core moved development and production onto one Vite 8. rollup now fails with an actionable message; rolldown is still accepted. The Rollup fallback for an incomplete client bundle is gone too: a bundle that stays incomplete after the sequential retry fails the build instead of rebuilding with Rollup.

Feature packages the app installs

Starting with 0.1.22, @farm.js/core no longer installs the packages behind optional features. An app that uses one of these features declares the package itself. New starters already do, and farm doctor reports a feature that is in use without its package.

FeatureInstall
Built-in Tailwind CSS (a stylesheet imports tailwindcss)pnpm add -D @tailwindcss/vite
opengraph-image/twitter-image JSX, @farm.js/core/ogpnpm add @vercel/og
Image optimization on Node, Vercel, Netlify, and in devpnpm add sharp
Docs engine (docs enabled, or a docs.config.* file)pnpm add @farming-labs/docs

Without @tailwindcss/vite, Farm keeps building without Tailwind and logs the install command the first time a stylesheet imports tailwindcss. Without @vercel/og, farm build fails with the install command when the app has a generated metadata image or imports @farm.js/core/og; static opengraph-image.png files do not need it. Without sharp, images.provider: "auto" serves original image URLs (the documented provider: "none" behavior) and logs the install command, and images.provider: "node" fails. Without @farming-labs/docs, farm dev and farm build fail with the install command when docs are enabled.

Deprecated APIs to replace before 0.2

These still work in 0.1 and are scheduled for removal in a later minor release.

Plugin lifecycle hooks

DeprecatedUse instead
initsetup
configconfigure
readyruntime.start
shutdownruntime.close
devServerCreateddev.server
hmrUpdatedev.update
buildStart, beforeBundlebuild.before
buildEnd, afterBundlebuild.after
beforeNitroBuildbuild.configure
routeDiscovered, middlewareDiscovered, apiRouteDiscoveredrouter.discovered
routesGeneratedrouter.generated
beforeRouteMatch / afterRouteMatchrouter.before / router.after
beforeRenderrender.before
afterRender, transformHTMLrender.html
transformPagerender.before or render.html
beforeApiHandler, beforeRequestruntime.before
afterApiHandler, afterResponseruntime.after
requestContext on the plugin contextctx.req

Integrations and schemas

DeprecatedUse instead
slot on integration descriptors, FarmIntegrationSlotcategory, FarmIntegrationCategory
requestContext, FarmIntegrationRequestContextStorereq, FarmRequestStore
defineIntegrationSchemadefineSchema (an exact alias)
FarmIntegrationSchema* typesthe matching FarmSchema* types

Configuration and routes

DeprecatedUse instead
The built-in DevTools dashboard (devtools)devtools() from @farm.js/devtools in plugins
defineCron()cron in farm.config.ts, pointing at an API route
generateStaticParamsgetStaticPaths
md.routesmd.expose
security.contentSecurityPolicysecurity.csp

Getting help

If an app behaves differently after upgrading, run farm doctor and open an issue with its output, the renderer, and the deployment target.