Initial Proposal

[Ethan-Arrowood]

This PR adds the initial proposal.

Before this is merged, we need to seek approval from the various runtimes represented in this initial draft. The following list matches the list of keys included in this initial draft. Each runtime is either linked to a discussion/issues/post requesting approval from the relative project, or someone apart of WinterCG who can represent the runtime is tagged.

• [x] Cloudflare workerd - @jasnell
• [x] Deno Land deno - @lucacasonato
• [x] Meta React Native
• [x] Netlify - @ascorbic
• [x] Electron - reached out by @Ethan-Arrowood
• [x] Node.js
• [x] Oven Bun - reached out by @Ethan-Arrowood
• [x] Vercel Edge Light - @Ethan-Arrowood

[QuiiBz]

Using edge as a key for Vercel Edge Runtime might be confusing for users. The word « Edge » is used in many projects including Cloudflare Workers, Deno Deploy, and Vercel Edge Runtime. A user might think that everything with « Edge » in its marketing should have the edge runtime key, which won’t be the case unless he uses the Vercel Edge Runtime. Maybe a more specific key like vercel would make more sense?

[Ethan-Arrowood]

A user might think that everything with « Edge » in its marketing should have the edge runtime key

This is almost exactly why we are creating this proposal 😄 It is currently ambiguous and vague what folks should be using. And since it is not standardized every tooling makes up its own rules. Node says you can use a variety of keys, Webpack has its own list, etc.

By listing them here, and encouraging tools to adopt this standard, at least there will be no more confusion and vagueness.

While yes "edge" is a commonly used word in this space, no other runtime is branding and marketing itself as Vercel's Edge Runtime is and it was what was decided upon internally at Vercel. If there is hard push back from the group, I will bring the feedback back to Vercel for discussion.

[Ethan-Arrowood]

I'll go ahead and add a stub now! Do we have anyone from Netlify involved in WinterCG? Anyone specific I should reach out too? Otherwise, I will open a discussion thread like I did for React Native

[lucacasonato]

I'll get you someone.

I also have concerns about using "edge" as the key for Vercel Edge Runtime. Edge is not a name unique to Vercel. There are many other products with edge in the name, so this may get very confusing. I think we need something more specific. An arbitrarily chosen list of other runtimes with Edge in the name:

• Lambda@Edge
• Netlify Edge
• Vercel Edge Network (not the same thing as Vercel Edge Runtime AFAICT)
• Netlify Edge Functions (not the same thing as Netlify Edge Functions)
• Google Distributed Cloud Edge
• Microsoft Edge

Then there are also other products that use "edge" as a concept in marketing material:

• Cloudflare Workers
• Deno Deploy

[Ethan-Arrowood]

What about individual browsers?

Since the browsers wouldn't necessarily be concerned with what we are working towards here in WinterCG it could be weird to have them on the list. I think generally, we are trying to create the list of server runtimes so that we can leverage the same tooling browsers have benefited from (i.e. browserlist) previously.

[ljharb]

Sure - but we'd still want to make sure that server runtime keys didn't conflict with what users might want to name their browsers, and it seems the simplest way to do that is to include them here?

[Ethan-Arrowood]

didn't conflict with what users might want to name their browsers, and it seems the simplest way to do that is to include them here?

Good point! Is there an existing standard for those browser identifiers? My assumption is that the tooling we are looking to improve with this key set is currently not concerned with specific browser bundles. Like even Webpack only has a browser key for representing browsers as a target environment.

[ljharb]

The closest is likely https://github.com/browserslist/browserslist

[Ethan-Arrowood]

Instead of having browsers in the list, we add some text to also avoid conflicting with browsers defined in browserlist to prevent tooling conflicts. This way we aren't responsible for getting any sort of browser buy-in or maintenance

[ljharb]

That sounds perfectly reasonable!

[jasnell]

@Ethan-Arrowood ... let's not list anyone next to the Node.js slot in this list since the TSC has never formally decided that Node.js has any official representation here. Those of us here who contribute to Node.js cannot say that we are representing the project as a whole.

[jasnell]

