Skip to content

feat(cloudflare): Worker.URL — bind a Worker's own URL onto itself - #964

Merged
sam-goodwin merged 3 commits into
mainfrom
claude/worker-url-binding-f284a6
Jul 27, 2026
Merged

sam-goodwin merged 3 commits into
mainfrom
claude/worker-url-binding-f284a6

Conversation

@sam-goodwin

Copy link
Copy Markdown
Member

Closes #953.

Worker.URL injects a Worker's own public URL as a binding on that same Worker. It works in both Worker styles and under alchemy dev (where it resolves to the local dev-server URL).

Effect-native:

Cloudflare.Worker(
  "Api",
  { main: import.meta.url },
  Effect.gen(function* () {
    const url = yield* Cloudflare.Worker.URL; // attaches binding, returns accessor

    return {
      fetch: Effect.gen(function* () {
        const publicUrl = yield* url; // string
        return Response.json({ url: publicUrl });
      }),
    };
  }).pipe(Effect.provide(Cloudflare.Workers.URLBinding)),
);

Async Workers declare it on env (InferEnv maps it to string), and the canonical Vite case inlines it into the client bundle at build time:

Cloudflare.Website.Vite("Website", {
  env: {
    VITE_PUBLIC_URL: Cloudflare.Worker.URL, // import.meta.env.VITE_PUBLIC_URL + env.VITE_PUBLIC_URL
  },
});

How it works:

  • The URL is fully computable before the script upload (first custom domain, else https://{name}.{accountSubdomain}.workers.dev), so there is no circularity — the binding emits an alchemy-only { type: "self_url", name } sentinel that the provider resolves and lowers into a plain_text binding just before putScript, and substitutes into the Vite define env before the build.
  • The resolved URL is folded into the worker metadata hash, so an account-subdomain rename or domain reorder redeploys the Worker with the fresh value.
  • Defects with clear messages for Workers that have no URL (url: false with no domains) and dispatch-namespace user workers.
  • LocalWorkerProvider lowers the sentinel to the dev-proxy URL (Text binding + Vite dev define).

Live tests (test/Cloudflare/Workers/URL.test.ts, all passing): effectful yield* Worker.URL, async env: { PUBLIC_URL: Worker.URL }, and a Vite fixture asserting both the build-time inline and the runtime binding equal worker.url.

Docs: new @section on the Worker typedoc, ## The Worker's own URL in the Workers guide, ### The site's own URL in the Vite guide, and a note in the Vite SPA guide's URL-injection section.

🤖 Generated with Claude Code

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@alchemy-version-bot

alchemy-version-bot Bot commented Jul 27, 2026 •

Copy link
Copy Markdown
Contributor

Install the packages built from this commit:

alchemy

bun add alchemy@https://pkg.ing/alchemy/c4e71d4

@alchemy.run/better-auth

bun add @alchemy.run/better-auth@https://pkg.ing/@alchemy.run/better-auth/c4e71d4

@alchemy.run/pr-package

bun add @alchemy.run/pr-package@https://pkg.ing/@alchemy.run/pr-package/c4e71d4

sam-goodwin and others added 2 commits July 27, 2026 15:07
…ted tag

The bare-yield/env ergonomics come free from the existing Binding value
machinery — no Symbol.iterator overrides, no IIFE. isSelfUrl is structural
(kind only) because the engine strips binding-value methods when resolving
props for providers.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…e or layer

Follows the WorkerLoader pattern: a real Effect carrying the ~alchemy/Kind
marker, yieldable in effectful workers (no Effect.provide needed) and
declarable on env. Defined inside Worker.ts — a separate URL.ts module forms
a value cycle with Worker.ts that the deploy bundler's scope hoisting turns
into a script-startup crash (verified: same code inlined works, module split
1101s in cloud while local dev's entry tolerates it).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@sam-goodwin
sam-goodwin merged commit ff3bd99 into main Jul 27, 2026
9 checks passed
@sam-goodwin
sam-goodwin deleted the claude/worker-url-binding-f284a6 branch July 27, 2026 22:51
sam-goodwin added a commit that referenced this pull request Jul 28, 2026
Resolves Worker.ts / WorkerProvider.ts conflicts (Worker.URL #964 landed
alongside the version prop) and rejects Worker.URL bindings on version
workers — a version's URL is its preview URL, which only exists after
upload. Distilled submodule resolves to main's pointer, which already
contains distilled#389.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
john-royal added a commit that referenced this pull request Jul 30, 2026
Brings in 94 commits from main (local vs live provider modes #963,
workersDev/domain props #977, Worker.URL self-binding #964, assets-only
Workers #969, Prisma provider #416, version affinity #985, telemetry
#860) while preserving this branch's SourceProvider architecture and
Website framework integrations.

- Worker providers take main's side wholesale; the SourceProvider
  integration is re-grafted as a dispatch: `props.source` routes through
  `resolveSource`/`loadSource` (build, hash slots, and local dev in both
  server and bundle modes via the make-before-break serve path), while
  script/vite/python/prebuilt/assets-only workers keep main's paths.
- Apply.ts: both sides landed the resolved-bindings persistence fix
  (#874 / ef08f4c); merged as the union, keeping `providerMode` and
  `bindings` on replaced-state commits.
- test Utils/Http.ts: keep main's generalized retryResponse machinery
  (expectUrlRedirect/expectUrlHeader) and re-add expectDirectStatus on
  top of it.
- Website tests track main's API: `url`/`subdomain` props fold into
  `workersDev`; dev-mode R2 cleanup skips virtual `dev:` buckets.
- cloudflare-tools submodule bumped to this branch's merge of its own
  upstream main (59c3861); distilled synced to main's pointer.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.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.

No way to attach a container to a Durable Object declared on an async (non-Effect) Worker

1 participant