Skip to content

feat(cloudflare/email): local send_email stub in dev with dev.remote opt-in - #865

Merged
sam-goodwin merged 5 commits into
alchemy-run:mainfrom
zeyuri:docs/send-email-dev-warning
Jul 28, 2026
Merged

sam-goodwin merged 5 commits into
alchemy-run:mainfrom
zeyuri:docs/send-email-dev-warning

Conversation

@zeyuri

@zeyuri zeyuri commented Jul 18, 2026 •

Copy link
Copy Markdown
Contributor

Under alchemy dev, a send_email binding used to proxy straight to the live Cloudflare binding, so send() from a dev loop sent real mail (an OTP flow test made real send attempts). It now defaults to a local stub: send() logs the message's from/to/subject to the dev console and resolves without delivering. Opt into real sends per binding:

Cloudflare.Email.SendEmail("Email", {
  destinationAddress: "you@personal.example",
  dev: { remote: true }, // default false — local logging stub
});
  • SendEmailProps.dev.remote threads through the Worker's local provider to select SendEmail.remote vs SendEmail.local (the cloudflare-tools stub keeps the EmailMessage shim, so user code can still construct messages in dev)
  • cloudflare/email/send-and-receive.mdx documents the stub and the dev.remote opt-in; environments/local-development.mdx notes that side-effect bindings default to local

🤖 Generated with Claude Code

@john-royal

Copy link
Copy Markdown
Contributor

The way Miniflare and Wrangler handle it, the message is console.logged unless you opt in to the real, remote binding. Is that something you'd want?

@zeyuri

zeyuri commented Jul 21, 2026 •

Copy link
Copy Markdown
Contributor Author

Yes — logging-by-default with an opt-in for real sends is what we'd want. The catch is that a faithful stub is entirely a cloudflare-runtime change, not an alchemy one, so I'd rather confirm placement with you before wiring it. Concretely:

In cloudflare-runtime (distilled):

  • New src/bindings/send-email/send-email.worker.ts — a stub makeBinding(env) returning { async send(message) { /* console.log from/to/subject */ } }, mirroring analytics-engine.worker.ts.
  • Register that stub as an extension module and add export const local = (props) => Plugin.useSync(SendEmail, () => ({ name: props.binding, wrapped: { moduleName, innerBindings } })) in SendEmail.ts, alongside remote. The cloudflare-internal:email EmailMessage shim (SendEmailLive) is reused as-is.

In alchemy:

  • An opt-in flag (remote?: boolean; Wrangler calls it experimental_remote) on the send_email descriptor built in Cloudflare/Email/SendBinding.ts, threaded from Cloudflare.Email.SendEmail(...) props.
  • LocalWorkerProvider.ts's case "send_email" switches on it: b.remote ? SendEmail.remote({...}) : SendEmail.local({...}).
  • These two docs pages then describe the new default (logged locally; remote: true for real sends).

Happy to implement in that order (runtime PR first, then submodule bump + alchemy wiring) if you're good with the placement and the opt-in name.

@john-royal

Copy link
Copy Markdown
Contributor

Yeah that sounds great! Go ahead - would be happy to review and merge when ready.

The one part of your plan that I'd alter is making the option flag dev?: { remote?: boolean } to make it clear that we're referring to making it remote in dev. Is that ok with you?

@zeyuri

zeyuri commented Jul 21, 2026

Copy link
Copy Markdown
Contributor Author

dev: { remote: true } works well — consistent with the existing dev options on Worker. Implementing now: cloudflare-runtime stub PR first, then the alchemy wiring + these docs once it lands.

@zeyuri

zeyuri commented Jul 21, 2026

Copy link
Copy Markdown
Contributor Author

Runtime half is up: alchemy-run/cloudflare-tools#76 (the SendEmail.local stub, mirroring the analytics-engine one but logging from/to/subject). The alchemy wiring — dev: { remote: true } on the descriptor, LocalWorkerProvider switching on it, and rewritten versions of these two docs pages — is implemented and ready to PR the moment #76 lands and a cloudflare-runtime bump exists.

@john-royal john-royal self-assigned this Jul 21, 2026
@sam-goodwin

Copy link
Copy Markdown
Member

Is this ready to merge @john-royal ?

@john-royal

Copy link
Copy Markdown
Contributor

Docs need to be updated now that the local binding is implemented and remote now defaults to false. After that, good to merge.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@sam-goodwin sam-goodwin changed the title docs(email): warn that send_email is live under alchemy dev feat(cloudflare/email): local send_email stub in dev with dev.remote opt-in Jul 28, 2026
@sam-goodwin
sam-goodwin merged commit eb70263 into alchemy-run:main Jul 28, 2026
8 checks passed
sam-goodwin added a commit that referenced this pull request Jul 29, 2026
…r-aggregating destroy

Ports into the LocalProvider.make structure:
- make-before-break serveWith (workerd scopes fork from rootScope, closed on
  cutover / closeWorkerd) from #863
- url/urls/domain Attributes + resolveLocalUrls wildcard-host handling from #977
  (local urls no longer carry a trailing slash; tests updated to `${url}/path`)
- ALCHEMY_WORKER_NAME env (#860), viteMain root-relative resolution (#796),
  toRuntimeBinding dev.remote param for send_email (#865)

distilled bumped to main (0.30.2).

Co-authored-by: Cursor <cursoragent@cursor.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants