Document ctx.props, ctx.exports, and worker-loader. #25303
Merged
+434
−3
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
kentonv
requested review from
a team,
GregBrimble,
Oxyjun,
WalshyDev,
elithrar,
harshil1712,
joshthoward,
kodster28,
korinne,
mikenomitch and
vy-ton
as code owners
github-actions
bot
added
product:durable-objects
|
This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:
|
|
I feel like this is tucking some very important stuff into the "context" page which previously didn't matter that much. We probably want more of an overview somewhere but I don't really have a sense of where to put that or how to structure it. |
github-actions
bot
assigned
elithrar,
harshil1712,
joshthoward,
mikenomitch,
Oxyjun,
vy-ton,
GregBrimble,
irvinebroque and
kodster28
6 tasks
irvinebroque
approved these changes
Sep 23, 2025
joshthoward
approved these changes
Sep 24, 2025
penalosa
reviewed
Sep 24, 2025
And added some final tweaks. Leaving worker-loader out of changelog for now since it's closed beta.
kentonv
force-pushed
the
kenton/dynamic-worker-loading
branch
from
39aac82 to
dbc1630
Compare
irvinebroque
approved these changes
Sep 25, 2025
| date: 2025-09-26 | ||
| --- | ||
|
|
||
| The [`ctx.exports` API](/workers/runtime-apis/context/#exports) contains automatically-configured bindings corresponding to your Worker's top-level exports. For each top-level export extending `WorkerEntrypoint`, `ctx.exports` will contain a [Service Binding](/workers/runtime-apis/bindings/service-bindings) by the same name, and for each export extending `DurableObject` (and for which storage has been configured via a [migration](/durable-objects/reference/durable-objects-migrations/)), `ctx.exports` will contain a [Durable Object namespace binding](/durable-objects/api/namespace/). This means you no longer have to configure these bindings explicitly in `wrangler.jsonc`/`wrangler.toml`. |
There was a problem hiding this comment.
copy over this code snippet?
so that the reader can read the code snippet and "get it" faster?
There was a problem hiding this comment.
Could do before/after
Before:
example codeAfter:
<less config / zero config>
example code
There was a problem hiding this comment.
Copied the example, not really feeling how to do before/after.
|
|
||
| Loads a Worker with the given ID. | ||
|
|
||
| As a convenience, the loader implements basic caching of isolates: If this loader has already been used to load a Worker with the same ID in the past, and that Worker's isolate is still resident in memory, then the existing Worker will be returned, and the callback will not be called. When an isolate has not been used in a while, the system will discard it automatically, and then the next attempt to get the same ID will have to load it again. If you frequently run the same code, you should use the same ID in order to get automatic caching. On the other hand, if the code you load is different every time, you can provide a random ID. Note that if your code has many versions, each version will need a unique ID, as there is no way to explicitly evict a previous version. |
There was a problem hiding this comment.
Suggested change
| As a convenience, the loader implements basic caching of isolates: If this loader has already been used to load a Worker with the same ID in the past, and that Worker's isolate is still resident in memory, then the existing Worker will be returned, and the callback will not be called. When an isolate has not been used in a while, the system will discard it automatically, and then the next attempt to get the same ID will have to load it again. If you frequently run the same code, you should use the same ID in order to get automatic caching. On the other hand, if the code you load is different every time, you can provide a random ID. Note that if your code has many versions, each version will need a unique ID, as there is no way to explicitly evict a previous version. | |
| As a convenience, the loader implements basic caching of isolates: If this loader has already been used to load a Worker with the same ID in the past, and that Worker's isolate is still resident in memory, then the existing Worker will be returned, and the callback will not be called. When an isolate has not been used in a while, the system will discard it automatically, and then the next attempt to get the same ID will have to load it again. | |
| This means that anytime you update any value returned by the callback (the isolate's code and its configuration), you must use a different ID if you need to guarantee that the updated values will be used. | |
| Best practices: | |
| - If you frequently run the same code with the same configuration provided in the callback, you should use the same ID in order to get automatic caching. | |
| - If the code or configuration you load is different every time, you should provide a random ID. | |
| Note that if your code has many versions, each version will need a unique ID, as there is no way to explicitly evict a previous version. |
Thinking about ways to be explicit to people that this means not just that if the code changes you need new ID, but that if the config provided via the callback changes, you also need new ID...
There was a problem hiding this comment.
riffing on how to be super clear about this...can take or leave language
There was a problem hiding this comment.
At the same time as you were suggesting this I was tweaking my own text a bit, but now I gotta run, so I'll come back and see if I can merge yours and mine later.
There was a problem hiding this comment.
OK I rewrote this section again, I think it's clearer now, hopefully.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
12 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
Documentation for the still-experimental Dynamic Worker Loading feature, as well as
ctx.props(which has been around a while, undocumented) andctx.exports(which will hopefully be unflagged "experimental" soon).Documentation checklist