Skip to content

Commit 18a21dd

Browse files
authored
Clarify guide around implementing experimental node.js apis (#3383)
1 parent b982f8b commit 18a21dd

File tree

1 file changed

+2
-0
lines changed

1 file changed

+2
-0
lines changed

src/node/README.md

+2
Original file line numberDiff line numberDiff line change
@@ -19,3 +19,5 @@
1919
1. We will seek to prioritize implementation of Node.js APIs that are needed by npm modules and other ecosystem dependencies that our customers want and are trying to use. When those modules require Node.js core APIs, we will implement those in accordance with this framework. In some cases that may mean it will not be possible to support the module as written. Like the Node.js APIs themselves, support will be best-effort. When we cannot fully implement support for these modules directly in the runtime, we will attempt to work with the maintainers of those modules to implement a workers-compatible alternative or work to develop alternative workarounds.
2020

2121
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.
22+
23+
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.

0 commit comments

Comments
 (0)