From 10eafbce8d3fb1371dd31f5967a698fb02269d70 Mon Sep 17 00:00:00 2001 From: James M Snell Date: Fri, 24 Jan 2025 10:23:34 -0800 Subject: [PATCH] Node.js compat guidelines... favor explicit throws for intentionally unsupported apis (#3408) --- src/node/README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/node/README.md b/src/node/README.md index 451ef077973..829a7f63126 100644 --- a/src/node/README.md +++ b/src/node/README.md @@ -21,3 +21,5 @@ 1. Polyfills of Node.js APIs (that is, external implementations that are not bundled directly into the workers runtime) may be leveraged as a last-resort alternative to patch over parts of the Node.js API we choose not to implement in the runtime. When used, these must be generally available for any Workers user, not only those using wrangler. The built-in implementation of Node.js APIs should always take precedence in general but individual workers should be able to BYOI ("bring your own implementation") within the reasonable constraints of the runtime. Cloudflare tooling should never polyfill an API that already exists within the runtime, and the existence of a polyfill implementation will not rule out implementing the API directly in the runtime. 1. Experimental APIs only recently added to Node.js should not be implemented immediately in the workers runtime. Such APIs may be unstable for some time and could cause long term backwards compatibility issues or other unfortunate complexities in the workers runtime due to our "No Breaking Changes Without Compatibility Flags" policy. It is better to allow these APIs to sit and mature a bit in the Node.js runtime to ensure they are stable before being implemented in the workers runtime. Exceptions can be made to address immediate priority use cases. + +1. When a decision is made to explicit *not* implement a particular Node.js API, that decision should be documented. Attempts to use such APIs should result in a runtime error rather than silent failure or silently ignoring.