To be clear, my sign off on this PR is from my POV as representing cloudflare workerd, not Node.js

[Ethan-Arrowood]

Okay removed myself. I was planning on opening an discussion in the tooling group anyways so i'll link to that instead when I do. Luckily, they should be an easy one as node is already documented, supported, and known (and no one else is using that branding).

[Ethan-Arrowood]

Does anyone have more input into the criteria for being on this list? I've intentionally left that section vague since there is value in not having a large set of restrictive rules (so any runtime can be included), but I can also see some value in setting stricter expectations.

Some things that come to mind are:

• runtime availability
  • is it open sourced?
  • is there available documentation for what the runtime defines as part of its API?
• legitimacy
  • representative marketing & branding
  • does it actually exist?
  • like is the runtime more than just a pet project someone threw some catchy name in front of?
  • does it have some resemblance of a community? chat/forum/support channels
  • is it backed by any entity other than individual efforts? I.e. corporate, organization (such as OpenJS Foundation)

I'm not proposing that we need to set more than what I've written so far, but want to share the thought so it can be discussed 😄

[sheplu]

I think we should have some restricting rules - at least some basics one. I am not sure that if I build a runtime only for me / private it is interesting to have it listed here. open sourced seems a bit much but I think publicly available seems a good fit

[ascorbic]

Thanks @Ethan-Arrowood for the invite. I think we would agree that netlify is the best idea for the key for Netlify Edge Functions. I would echo @lucacasonato's comments about the use of edge for Vercel, and would suggest vercel instead. If you would rather qualify it as something like vercel-edge then I think it would make sense for Netlify to follow the same convention and use netlify-edge.

[QuiiBz]

Agree with @ascorbic. As I said earlier, edge by itself can mean a lot of different things and is commonly used in different products from different companies (see this comment).

These keys should be easy to remember and self-explanatory. Using the same naming as above with the full product name alongside makes it very clear:

• Netlify Edge Functions -> netlify-edge
• Vercel Edge Runtime -> vercel-edge

[Ethan-Arrowood]

Hi folks, revisiting Vercel's choice for runtime key, we would like to proceed with an alternative: edge-runtime. We agree that edge may be too broad (akin to browser). The product is marketed and branded as Edge Runtime consistently across multiple places, and even uses the edge-runtime npm package as well as the @edge-runtime npm org for packages.

See these resources for examples of the associated branding:

• https://vercel.com/blog/introducing-the-edge-runtime
• https://github.com/vercel/edge-runtime
• https://www.npmjs.com/package/edge-runtime
• https://edge-runtime.vercel.app/

Thank you for constructively highlighting concerns with the original key choice 😄

[ascorbic]

I still think that is too generic @Ethan-Arrowood. Adding "runtime" doesn't help, because these are all runtimes.

[rauchg]

Hey folks, that's how the product is branded, and @Ethan-Arrowood has supplied several links of evidence. @ascorbic in your own website you're validating the use of "edge runtime" (which is an opensource specification), and you contrast it with your own product "Netlify Edge Functions":

This opensource project is not called "Vercel Edge Runtime", like Bun is not called "Oven Bun" or Deno the runtime is not called "Deno Deno".

This is how you install it:

The "runtime" part is part of its brand, not just something to be clarified.

[jasnell]

I'm +1 on edge-runtime for vercel.

[lucacasonato]

I unfortunately can not sign off on "edge-runtime". As I have elaborated to @Ethan-Arrowood privately, we brand Deno and Deno Deploy as an edge runtime - as such our customers understand "edge runtime" to be a class of runtimes (runtimes executing on the edge).

I do not agree with your point about naming @rauchg. Deno and Bun are names that can stand by themselves without further clarification because they are brands. They are not a generic term. If Deno was called "JavaScript runtime", we could not refer to it as "JavaScript runtime" without further qualifying that it was the "Deno JavaScript runtime", or "JavaScript runtime by Deno" - if we didn't this would be highly confusing. "Edge runtime" is a generic term, because it is a class of products. There are multiple products that describe themselves as an "edge runtime" (runtimes for the edge).

