Skip to content

Commit

Permalink
Node.js compat guidelines... favor explicit throws for intentionally …
Browse files Browse the repository at this point in the history
…unsupported apis (#3408)
  • Loading branch information
jasnell authored Jan 24, 2025
1 parent 52568fe commit 10eafbc
Showing 1 changed file with 2 additions and 0 deletions.
2 changes: 2 additions & 0 deletions src/node/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

0 comments on commit 10eafbc

Please # to comment.