@farm.js/core 0.1.49 → 0.1.51-beta.0

package/README.md

@@ -1,11 +1,171 @@
 # @farm.js/core
 
-The core of Farm.js, the framework for the web and agents.
+The core of Farm.js, a full-stack framework for the web and agents. It owns app-directory routing in
+`src/app`, server rendering with streaming, API routes, server functions and queries, middleware,
+integrations, and the Vite and Nitro pipeline that turns an app into deployable output.
 
 See [Stability and Support](https://farmjs.dev/docs/stability) for what this package guarantees.
 
+## Install
+
+Start a new app with the starter, which installs the dependencies for you:
+
+```bash
+pnpm create @farm.js/app my-app --template basic
+```
+
+To add Farm to an existing project:
+
 ```bash
-npm install @farm.js/core
+pnpm add @farm.js/core react react-dom
+pnpm add -D @farm.js/cli
+```
+
+Farm requires Node.js 22.13 or newer. `@farm.js/cli` provides the `farm` command. Every peer
+dependency is optional: `react` and `react-dom` (18.2 or 19) are needed for the default React
+renderer, and apps on another renderer install that renderer's package instead. Add the others only
+when the app uses the feature:
+
+| Package              | Needed for                                                      |
+| -------------------- | --------------------------------------------------------------- |
+| `@tailwindcss/vite`  | Built-in Tailwind CSS (a stylesheet imports `tailwindcss`)      |
+| `@vercel/og`         | `opengraph-image` and `twitter-image` JSX, `@farm.js/core/og`   |
+| `sharp`              | Image optimization on Node, Vercel, Netlify, and in development |
+| `@farming-labs/docs` | The docs engine (`docs` enabled, or a `docs.config.*` file)     |
+
+## Usage
+
+A Farm app needs `src/app`, `farm.config.ts`, `package.json`, and `tsconfig.json`.
+
+```ts
+// farm.config.ts
+import { defineConfig } from "@farm.js/core";
+
+export default defineConfig({
+  deploy: {
+    target: "node",
+  },
+});
+```
+
+```tsx
+// src/app/layout.tsx
+import type { LayoutProps } from "@farm.js/core";
+
+export default function RootLayout({ children }: LayoutProps) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+
+```tsx
+// src/app/page.tsx
+import type { PageProps } from "@farm.js/core";
+
+export default function HomePage(_props: PageProps) {
+  return <h1>Hello from Farm.js</h1>;
+}
+```
+
+```json
+{
+  "scripts": {
+    "dev": "farm dev",
+    "build": "farm build",
+    "start": "node .farm/.output/server/index.mjs"
+  }
+}
 ```
 
-See the [Farm.js repository](https://github.com/farming-labs/farm.js) for documentation, examples, and support.
+Run `pnpm dev`. Farm generates route, environment, and i18n types into `src/farm.d.ts` and keeps
+them current while the dev server runs.
+
+## What it provides
+
+- **File routes.** Folders under `src/app` become URLs, with `page`, `layout`, `loading`, `error`,
+  and `not-found` files, `[id]` and `[...slug]` segments, `(group)` folders, and `@slot` folders.
+- **Rendering.** Pages render on the server, and React streams the HTML. Opt a route into static
+  output with `export const dynamic = "force-static"` or into ISR with
+  `export const revalidate = 300`. Partial Prerendering is experimental (`experimental.ppr`).
+- **APIs and data.** `route.ts` files export HTTP methods built with `createEndpoint`, and
+  `createApiClients` returns typed server and browser callers from the generated router.
+  `createServerFn` and `createServerQuery` define validated server functions and cached reads.
+- **Middleware.** Entries in `farm.config.ts` run first, then `src/app/**/middleware.ts` files from
+  the root segment down, in development and production.
+- **Integrations and plugins.** Provider packages mount through `integrations: { ... }` and
+  framework extensions through `plugins: [ ... ]`.
+- **Markdown mirrors.** Every page also answers as Markdown at its URL plus `.md`, for agents and
+  crawlers.
+
+```ts
+// src/app/api/hello/route.ts
+import { createEndpoint } from "@farm.js/core/api";
+
+export const GET = createEndpoint(async () => Response.json({ message: "Hello" }));
+```
+
+Pass `body`, `query`, or `headers` schemas as the first argument to validate input before the
+handler runs.
+
+## Renderers
+
+React is the default and is built into this package. Preact, Solid, Vue, and Svelte are beta
+adapters selected with `renderer` (for example `renderer: vue()` from `@farm.js/vue`). Routing,
+APIs, middleware, and deployment stay the same across renderers.
+
+React Server Components are experimental and opt-in:
+
+```ts
+export default defineConfig({
+  experimental: {
+    serverComponents: true,
+  },
+});
+```
+
+When the RSC packages are missing, `farm dev` and `farm build` install them with the app's package
+manager. CI never changes dependencies.
+
+## Deployment
+
+`deploy.target` maps to a Nitro preset. With no target, `farm build` writes a Node server to
+`.farm/.output`, unless it detects a Vercel, Netlify, or Cloudflare Pages build environment. Other
+Nitro presets pass through `deploy.preset` on a best-effort basis.
+
+| Target       | Nitro preset       |
+| ------------ | ------------------ |
+| `node`       | `node-server`      |
+| `vercel`     | `vercel`           |
+| `cloudflare` | `cloudflare-pages` |
+| `netlify`    | `netlify`          |
+
+## Entry points
+
+| Import                              | Use it for                                               |
+| ----------------------------------- | -------------------------------------------------------- |
+| `@farm.js/core`                     | `defineConfig` and types such as `PageProps`, `Metadata` |
+| `@farm.js/core/api`                 | `createEndpoint` for `route.ts` handlers                 |
+| `@farm.js/core/client`              | `Link`, `useRouter`, `createApiClients`                  |
+| `@farm.js/core/navigation`          | `redirect`, `notFound`, `usePathname`, `useSearchParams` |
+| `@farm.js/core/headers`             | `headers()`, `cookies()`, `getCspNonce()` on the server  |
+| `@farm.js/core/server-fn`           | `createServerFn`                                         |
+| `@farm.js/core/server-query`        | `createServerQuery`                                      |
+| `@farm.js/core/server-query/client` | `useServerQuery`, `prefetchServerQuery`                  |
+
+## Documentation
+
+- [Getting Started](https://farmjs.dev/docs/getting-started)
+- [Project Structure](https://farmjs.dev/docs/project-structure)
+- [Routing](https://farmjs.dev/docs/routing)
+- [Rendering Model](https://farmjs.dev/docs/server-rendering)
+- [API Routes](https://farmjs.dev/docs/api-routes)
+- [Server Queries](https://farmjs.dev/docs/server-queries)
+- [Middleware](https://farmjs.dev/docs/middleware)
+- [Configuration](https://farmjs.dev/docs/configuration)
+- [Renderers](https://farmjs.dev/docs/renderers)
+- [Deployment](https://farmjs.dev/docs/deployment)
+
+Report issues and find examples in the [Farm.js repository](https://github.com/farming-labs/farm.js).

package/dist/{agent-mcp-Bb8hnnqd.d.ts → agent-mcp-BBMfNpsC.d.ts}

@@ -1,4 +1,4 @@
-import { M as Metadata, aR as FarmAgentJsonLd, aS as FarmMCPServerRegistration, aT as FarmMarkdownResolvedConfig } from './client-plugins-DFDQUI9Q.js';
+import { M as Metadata, aS as FarmAgentJsonLd, aT as FarmMCPServerRegistration, aU as FarmMarkdownResolvedConfig } from './client-plugins-CFBEfVPO.js';
 
 type MetadataImageKind = "opengraph" | "twitter";
 interface FarmMetadataImageReference {

package/dist/{agent-mcp-ir3v4fHf.d.mts → agent-mcp-D44ip11f.d.mts}

@@ -1,4 +1,4 @@
-import { M as Metadata, aR as FarmAgentJsonLd, aS as FarmMCPServerRegistration, aT as FarmMarkdownResolvedConfig } from './client-plugins-BNBeyLMi.mjs';
+import { M as Metadata, aS as FarmAgentJsonLd, aT as FarmMCPServerRegistration, aU as FarmMarkdownResolvedConfig } from './client-plugins-cqy_dQd0.mjs';
 
 type MetadataImageKind = "opengraph" | "twitter";
 interface FarmMetadataImageReference {

package/dist/agent-runtime.cjs

@@ -1,6 +1,6 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; }
 
-var _chunkN25RPPO5cjs = require('./chunk-N25RPPO5.cjs');
+var _chunkWAPQWAE6cjs = require('./chunk-WAPQWAE6.cjs');
 require('./chunk-DUIP64BF.cjs');
 require('./chunk-PFV2KPDZ.cjs');
 require('./chunk-ZXK2EYQW.cjs');
@@ -8,7 +8,7 @@ require('./chunk-5DX3O6TT.cjs');
 require('./chunk-ITV4QQL2.cjs');
 require('./chunk-FEFCISOX.cjs');
 require('./chunk-Z5MZDFX4.cjs');
-require('./chunk-5566GNEG.cjs');
+require('./chunk-LIFUPCXW.cjs');
 require('./chunk-JYT7AN37.cjs');
 require('./chunk-B5BBTPJQ.cjs');
 require('./chunk-HA7YRO53.cjs');
@@ -97,7 +97,7 @@ function createAgentRuntimeIntegration(options) {
       });
     }
   };
-  return _chunkN25RPPO5cjs.defineIntegration.call(void 0, {
+  return _chunkWAPQWAE6cjs.defineIntegration.call(void 0, {
     category: "agent",
     type: provider,
     serverRuntime: options.serverRuntime,

package/dist/agent-runtime.d.mts

@@ -1,10 +1,9 @@
 import { ChildProcess } from 'node:child_process';
-import { B as BundleResultPayload, F as FarmPlugin, a as FarmIntegration } from './client-plugins-BNBeyLMi.mjs';
-import './lifecycle-DK06VuKP.mjs';
+import { B as BundleResultPayload, F as FarmPlugin, a as FarmIntegration } from './client-plugins-cqy_dQd0.mjs';
+import './lifecycle-C2aLBOwu.mjs';
 import './route-2_yXC6gv.mjs';
 import './endpoint-BkMSCRf6.mjs';
 import './cache.mjs';
-import './cache-invalidation-BD0z_lfu.mjs';
 import './renderer.mjs';
 import './deployment.mjs';
 import 'http';
@@ -21,15 +20,16 @@ import '@farming-labs/docs';
 import './observability-B2363jB6.mjs';
 import '@opentelemetry/api';
 import 'vite';
-import './workflows-Df1C_7OG.mjs';
+import './workflows-CRMzQZ3k.mjs';
 import './cron.mjs';
 import './env.mjs';
 import './server-action-security.mjs';
-import './layers-D9fbe-rz.mjs';
+import './layers-CcS42OGR.mjs';
 import 'rolldown/utils';
 import 'rolldown';
 import './image-config-CeDgNyX4.mjs';
-import './types--Wh02r5_.mjs';
+import './types-C41ePjvP.mjs';
+import './config-CnhyvvmT.mjs';
 import './types-DQnyD3VD.mjs';
 import './font.mjs';
 

package/dist/agent-runtime.d.ts

@@ -1,10 +1,9 @@
 import { ChildProcess } from 'node:child_process';
-import { B as BundleResultPayload, F as FarmPlugin, a as FarmIntegration } from './client-plugins-DFDQUI9Q.js';
-import './lifecycle-DK06VuKP.js';
+import { B as BundleResultPayload, F as FarmPlugin, a as FarmIntegration } from './client-plugins-CFBEfVPO.js';
+import './lifecycle-C2aLBOwu.js';
 import './route-DFhZj6jN.js';
 import './endpoint-BgHn0lhl.js';
 import './cache.js';
-import './cache-invalidation-BD0z_lfu.js';
 import './renderer.js';
 import './deployment.js';
 import 'http';
@@ -21,15 +20,16 @@ import '@farming-labs/docs';
 import './observability-B2363jB6.js';
 import '@opentelemetry/api';
 import 'vite';
-import './workflows-Df1C_7OG.js';
+import './workflows-CRMzQZ3k.js';
 import './cron.js';
 import './env.js';
 import './server-action-security.js';
-import './layers-D9fbe-rz.js';
+import './layers-CcS42OGR.js';
 import 'rolldown/utils';
 import 'rolldown';
 import './image-config-CeDgNyX4.js';
-import './types--Wh02r5_.js';
+import './types-C41ePjvP.js';
+import './config-CnhyvvmT.js';
 import './types-DQnyD3VD.js';
 import './font.js';
 

package/dist/agent-runtime.mjs

@@ -1,6 +1,6 @@
 import {
   defineIntegration
-} from "./chunk-NW2BKDVT.mjs";
+} from "./chunk-HHFMECFO.mjs";
 import "./chunk-H4WUWLQR.mjs";
 import "./chunk-F6TLUMH7.mjs";
 import "./chunk-46P5KNTE.mjs";
@@ -8,7 +8,7 @@ import "./chunk-EDPENAVO.mjs";
 import "./chunk-TGSEVBPO.mjs";
 import "./chunk-QSTRBKHZ.mjs";
 import "./chunk-IUQLRTTO.mjs";
-import "./chunk-C6U66WWF.mjs";
+import "./chunk-GFT5AHAT.mjs";
 import "./chunk-D2LCAV6L.mjs";
 import "./chunk-LM2YOGDK.mjs";
 import "./chunk-GYMGK467.mjs";