Because "edge runtimes" is a class of products, calling any individual product "edge runtime" without further qualification is confusing. In the context of a standards group that has members from multiple other companies that each have products in this class, this is even more so the case.

[jasnell]

Ah, the age old problem about there being only four difficult problems in software: (1) naming things, (2) timestamps, and (3) off-by-one errors.

The challenge here is not dissimilar to Cloudflare Workers, and we discussed this. Using just workers as a key is too generic because there are many platforms that could refer to. Fortunately, we came up with workerd for the open source runtime and that just happens to fit fine.

@rauchg ... quick question: is edge-runtime or Edge Runtime trademarked by Vercel in any way? Similar to Deno, Bun, or Node.js being trademarks? If not, while I personally am fine with edge-runtime referring to Vercel's stuff, I do see the argument that if some other company comes up with Foo, Inc. Edge Runtime, then just saying edge-runtime is not specific enough to ensure that users are not confused.

Perhaps there is a compromise here that can be found? Let's, perhaps, throw some options on the table and see what consensus we can build around each?

Either way, to unblock this, if we don't have consensus here by the next wintercg call, we'll put this on the call agenda and have a call for consensus there to make a decision.

[ascorbic]

in your own website you're validating the use of "edge runtime" (which is an opensource specification), and you contrast it with your own product "Netlify Edge Functions"

@rauchg that is an exactly opposite example. We're using it generically there, specifically because we're not using the "Edge Runtime" package.

As @lucacasonato said, the only reason we're saying "edge runtime" needs qualification is because it's a generic term that is otherwise ambiguous and confusing.

[sheplu]

I just checked and it seems that if you google edge-runtime only pages owned / linked to vercel are showing (except a think from Microsoft - Edge browser)

So I would agree that this is just two generic name put together, yet npm orgs + vercel package + articles + documentation (on vercel) + others only redirect to vercel To be completely honest, end of page 2 / 3 I got some link to IoT Edge Runtime (from Microsoft)

[lucacasonato]

@sheplu I can not reproduce your results. Even if I could that does not change my argument. The point is that other runtimes and the wider ecosystem have an understanding that "edge runtime" is a class of products, not an individual product. As such no individual product can claim the name "edge runtime" without it being highly confusing.

Do you have personalized Google results enabled? For me the #1 result is a MS WebView related link:

[Ethan-Arrowood]

I have to disagree that "edge-runtime" is too generic. Beyond the fact that it is the actual name of the product (and is used as such throughout many different branding aspects), as @sheplu commented, a search for "edge runtime" (notice lowercase as to not infer a proper name) mainly returns results for the product in question. I have verified this myself using incognito browsers with Google and DuckDuckGo search engines. Aside from some hits for Microsoft pages the use both terms "edge" and "runtime" (but not together as one term), there are no other generic posts returned; in fact most of the resulting hits are for Vercel's Edge Runtime product. Furthermore, the term doesn't even have a Wikipedia page. Contrary to the previous term, "edge", which does in fact return a multitude of other pages, definitions, and more. I feel strongly that this term is not as generic as folks in this thread believe it is.

Vercel is sticking with our selected name "edge-runtime". If others continue to disagree based on this multitude of evidence that the term is not generic enough to warrant confusion and that it doesn't accurately depict our product, then we will move on to a CfC as defined in the groups charter during next weeks call.

[Ethan-Arrowood]

Here are screenshots of proof. These were taken in an incognito fire fox browser instance.

[ljharb]

When I google for edge runtime in quotes, I see lots of vercel/next.js results on the first page, but also a few results for Microsoft/Azure's "edge runtime" (https://learn.microsoft.com/en-us/azure/iot-edge/iot-edge-runtime?view=iotedge-1.4 and https://migration-tool.sharegate.com/hc/en-us/articles/7108233802260-Edge-runtime-installation-failed-Internet-Explorer-deprecation-)

To me, the term is clearly predominantly Vercel/next.js, but it's just as clearly not unique to it.

[ascorbic]

