@farm.js/cf-agent 0.1.49 → 0.1.51-beta.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +124 -3
  2. package/package.json +2 -2
package/README.md CHANGED
@@ -1,11 +1,132 @@
1
1
  # @farm.js/cf-agent
2
2
 
3
- First-class Cloudflare Agents integration for Farm.js
3
+ [Cloudflare Agents](https://developers.cloudflare.com/agents/) beside a Farm.js app, without
4
+ replacing the Agents SDK. In development Farm runs Wrangler and proxies Agent HTTP and WebSocket
5
+ traffic at the app's origin; in production the Farm build and the Agent Worker are composed into one
6
+ Worker.
4
7
 
5
8
  See [Stability and Support](https://farmjs.dev/docs/stability) for what this package guarantees.
6
9
 
10
+ ## Install
11
+
12
+ Cloudflare Agents and Wrangler require Node.js 22 or newer.
13
+
14
+ ```bash
15
+ pnpm add @farm.js/cf-agent agents
16
+ pnpm add -D wrangler @cloudflare/workers-types
17
+ ```
18
+
19
+ `agents` (`>=0.17.4 <1`) and `wrangler` (`>=4.111.0 <5`) are peer dependencies. Farm runs the
20
+ app's own Wrangler binary during `farm dev`.
21
+
22
+ ## Configure
23
+
24
+ ```ts
25
+ // farm.config.ts
26
+ import { cfAgent } from "@farm.js/cf-agent";
27
+ import { defineConfig } from "@farm.js/core";
28
+
29
+ export default defineConfig({
30
+ integrations: {
31
+ agent: cfAgent(),
32
+ },
33
+ deploy: {
34
+ target: "cloudflare",
35
+ preset: "cloudflare-module",
36
+ output: ".output",
37
+ },
38
+ });
39
+ ```
40
+
41
+ The `cloudflare-module` preset is required, because Farm and the Agents' Durable Objects share one
42
+ Worker; the build fails with any other preset. Wrangler stays the source of truth for Agent
43
+ bindings, migrations, compatibility flags, and environments, in `wrangler.jsonc` next to
44
+ `farm.config.ts`:
45
+
46
+ ```json
47
+ {
48
+ "name": "farm-cloudflare-agent",
49
+ "main": "agent.ts",
50
+ "compatibility_date": "2026-07-16",
51
+ "compatibility_flags": ["nodejs_compat"],
52
+ "durable_objects": {
53
+ "bindings": [{ "name": "CounterAgent", "class_name": "CounterAgent" }]
54
+ },
55
+ "migrations": [{ "tag": "v1", "new_sqlite_classes": ["CounterAgent"] }]
56
+ }
57
+ ```
58
+
59
+ `main` points at an ordinary Agents Worker: the `Agent` classes plus a default `fetch` that calls
60
+ `routeAgentRequest(request, env)`. Connect from the browser with Cloudflare's `useAgent()` hook
61
+ from `agents/react`; Farm only gives that protocol a same-origin home.
62
+
63
+ ## Development
64
+
65
+ `farm dev` starts Wrangler on a free loopback port and proxies `/agents` with WebSocket upgrades.
66
+ The proxy refuses cross-site requests and WebSocket upgrades with `403` before they reach Wrangler.
67
+ Same-origin requests, requests without an `Origin` header, and top-level `GET` navigations still
68
+ pass. Production requests go straight to the Worker, so authorize them inside it, for example in
69
+ `routeAgentRequest`'s `onBeforeConnect` and `onBeforeRequest`.
70
+
71
+ ## Build and deploy
72
+
7
73
  ```bash
8
- npm install @farm.js/cf-agent
74
+ farm build
75
+ farm deploy --cloudflare
9
76
  ```
10
77
 
11
- See the [Farm.js repository](https://github.com/farming-labs/farm.js) for documentation, examples, and support.
78
+ After the Farm build, the integration keeps the original `wrangler.jsonc` and writes:
79
+
80
+ - `.farm/cf-agent/worker.mjs`, a Worker entry that sends `/agents/**` to the Agent Worker and every
81
+ other request to Farm, and re-exports the Agent classes so Durable Object bindings stay valid.
82
+ Other handlers both Workers export, such as `scheduled` or `queue`, run the Agent's first, then
83
+ Farm's.
84
+ - `.farm-cf-agent.wrangler.jsonc`, the Wrangler config `farm deploy --cloudflare` deploys. It points
85
+ `main` at the combined entry, serves Farm's public output as assets, and adds `nodejs_compat`.
86
+ - `.farm/cf-agent/deploy.json`, the deploy metadata the CLI reads.
87
+
88
+ Check the combined Worker without uploading it:
89
+
90
+ ```bash
91
+ wrangler deploy --dry-run --config .farm-cf-agent.wrangler.jsonc
92
+ ```
93
+
94
+ Wrangler does not inherit `durable_objects` into an environment. When `environment` is set and that
95
+ environment declares no Durable Object bindings, the build fails and prints the bindings to copy.
96
+
97
+ ## Use an external Worker
98
+
99
+ Point Farm at a separately deployed Agent Worker instead:
100
+
101
+ ```ts
102
+ agent: cfAgent({
103
+ origin: process.env.CF_AGENT_ORIGIN,
104
+ });
105
+ ```
106
+
107
+ `CF_AGENT_ORIGIN` is also read when `origin` is omitted. With an origin, Farm does not start
108
+ Wrangler, proxies the route prefix to that Worker, and skips the combined Worker build.
109
+
110
+ ## Options
111
+
112
+ | Option | Default | Description |
113
+ | --------------- | ----------------- | ------------------------------------------------------------------------- |
114
+ | `config` | `wrangler.jsonc` | Wrangler config, relative to `farm.config.ts`. |
115
+ | `routePrefix` | `/agents` | Same-origin Agent route. Keep it equal to `routeAgentRequest`'s `prefix`. |
116
+ | `origin` | `CF_AGENT_ORIGIN` | An existing Agent Worker origin. |
117
+ | `environment` | | Wrangler environment for development and deployment. |
118
+ | `dev` | | `false` disables the managed Wrangler process. |
119
+ | `dev.port` | a free port | Fixed local Wrangler port. |
120
+ | `dev.remote` | `false` | Use Wrangler remote development. |
121
+ | `dev.logs` | `true` | Forward Wrangler output through Farm's logger. |
122
+ | `dev.timeoutMs` | `60000` | Maximum wait for Wrangler to start. |
123
+
124
+ ## Documentation
125
+
126
+ - [Cloudflare Agents integration](https://farmjs.dev/docs/integrations/cf-agent)
127
+
128
+ The [`examples/cf-agent`](https://github.com/farming-labs/farm.js/tree/main/examples/cf-agent) app
129
+ runs a counter Agent in development and as one Worker.
130
+
131
+ Report issues and find examples in the
132
+ [Farm.js repository](https://github.com/farming-labs/farm.js).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@farm.js/cf-agent",
3
- "version": "0.1.49",
3
+ "version": "0.1.51-beta.0",
4
4
  "description": "First-class Cloudflare Agents integration for Farm.js",
5
5
  "keywords": [
6
6
  "agents",
@@ -32,7 +32,7 @@
32
32
  },
33
33
  "dependencies": {
34
34
  "jsonc-parser": "^3.3.1",
35
- "@farm.js/core": "0.1.49"
35
+ "@farm.js/core": "0.1.51-beta.0"
36
36
  },
37
37
  "devDependencies": {
38
38
  "@types/node": "^22.20.5",