@farm.js/cf-agent 0.1.50 → 0.1.51-beta.1
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.
- package/README.md +124 -3
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,11 +1,132 @@
|
|
|
1
1
|
# @farm.js/cf-agent
|
|
2
2
|
|
|
3
|
-
|
|
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
|
-
|
|
74
|
+
farm build
|
|
75
|
+
farm deploy --cloudflare
|
|
9
76
|
```
|
|
10
77
|
|
|
11
|
-
|
|
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.
|
|
3
|
+
"version": "0.1.51-beta.1",
|
|
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.
|
|
35
|
+
"@farm.js/core": "0.1.51-beta.1"
|
|
36
36
|
},
|
|
37
37
|
"devDependencies": {
|
|
38
38
|
"@types/node": "^22.20.5",
|