<script type=worker>: the worker element

Try it

<iframe src=:hello></iframe>
<script type=worker edge>
  export default {
    fetch: request => new Response(`Hello from ${new URL(request.url).pathname}`)
  }
</script>

The iframe asks for :hello. The worker sees /hello and answers Hello from /hello. In the playground, GET / always returns your page, and the : prefix reaches the worker for any path, the root included, in the playground and on RTEdge.net. See Calling the worker.

Attributes

This element includes the global attributes. The attributes below control how the worker runs. edge, fetch, io:host and io:fail are read from the first worker script only, so put them there; the copies on later worker scripts are ignored.

type

Must be worker. Browsers do not execute this type, so the element stays an inert part of the output document.

edge

A boolean attribute, accepted with any value. It deploys the script to RTEdge.net as the worker of the route. Worker scripts without edge run only in the playground, and a deployment with no edge script has no worker. In the playground, edge does not change how the code runs: edge and non-edge scripts run together.

fetch Deprecated Playground only

The name of the top-level binding that is the handler of a classic-script worker. The default is response. Use export default { fetch } instead; see the legacy form.

io:host Playground only

A space-separated list of hosts whose requests from the output the worker answers, usually to mock a third-party API. * means every host. RTEdge.net ignores it. See Mocking third-party APIs.

io:fail Playground only

What happens when the worker fails. open forwards the original request to the network. Any other value, or no value, is closed, the default. RTEdge.net ignores it. See Failing open or closed.

io:guest

Keeps the source of the deployment public. A deployment with an edge worker has a private source, which only you, your editors and io:user permits may open with ?. The source stays public only if every edge script carries io:guest and nothing else restricts it. See io:guest.

io:user

A list of email addresses, domains or * that may open the source with ?. It is read from every edge script. See io:user.

copy:redact Playground only

An editor feature: the script is masked in the editor, and copying it puts a REDACTED comment on the clipboard. It has no effect on a deployment: the element is served as you wrote it. See copy:redact.

pure Experimental

A boolean attribute that keeps edits to this script from reloading the output. The edit patches the page only, and the service worker keeps the old code until the next full load.

Note: pure is experimental and may change.

src

Never read. Worker code cannot be loaded from a file: write it inside the element, and use static imports for libraries.

Content

JavaScript text and no child elements. The text of every worker script is one program, whether the script has edge or not: the playground joins them with a newline, in document order. A worker script nested inside a <template> is not found.

Usage notes

Several worker scripts are one program

Because the scripts are joined, they must still parse and compile as one program. In particular, two export default statements, even in two different scripts, break every request: only the last one is rewritten as the handler, and the first stays an export statement, which the worker cannot run. Keep one handler, and make the first worker script the edge script.

On RTEdge.net, only the edge scripts are merged, in document order, into the worker of the route. The edge value and the fetch attribute come from the first edge script, while io:user permits are collected from all of them.

In the playground

• The worker runs in the service worker of the output, as a function body: it is not a module. Static import declarations are bundled for you, and the transform handles export default; top-level await, import.meta and dynamic import() do not work.
• The top-level code runs again for each request, and the handler of the first evaluation stays cached, so module-level state persists until the worker source changes.
• An edit to a worker script reloads the output, which sends the new worker to the service worker, unless the script has pure. Each full load clears the playground console and network panels.
• Page scripts can read the source: document.querySelector('script[type=worker]') works in the output document. The output serves your input as it is, so nothing is redacted there.
• Calls to console in worker code appear in the playground console with the 🛎️⚙️ prefix, and the network panel lists every request the worker handled. See Console and network.

On RTEdge.net

• A deploy takes the edge scripts, builds one module and uploads it as the worker of each route. Deploying a page with no edge script deletes the route's existing worker.
• Every <script type=worker>, with or without edge, is blanked out of the served page and replaced by line breaks, so line numbers do not shift. The source opened with ? still contains them.
• The source is private when the deployment has an edge worker without io:guest: only the owner, the editors and io:user permits can open it. Redaction is not secrecy: edge:redact and edge:remove change only the served HTML, and a public source still shows everything. See Keeping secrets out of deployments.
• Static imports are bundled again at every deploy and then frozen, and WebAssembly is extracted at deploy. See Importing modules and WebAssembly.

The rest of the deployed runtime is in The edge worker runtime.

Pitfalls

• Write the handler as export default { fetch … } and nothing else on that object; see Handler forms.
• End the script with a line break, and never end it with a // comment right before </script>.
• Never leave a worker script empty, or holding only import statements, while an output is open.
• Do not await the result of env.KV.open().

Examples

An API called from the page

Requests made with fetch() keep their method, headers and query. request.rt.code is true in the playground.

<pre id=api></pre>
<script type=module>
  api.textContent = JSON.stringify(await fetch(':api/now?tz=UTC').then(r => r.json()), null, 2)
</script>
<script type=worker edge>
  export default {
    fetch: async request => {
      const { pathname, searchParams } = new URL(request.url)
      if (pathname !== '/api/now') return new Response('Not found', { status: 404 })
      return Response.json({ now: new Date().toISOString(), tz: searchParams.get('tz'), playground: request.rt.code === true })
    }
  }
</script>

A playground-only mock

Without edge, the script runs only in the playground. io:host sends the requests for api.example.com to it, and returning nothing lets other requests reach the real host.

<pre id=profile></pre>
<script type=module>
  profile.textContent = JSON.stringify(await fetch('https://api.example.com/v1/users/7').then(r => r.json()))
</script>
<script type=worker io:host=api.example.com>
  export default {
    fetch: async request => {
      const { pathname } = new URL(request.url)
      if (pathname.startsWith('/v1/users/')) return Response.json({ id: +pathname.split('/').at(-1), name: 'Ada' })
    }
  }
</script>

A worker with a public source

With io:guest, anyone can open the source of the deployment with ?, provided no io:user or edge:user restricts it. Without it, an edge worker makes the source private.

<iframe src=:x></iframe>
<script type=worker edge io:guest>
  export default { fetch: r => new Response(r.url) }
</script>

Technical summary

Specifications

Not part of any specification. <script type=worker> is an RTCode.io and RTEdge.net feature. It builds on a script element with an unknown type, which browsers treat as a data block and do not run, on service workers in the playground, and on the Cloudflare Workers runtime on RTEdge.net.

Availability

See also

• The fetch() handler
• Request.rt
• env
• Using workers
• Mocking third-party APIs
• The edge worker runtime
• worker:fs
• edge:user