The question isn't whether Vercel's "Edge Runtime" has better SEO. It's whether "edge runtime" is used generically elsewhere and could be confusing, and it quite clearly is and could. A quick check shows its use in the Astro docs to refer to Deno and Cloudflare, @Atinux using it generically to refer to Netlify and @biilmann using it to refer to Netlify's old Edge Handlers runtime. "Edge" is undeniably a generic term in this context and applies to most of the runtimes in question, and so of course is "runtime" (it's in the name of this group and repo). To be honest, it's unfortunate that such a potentially confusing name was used for the product in the first place.

The argument that the key needs to be edge-runtime because that's the name of the product doesn't square with the fact that your initial proposal was to just use edge as the key, and edge-runtime was your follow-up when people pushed back. If you were willing to use a shortened, more generic version of the name, why is it a problem to use a name that has a qualifier to remove the potential for confusion?

[legendecas]

I'm concerned about the term "edge runtime" (i.e. runtimes for the edge) not being unique to a specific runtime too. EdgeRoutine is an Alibaba Cloud product and is marketed as a JavaScript runtime on the edge. We'd find that in the context of a standards group about JavaScript runtimes, adding the suffix "runtime" solely doesn't qualify the term "edge" to be unique to a specific product.

[jacobrask]

Akamai EdgeWorkers is also highly relevant to consider here

[XadillaX]

I'm concerned about the term "edge runtime" (i.e. runtimes for the edge) not being unique to a specific runtime too. EdgeRoutine is an Alibaba Cloud product and is marketed as a JavaScript runtime on the edge. We'd find that in the context of a standards group about JavaScript runtimes, adding the suffix "runtime" solely doesn't qualify the term "edge" to be unique to a specific product.

I agree with @legendecas, edge is a common word for tech.

[rauchg]

I think some context is missing here. What we’re trying to represent is an open source project that acts as a compatibility layer for the edge (with support for workerd, nodejs, deno and more in the future). This is categorically distinct from a platform product like "$Vendor Edge Function".

Even before we started any work on the Vercel side of things, we set out to create this "Edge Runtime" effort. We invested time in creating:

• documentation and spec
• a local CLI
• polyfills and ponyfills
• testing environments

📣 Based on the feedback here, and in contrast to the very goal of the project, we’re going to revisit branding. We will come back to this group in a few days

[ascorbic]

@rauchg that does sound like a worthwhile effort, and aligns with the goal of WinterCG. As I understood it, the OSS package was just meant as a way to run Vercel Edge Functions and Next.js edge runtime etc locally in a Node environment instead of workerd. I didn't understand that it had a broader goal. Thank you for reconsidering the naming, because it is unclear as it stands.

[jacob-ebey]

If "runtime" B is implemented on top of runtime A and doesn't own any of the web-interoperable implementations themselves they should not be included on this list IMO. We do not need any more artificial fragmentation of the ecosystem.

[Ethan-Arrowood]

The purpose of this proposal is to provide a registry of key values so that any web interoperable runtime can have a clear identifier for use with developer tooling and other purposes.

It is not going to dictate how those runtimes are implemented. Even if one runtime is layered on top of another, the two runtimes may need some distinction in the context of developer tooling and thus both belong on this list.

Furthermore, as indicated in the proposal and in discussions in this thread, the WinterCG is intentionally leaving inclusion criteria minimal

[leerob]

@jacob-ebey To clarify: The edge-runtime (or new name) is not a 1:1 mapping of any other runtime mentioned here. Specifically, there’s no Deno global object, Cloudflare APIs, or other runtime global objects like Bun. This is an important distinction – it's a compatibility layer.

[rauchg]

That clarification extends to @ascorbic's question I believe as well. The very idea of edge-runtime is that if you target it, you have the strict subset of truly standard APIs and behavior that we're hoping WinterCG will converge onto.

Hence why we've been careful to stay away from ad-hoc, non-Web APIs like HTMLRewriter (although we certainly will add it if it gets WinterCG support!)

[jacob-ebey]

I don't understand the purpose of proposing these keys in the first place. Seems as though "runtime keys" should be scoped to the concerns of wintercg: implementation of common runtime API's. If company X builds a "runtime" on top of Deno, it's not a new runtime, it's still Deno. If WinterCG introduces a new API, it's Deno that needs to implement it, therefore company X's "runtime" doesn't belong on the list. "where the WinterCG implementation lives" should determine if something deserves a runtime key. The goal isn't "bundler tooling interoperability", it's runtime interoperability, and at no point would runtime code that's interoperable need to check a runtime key.

Just to clarify I'm not talking about "edge-runtime" naming, I'm talking core reason these keys exist.

[verythorough]

If edge-runtime isn't meant to be a vendor platform product, why is the vendor name included in the proposed runtime name?

And if it's meant to be independent, shouldn't it include maintainers (not just contributors) representing multiple parties?

[Ethan-Arrowood]

For folks new to this proposal, the albeit short history started from the idea of how do we expand the usage of engines and exports field in package.json https://github.com/wintercg/admin/issues/36

To summarize that part, there is already developer tooling that lets you specify "my project needs to run in Node version 16+" or "use this file when you run my module in the browser, and this file when you run it in node".

Now that we have so many new runtimes being developed such as Workerd, Deno, Bun, Edge Runtime, etc. we wanted a clear way to define what key can be used to represent those runtimes in these same fields.

The simplest way to do so was to create a proposal that acts as a living registry.

This specification contains the language necessary for the keys to be added, modified, and deprecated over time. It enables developer tooling to build around a defined list just like browserlist was implemented. And most importantly, it acts to prevent multiple runtime projects from having conflicting identifiers.

[jacob-ebey]

Why is it not based off of who owns the implementation / what the actual runtime is? I.e, we are going to continue to see an explosion of cases like the following unless the criteria for being on this list becomes "I own the WinterCG API implementations":

swtich (runtimeKeyProposal) {
  "cloudflare":
  "vendor-a-edge":
  "vendor-b-edge":
    // same
    break;
  "deno":
  "vendor-c-edge":
  "vendor-d-edge":
    // same
    break;
  "bun"
  "vendor-e-edge":
  "vendor-f-edge":
    // same
    break;
  // ...etc
}

I don't need 50 more keys to add to a bundler's "exports" / "imports" configuration.

[Ethan-Arrowood]

That is the benefit of this proposal. It does not dictate how tools need to utilize the list. All it does is specify the registry. It is up to (figuratively) you how you want to use these keys. Are you a tooling author creating a bundler that supports Node, Deno, CF, Bun, and more? Maybe this list and a lengthy export list in package.json is important. Are you a module author creating an library meant to run only in Node? Okay great, specify "node" in your exports and call it a day. Maybe you are a module author creating a library meant to run across node, deno, etc... then you definitely care about this registry so you can precisely specify what export files match with what.

[Ethan-Arrowood]

I will reiterate that we have been very intentional with the language used in the proposal. We do not want to be telling anyone to do anything; we are simply making this information publicly available in the most consistent and openly collaborative way possible. For the overall benefit of all developers working in the budding web runtime space.

[jacob-ebey]

Fair enough. I then ask those on the list to reconsider if they need their own key or fall into an existing key. Specifically if you do not own the WinterCG API's or the module loading system.

[panva]

@jacob-ebey I've made the proposal to also add a catch*all key to represent "any runtime that satistisfies the WinterCG minimal API". Such that runtimes that do just that and nothing on top can rely on that and also that library authors that don't need any specific runtime's API don't need to keep on adding unique vendor specific keys to their declaration files.

[Ethan-Arrowood]

Yes! https://github.com/wintercg/runtime-keys/issues/1 it was actually the very first issue in this repo ✨ We just want to be intentional what "wintercg" would represent. Does it correlate to the latest iteration of the minimum common api spec?

It is something to be discussed and iterated on in the future for sure

[jacob-ebey]

Just want to verify that we are not specifying runtime API compatibility with this, but rather what runtime owns specific keys for "exports" / "imports". Seems outside of the stated goals of WinterCG, or am I still misunderstanding?

[Ethan-Arrowood]

I believe you are misunderstanding. The goal of the Minimum Common API is to specify runtime API compatibility. Other specs and proposals in this group have other goals