import { Callout } from 'nextra-theme-docs'
The @edge-runtime/node-utils package contains utilities to run web compliant code into a Node.js environment.
npm install @edge-runtime/node-utils
This package includes built-in TypeScript support.
import { once } = from 'node:events'
import { createServer } from 'node:http'
import { buildToNodeHandler } from '@edge-runtime/node-utils'
// 1. builds a transformer, using Node.js@18 globals, and a base url for URL constructor.
const transformToNode = buildToNodeHandler(global, {
defaultOrigin: 'http://example.com',
})
const server = await createServer(
// 2. takes an web compliant request handler, that uses Web globals like Request and Response,
// and turn it into a Node.js compliant request handler.
transformToNode(async (req: Request) => new Response(req.body))
)
// 3. start the node.js server
server.listen()
await once(server, 'listening')
// 4. invoke the request handler
const response = await fetch(
`http://localhost:${(server.address() as AddressInfo).port}`,
{ method: 'POST', body: 'hello world' }
)
console.log(await response.text()) // is 'hello world'
await server.close()
Builds a transformer function to turn an web compliant request handler:
(req: Request) => Promise<Response> | Response | null | undefined`
into a Node.js compliant request handler:
(req: IncomingMessage, res: ServerResponse) => Promise<void> | void
Limitation: it does support the web handler second parameter, so waitUntil
is not implemented yet.
List of Web globals used by the transformer function:
When running in Node.js 18+ (or Node.js 16 with --experimental-fetch), you may pass the ones from global
scope.
import { buildToNodeHandler } from '@edge-runtime/node-utils'
buildToNodeHandler(globals, {
/* ... options */
})
Otherwise, you can reuse primitives from @edge-runtime/primitives
import { buildToNodeHandler } from '@edge-runtime/node-utils'
import * as primitives from '@edge-runtime/primitives'
buildToNodeHandler(primitives, {
/* ... options */
})
Options used to build the transformer function, including:
The incoming host
header is used when turning the incoming request relative url into a full Request.url string.
In case no host is provided, this default origin will be used instead.
buildToRequest(dependencies, options): toRequest(request: IncomingMessage, options: object): Request
Builds a transformer function to turn a Node.js IncomingMessage into a Web [Request]. It needs globals Web contstructor a dependencies, as well as options to handle incoming url.
Builds a transformer function to build a fetch event from a web [Request]. The returned event is linked to provided request, and has a mocked waitUntil() method, which throws on access.
It needs globals Web constructor a dependencies.
Turns Web Request.headers into
Node.js ServerResponse
OutgoingHttpHeaders.
Includes set-cookie
special handling, splitting multiple values when relevant.
Builds a transformer to turn Node.js IncomingHttpHeaders into Web Request.headers.
Turns Web ReadableStream (typically, the Response.body) into Node.js Readable stream.
Builds a transformer to turn Node.js Readable (typically, the IncomingMessage's payload) into Web ReadableStream.