cloudflare-docs
cloudflare-docs copied to clipboard
cloudflare
Stance on ESM, TS, and Tab Switcher Update
Which Cloudflare product does this pertain to?
Workers
Existing documentation URL(s)
Examples Tutorials Maybe more?
Section that requires update
Code snippets across the Workers Docs and other docs that contain Workers Code Snippets.
What needs to change?
What is the stance on updating all code snippets in the docs to support the ESM format, along with the Service Worker format, with Tab Switcher and TS as needed? Currently, looking at Cloudflare messaging(blogs, new releases, etc.), ESM is targeted as the go-to for all new programs, and Service Workers are only for backward compatibility.
How should it change?
While in some cases, it might be necessary to maintain documentation for users working on old codebases, in general, it seems it would reduce headaches to push people towards the ESM format when at all possible.
Additional information
Note, this is just my personal view, based on what I've seen, so if I am wrong, just let me know.
Also, this isn't a request for a modification per se, this was more meant to clarify the current stance for ESM/TS vs. Service Workers so that I don't make a mongo PR if it isn't necessary.
Also, if this were a PR, would it be better to do it in one big PR or split each tutorial/example edit into its own PR?
I made a slight start (https://github.com/cloudflare/cloudflare-docs/pull/5866) but was blocked by some issues with the Tab Switcher code.
I've put up a PR to fix the Tab Switcher bugs (https://github.com/cloudflare/cloudflare-docs/pull/5867) which should make it a better.
My opinion is that we should provide SW examples, but use default="true" on the ESM examples so that users are 'nudged' towards Module Workers.
I like TypeScript examples but if an example requires ctx but not env, it's a bit weird. Do we just do ExportedHandler<_> and req, _, ctx?
For Workers code, I think it's easier to have 2 toggles:
Modules(default on)TypeScript(default on)
We can to encourage both Modules and TypeScript, since that has a better experience.
If we have tabs for each version -- ESM JS, ESM TS, SW JS, SW TS -- that's an overload of options and it's too messy.
Sounds good, @Electroid. On the point about the number of PRs, would it be easier if each changed code block were its own Pull Request, or having a single large Pull Request for every change?
Sounds good, @Electroid. On the point about the number of PRs, would it be easier if each changed code block were its own Pull Request, or having a single large Pull Request for every change?
Let's do a trial run on a few pages first, then a second PR can do everything.
@Electroid Am I good to go on making the larger PR now, or should wait a bit longer?
this seems like it was closed by #6195, but can be reopened if still needs to be addressed
