Skip to content

docs: document that Web Workers require --allow-read for local scripts#3423

Merged
bartlomieju merged 3 commits into
mainfrom
docs/worker-allow-read
Jul 21, 2026
Merged

docs: document that Web Workers require --allow-read for local scripts#3423
bartlomieju merged 3 commits into
mainfrom
docs/worker-allow-read

Conversation

@bartlomieju

Copy link
Copy Markdown
Member

The permissions reference explains that the entrypoint module and its
statically analyzable import graph are read by default, which is why
deno run script.ts needs no --allow-read. It does not mention that Web
Workers are an exception to this rule, and the Worker API reference only covers
WorkerOptions.deno.permissions (what the worker may do once running), not the
permission required to load the worker script in the first place.

A worker's script is loaded as if it were a dynamic import rather than a static
root, so loading a worker whose script is a local file requires --allow-read.
This is verifiable at runtime: new Worker(new URL("./worker.ts", import.meta.url).href)
run without --allow-read fails with Requires read access to ".../worker.ts".
The requirement covers the worker's entry script and its entire static import
graph, and the read access is checked against the permissions of the thread
that created the worker. Workers loaded from https: URLs require
--allow-import instead, while data: and blob: URLs need no permission.

This adds a bullet to the "During module loading" list in the File system
access section, where the static-analysis read exemption is already described,
and tightens the wording of the related sentence in the "Importing from the
Web" section so the local --allow-read requirement reads clearly alongside
the remote --allow-import one.

Canary broke typechecking of several unrelated example scripts (npm
specifier resolution, 'with { type: bytes }' imports, worker lib globals,
'await using' disposal), turning the lint job red on every PR. Pin the
lint and freshness workflows to the latest stable 2.x release instead.
@bartlomieju
bartlomieju merged commit bcefb75 into main Jul 21, 2026
3 checks passed
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.

1 participant