All jobs

Add a Cron Trigger to a Hono Worker

Yes. An agent adds a cron schedule to your Hono Worker's wrangler config, exports a scheduled handler beside app.fetch, tests it in Workers Vitest, and opens a PR.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent reads how the Worker is exported before it adds a second handler. In a Worker shaped like the blog workspace of honojs/examples, src/index.ts builds a Hono app, mounts prettyJSON and a basicAuth check on non-GET requests under /posts/* read from c.env.USERNAME and c.env.PASSWORD, routes /api to src/api.ts, and ends with export default app. That line is why a cron cannot simply be added: Workers call scheduled on the default export, and a bare Hono instance has none. src/bindings.ts types the env as USERNAME, PASSWORD and BLOG_EXAMPLE: KVNamespace, and wrangler.example.toml names the Worker hono-example-blog with compatibility_date 2024-04-01, the nodejs_compat flag, the KV binding and no [triggers] table.

src/model.ts shows what a scheduled job can usefully do. Posts live in KV under keys prefixed v1:post:, and getPosts does KV.list({ prefix }) and then one KV.get per key, so GET /api/posts costs one read per post on every request. createPost, updatePost and deletePost each write or delete one key. package.json has hono ^4.2.4, wrangler ^3.53.0, vitest pinned to 1.3.0 and @cloudflare/vitest-pool-workers ^0.2.0; vitest.config.ts runs the suite inside workerd with defineWorkersConfig and wrangler: { configPath: './wrangler.toml' }, and src/api.test.ts imports env from cloudflare:test and calls worker.request('/posts', {}, env).

The agent changes the export to export default { fetch: app.fetch, scheduled } and keeps export { app } so the existing tests and api.test.ts still import what they use. The scheduled function takes (controller: ScheduledController, env: Bindings, ctx: ExecutionContext), rebuilds an index: it calls getPosts, writes the array once under v1:index with KV.put, and wraps the work in ctx.waitUntil so the invocation is not cut short. wrangler.example.toml gets a [triggers] table with crons = ["*/15 * * * *"], and the pull request shows the one-line change that makes GET /api/posts read v1:index first and fall back to the per-key reads, left as a follow-up so this change stays a pure addition.

Tests use the pool's own tools: src/scheduled.test.ts seeds two posts through model.createPost into env.BLOG_EXAMPLE, calls the exported scheduled with a controller whose cron is the configured string, a scheduledTime and a noRetry, and a context whose waitUntil collects promises the test awaits, then reads v1:index back and checks both posts are in it; a second case runs it with no posts and expects an empty array. The agent also runs wrangler dev --test-scheduled in the sandbox and curls /__scheduled?cron=*/15+*+*+*+* to see the handler fire outside Vitest, runs npm test and npx tsc --noEmit, and keeps all three outputs.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Add a cron trigger to this Hono Worker and open a pull request. Read package.json, wrangler.example.toml, vitest.config.ts, tsconfig.json, src/index.ts, src/api.ts, src/model.ts, src/bindings.ts and src/api.test.ts first. Change the default export to an object with fetch set to app.fetch and a scheduled handler, and keep a named export of app so existing imports work. The scheduled handler takes a ScheduledController, the Bindings env and an ExecutionContext, rebuilds a JSON index of all posts under the key v1:index using the existing getPosts, and runs the work inside ctx.waitUntil. Add a [triggers] table with crons set to every 15 minutes to wrangler.example.toml. Do not change GET /api/posts in this pull request; show in the description the one-line change that would read v1:index first. Add src/scheduled.test.ts using env from cloudflare:test that seeds two posts, calls scheduled with a fake controller and a context that collects waitUntil promises, and checks v1:index holds both, plus a case with no posts. Run wrangler dev --test-scheduled and curl the __scheduled endpoint with the cron string, run npm test and npx tsc --noEmit, and paste the output in the pull request.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

What comes back is a pull request that changes the last line of src/index.ts into an object export, adds a scheduled function above it, adds a [triggers] table to wrangler.example.toml, and adds src/scheduled.test.ts. The description pastes the Vitest summary, the tsc --noEmit result, the request line from wrangler dev --test-scheduled showing the __scheduled call handled, and the one-line follow-up for GET /api/posts.

The example repository has no workflow of its own, so the test output in the pull request is the check; on a repository with a Vitest workflow the new file runs on the pull request.

A reviewer checks that the fetch routes behave as before through the existing api.test.ts, that the cron string is the one they want, and that the handler's work is inside waitUntil. After merging they deploy, and the trigger appears on the Worker's settings page with its next run.

Run it on every Worker that needs a background job

A team with several Workers sends one POST /o/{org}/sessions per repository with this prompt and the repository in resources. Each run reads its own export and bindings, so a Worker that already exports an object gets only the scheduled key added, and each opens its own pull request.

Give the key a webhook_url and Rush POSTs run.completed when each turn ends, with session_url to read the pull request from, and send a request_id so a retried call returns the run it already started.

The use case this job follows, with its automation and trigger: Hand off a long task.

Why run it on Rush?

A cron handler is the kind of code that is only exercised in production unless someone sets up the harness: a fake controller, a context whose waitUntil the test can await, a local __scheduled call. In a Rush sandbox the agent builds that harness, runs the handler inside workerd against a local KV, fires it once through wrangler dev, and keeps every output in the run's record beside the pull request.

Turning export default app into an object export is one line, but doing it without breaking app.request in the existing tests, typing the controller and context, and proving the job runs is an afternoon on a laptop. The agent does it in one pass, and the same request works unchanged on the next Hono Worker.

Frequently asked questions

Will the existing routes or tests change?

No. fetch is app.fetch, so every route behaves as before, and app stays exported by name so src/api.test.ts and anything that calls app.request keep working. The only edit to src/index.ts is the export and the new function above it.

Why rebuild an index instead of something else?

Because getPosts in src/model.ts does a list and then one get per post, so an index key is the obvious job for a schedule in this Worker. A run on a Worker with other data gets a job that fits that data; the prompt names this one because the repository makes it concrete.

How is the handler tested without a real schedule?

The test calls the exported scheduled directly with a controller object carrying cron, scheduledTime and noRetry, and a context whose waitUntil pushes promises into an array the test awaits. wrangler dev --test-scheduled then exposes /__scheduled for a manual check outside Vitest.

Does it change wrangler.toml?

The repository commits only wrangler.example.toml, so the [triggers] table is added there. A reader with a real wrangler.toml gets the same table in that file; the trigger is created on the next wrangler deploy.

More Hono jobs

The same job on other stacks

More jobs like this: Hand off a long task

Keep reading