Node.js APIs match Current release version
Native implementations of Node.js APIs in Workers are intended to match the implementation in the Current release of Node.js, unless otherwise specified.
Cloudflare Workers · Runtime APIs · all subjects
runtime
283 notes in this subject, read out of this brain and free to use. This is page 3 of 5.
Deprecated and experimental Node.js APIs not supported
Deprecated or experimental APIs from Node.js and APIs that do not fit in a serverless context are not included in the supported API list for Workers.
Non-functional stub modules
Some Node.js modules are available as non-functional stubs that can be imported or required but do not provide working implementations. These stubs allow packages that check for module presence to load in Workers, but are not suitable for direct application code use.
path.join() example in Workers
The path.join() method can be used to join multiple path segments. For example, `path.join("/foo", "bar", "baz/asdf", "quux", "..");` returns '/foo/bar/baz/asdf'.
Import Node.js path module in Workers
The Node.js path module can be imported using `import path from "node:path";` in Cloudflare Workers. This module provides utilities for working with file and directory paths.
Node.js Readable stream implementation example
A Node.js-style Readable stream can be created by extending the Readable class and implementing a read() method. The read() method should call push() to emit chunks of data, and push(null) to signal the end of the stream. The example shows creating a Readable from an array of strings: const readable = new Readable({ encoding: "utf8", read() { nextChunk(readable); } });
Node.js Transform stream implementation example
A Node.js-style Transform stream can be created by extending the Transform class and implementing _transform() and _flush() methods. The _transform() method receives chunks and should call this.push() to emit transformed data and cb() to signal completion. The _flush() method is called when the stream ends and can emit final data. Example: class MyTransform extends Transform { constructor() { super({ encoding: "utf8" }); } _transform(chunk, _, cb) { this.push(chunk.toString().toUpperCase()); cb(); } _flush(cb) { this.push("\n"); cb(); } }
Node.js stream pipeline for chaining streams
The pipeline() function from node:stream/promises can be used to chain streams together. It handles connecting readable and transform streams in sequence. Example: await pipeline(readable, transform);
Node.js stream consumer text() function
The text() function from node:stream/consumers can be used to convert a stream into a string. It awaits all chunks from a stream and returns them as text. Example: return new Response(await text(transform));
Complete Node.js streams example in Workers
import { Readable, Transform } from "node:stream"; import { text } from "node:stream/consumers"; import { pipeline } from "node:stream/promises"; class MyTransform extends Transform { constructor() { super({ encoding: "utf8" }); } _transform(chunk, _, cb) { this.push(chunk.toString().toUpperCase()); cb(); } _flush(cb) { this.push("\n"); cb(); } } export default { async fetch() { const chunks = [ "hello ", "from ", "the ", "wonderful ", "world ", "of ", "node.js ", "streams!", ]; function nextChunk(readable) { readable.push(chunks.shift()); if (chunks.length === 0) readable.push(null); else queueMicrotask(() => nextChunk(readable)); } const readable = new Readable({ encoding: "utf8", read() { nextChunk(readable); }, }); const transform = new MyTransform(); await pipeline(readable, transform); return new Response(await text(transform)); }, };
Node.js streams API in Workers
The Node.js streams API is available in Cloudflare Workers for working with streaming data. Streams can be readable, writable, or both. All streams are instances of EventEmitter. The WHATWG standard Web Streams API should be preferred when possible.
process.nextTick example
import { env, nextTick } from "node:process"; env["FOO"] = "bar"; console.log(env["FOO"]); // Prints: bar nextTick(() => { console.log("next tick"); });
process module Node.js compatibility
The process module in Node.js provides APIs related to the current process. Initially Workers only supported nextTick, env, exit, getBuiltinModule, platform and features on process. The enable_nodejs_process_v2 compatibility flag updates process to include most Node.js process features.
process.env in Workers
In Workers, there is no process-level environment, so by default process.env is an empty object. You can set and get values from process.env, and those will be globally persistent for all Workers running in the same isolate and context. When Node.js compatibility is enabled and the nodejs_compat_populate_process_env compatibility flag is set (enabled by default for compatibility dates on or after 2025-04-01), process.env will contain any environment variables, secrets, or version metadata that has been configured on your Worker. Setting any value on process.env will coerce that value into a string.
process.env.NODE_ENV static replacement
When using Wrangler or the Cloudflare Vite plugin, process.env.NODE_ENV is statically replaced at build time and is not a runtime value.
Import env from cloudflare:workers
Instead of using process.env, you can import env from cloudflare:workers to access environment variables and all other bindings from anywhere in your code. It is strongly recommended that you do not replace the entire process.env object with the cloudflare env object, as this will cause you to lose any environment variables that were set previously and will cause unexpected behavior for other Workers running in the same isolate.
process.nextTick implementation
The Workers implementation of process.nextTick() is a wrapper for the standard Web Platform API queueMicrotask().
process.stdout and process.stderr streams
process.stdout and process.stderr are supported as non-TTY writable streams, which output to normal logging output with stdout: and stderr: prefixing. The line buffer stores writes to stdout or stderr until either a newline character \n is encountered or until the next microtask, when the log is then flushed to the output.
process.stdin stream
process.stdin is supported as a readable stream but is treated as an empty readable stream.
process.cwd default value
process.cwd() is the current working directory used as the default path for all filesystem operations, and is initialized to /bundle.
process.chdir allows modifying cwd
process.chdir() allows modifying the current working directory and is respected by FS operations when using enable_nodejs_fs_module.
process.hrtime high-resolution timer
process.hrtime is available as a high-resolution timer but provides an inaccurate timer for compatibility only.
nodejs_compat_populate_process_env compatibility flag
The nodejs_compat_populate_process_env compatibility flag is enabled by default for compatibility dates on or after 2025-04-01. When enabled with Node.js compatibility, process.env will contain any environment variables, secrets, or version metadata configured on your Worker.
StringDecoder usage example with buffer decoding
Example showing StringDecoder usage: const { StringDecoder } = require("node:string_decoder"); const decoder = new StringDecoder("utf8"); const cent = Buffer.from([0xc2, 0xa2]); console.log(decoder.write(cent)); const euro = Buffer.from([0xe2, 0x82, 0xac]); console.log(decoder.write(euro));
StringDecoder import syntax
StringDecoder can be imported from the node:string_decoder module using const { StringDecoder } = require("node:string_decoder").
StringDecoder available in Workers runtime
The node:string_decoder module is available in Cloudflare Workers for compatibility with existing npm packages. StringDecoder is a legacy utility module that predates the WHATWG standard TextEncoder and TextDecoder API. In most cases, TextEncoder and TextDecoder should be used instead of StringDecoder.
Create mock function with mock.fn()
Use mock.fn() to create a mock function that records how many times it was called and what arguments were passed. The call count is accessed via fn.mock.callCount() and arguments are available in fn.mock.calls[0].arguments.
MockTracker API available in Workers
The MockTracker API from Node.js test module is available in Cloudflare Workers for tracking and managing mock objects in test environments. It allows creating mock functions and recording their call count and arguments.
MockTracker mock timers API not implemented
The Workers implementation of MockTracker currently does not include the Node.js mock timers API.
MockTracker API example
Example of using MockTracker: import { mock } from 'node:test'; const fn = mock.fn(); fn(1,2,3); console.log(fn.mock.callCount()); console.log(fn.mock.calls[0].arguments);
Supported tls APIs in Workers
The following APIs from node:tls are available in Cloudflare Workers: connect, TLSSocket, checkServerIdentity, and createSecureContext.
tls.connect example with certificate options
Example showing how to use tls.connect with connection options containing key and cert from environment variables, with socket event handlers for 'data' and 'end' events: ```js import { connect } from "node:tls"; const connectionOptions = { key: env.KEY, cert: env.CERT }; const socket = connect(url, connectionOptions, () => { if (socket.authorized) { console.log("Connection authorized"); } }); socket.on("data", (data) => { console.log(data); }); socket.on("end", () => { console.log("server ends connection"); }); ```
Node.js tls module available in Workers
The node:tls module can be imported and used in Cloudflare Workers to create secure TLS connections to external services using Transport Layer Security.
Unsupported tls APIs in Workers
Server-side tls APIs including tls.Server and tls.createServer are not supported in Cloudflare Workers and will throw a 'Not implemented' error when called.
Timer security restrictions in Workers
Due to security-based restrictions on timers in Workers, timers are limited to returning the time of the last I/O. This means that while setTimeout, setInterval, and setImmediate will defer function execution until after other events have run, they will not delay them for the full time specified.
Global timer functions vs node:timers module behavior
When called from a global level on globalThis, functions such as clearTimeout and setTimeout will respect web standards rather than Node.js-specific functionality. For complete Node.js compatibility, you must call functions from the node:timers module.
Node.js timers example with setImmediate
The following example demonstrates using node:timers to schedule functions: ```ts import timers from "node:timers"; export default { async fetch(): Promise<Response> { console.log("first"); const { promise: promise1, resolve: resolve1 } = Promise.withResolvers<void>(); const { promise: promise2, resolve: resolve2 } = Promise.withResolvers<void>(); timers.setTimeout(() => { console.log("last"); resolve1(); }, 10); timers.setTimeout(() => { console.log("next"); resolve2(); }); await Promise.all([promise1, promise2]); return new Response("ok"); } } satisfies ExportedHandler<Env>; ``` This example imports node:timers and uses setTimeout to schedule callbacks that resolve promises.
setTimeout, setInterval, setImmediate Node.js APIs in Workers
Cloudflare Workers support the node:timers module which includes setTimeout for calling a function after a delay, setInterval for calling a function repeatedly, and setImmediate for calling a function in the next iteration of the event loop. These must be imported from the node:timers module for full Node.js compatibility.
domainToASCII function
domainToASCII() returns the Punycode ASCII serialization of a domain. If the domain is invalid, it returns an empty string. It is imported from 'node:url'. Example: domainToASCII('español.com') returns 'xn--espaol-zwa.com', domainToASCII('中文.com') returns 'xn--fiq228c.com', and domainToASCII('xn--iñvalid.com') returns an empty string.
domainToUnicode function
domainToUnicode() returns the Unicode serialization of a domain. If the domain is invalid, it returns an empty string. It performs the inverse operation to domainToASCII(). It is imported from 'node:url'. Example: domainToUnicode('xn--espaol-zwa.com') returns 'español.com', domainToUnicode('xn--fiq228c.com') returns '中文.com', and domainToUnicode('xn--iñvalid.com') returns an empty string.
node:zlib module import
The node:zlib module is available in Workers and provides compression functionality. It can be imported with: import zlib from "node:zlib";
node:zlib compression algorithms
The node:zlib module supports three compression algorithms: Gzip, Deflate/Inflate, and Brotli.
node:zlib API documentation reference
The node:zlib module implements the Node.js zlib API as documented at https://nodejs.org/api/zlib.html. Workers support the full node:zlib API.
promisify example with callback function
import { promisify } from "node:util"; function foo(args, callback) { try { callback(null, 1); } catch (err) { // Errors are emitted to the callback via the first argument. callback(err); } } const promisifiedFoo = promisify(foo); await promisifiedFoo(args);
util.types API for type checking
The util.types API from node:util provides methods to check if values are instances of built-in types. Available methods include isAnyArrayBuffer(), isArrayBufferView(), isArgumentsObject(), isAsyncFunction(), and others.
util.types examples for type checking
import { types } from "node:util"; types.isAnyArrayBuffer(new ArrayBuffer()); // Returns true types.isAnyArrayBuffer(new SharedArrayBuffer()); // Returns true types.isArrayBufferView(new Int8Array()); // true types.isArrayBufferView(Buffer.from("hello world")); // true types.isArrayBufferView(new DataView(new ArrayBuffer(16))); // true types.isArrayBufferView(new ArrayBuffer()); // false function foo() { types.isArgumentsObject(arguments); // Returns true } types.isAsyncFunction(function foo() {}); // Returns false types.isAsyncFunction(async function foo() {}); // Returns true
util.types APIs not implemented in Workers
The Workers implementation does not provide util.types.isExternal(), util.types.isProxy(), util.types.isKeyObject(), or util.types.isWebAssemblyCompiledModule().
util.MIMEType for working with MIME types
util.MIMEType from node:util provides convenience methods to work with and manipulate MIME types. It includes properties like type, subtype, and essence for parsing and accessing MIME type components.
util.MIMEType example
import { MIMEType } from "node:util"; const myMIME = new MIMEType("text/javascript;key=value"); console.log(myMIME.type); // Prints: text console.log(myMIME.essence); // Prints: text/javascript console.log(myMIME.subtype); // Prints: javascript console.log(String(myMIME)); // Prints: application/javascript;key=value
promisify function converts callback to Promise
The promisify method from node:util allows taking a Node.js-style callback function and converting it into a Promise-returning async function. Node.js-style callbacks follow the pattern where errors are passed as the first argument and the result as the second argument.
callbackify function converts Promise to callback
The callbackify function from node:util converts a Promise-returning async function into a Node.js-style callback function. The resulting function accepts arguments followed by a callback with the signature (err, value) => {}.
callbackify example with async function
import { callbackify } from 'node:util'; async function foo(args) { throw new Error('boom'); } const callbackifiedFoo = callbackify(foo); callbackifiedFoo(args, (err, value) => { if (err) throw err; });
performance.timeOrigin returns 0 in Workers runtime
The performance.timeOrigin read-only property returns 0 in the Workers runtime and serves as a baseline timestamp for other measurements.
performance.now() returns milliseconds since performance.timeOrigin
The performance.now() method returns a timestamp in milliseconds representing the time elapsed since performance.timeOrigin.
performance.now() only advances after I/O occurs in production
When Workers are deployed to Cloudflare, performance.now() and Date.now() only advance or increment after I/O occurs. This is a security measure to mitigate against Spectre attacks. CPU-only operations without I/O will show zero elapsed time.
Measure subrequest timing with performance.now()
You can measure the timing of a subrequest, KV fetch, R2 object retrieval, or any I/O operation by wrapping it with performance.now() or Date.now() calls before and after the operation.
performance.now() advances for CPU work in local development
In local development using Wrangler with the workerd runtime, timers increment regardless of whether I/O happens or not, allowing you to measure CPU-intensive operations.
CPU-only work shows zero timing in production
When a Worker performs expensive CPU-only work without I/O between performance.now() calls, the timing measurement will be 0 milliseconds in production.
Explicit Resource Management with `using` declaration
The `using` declaration is a Stage 3 TC39 proposal that allows explicit signaling of resource disposal. When a variable is declared with `using`, the variable's disposer is automatically invoked when the variable goes out of scope. Wrangler v4+ supports the `using` keyword natively. For earlier versions, resources must be disposed manually. The `using` declaration ensures resources are disposed even if code is interrupted by an exception. When a stub is declared with `using`, it is equivalent to wrapping the code in a try-finally block that calls `symbol.dispose()` in the finally clause.
wrangler types output file name
The wrangler types command produces a worker-configuration.d.ts file that includes typed bindings for Service and DurableObjectNamespace.