unenv preset

Azion Lib bundler preset of the @aziontech/unenv-preset package that maps Node.js globals and modules to polyfills for Azion Runtime.

Last updated

View as Markdown Agent setup

The @aziontech/unenv-preset package is the Azion Lib preset for unenv: one configuration object that lists the Node.js globals, modules, and polyfills a build for Azion Runtime replaces. Azion Bundler, which the Azion CLI runs to build a project, applies the preset. The package has no functions to call: a function reaches the polyfills by importing node:* modules, such as node:fs and node:crypto.

Install the package:

npm install @aziontech/unenv-preset

The preset sample on this page is a JavaScript ES module that runs in Node.js. The function samples run inside a function served locally with azion dev. For what node:fs returns in a deployed function, refer to node

.

Preset object

The default export of @aziontech/unenv-preset is the preset object, { inject, alias, external, polyfill }. The package has no named exports, so import { preset } from '@aziontech/unenv-preset' returns undefined. Import the object as the default:

JavaScript
01import preset from '@aziontech/unenv-preset';
02
03// The package has a default export only: { inject, alias, external, polyfill }
04console.log('keys:', Object.keys(preset));
05console.log('inject:', Object.keys(preset.inject));
06console.log('alias:', Object.keys(preset.alias));
07console.log('external:', preset.external);
08console.log('polyfill:', preset.polyfill);

Output:

Text
01keys: [ 'inject', 'alias', 'external', 'polyfill' ]
02inject: [
03 '__dirname',
04 '__filename',
05 'import.meta.url',
06 'process',
07 'performance',
08 'setInterval',
09 'clearInterval',
10 'console',
11 'asyncStorage',
12 'dateToString'
13]
14alias: [
15 '@aziontech/utils',
16 '@aziontech/utils/edge',
17 '@aziontech/utils/node',
18 'fetch-to-node',
19 'accepts',
20 'assert',
21 'buffer',
22 'https',
23 'module',
24 'string_decoder',
25 'timers',
26 'util',
27 'zlib'
28]
29external: [
30 'node:async_hooks',
31 'node:fs/promises',
32 'node:stream',
33 'node:crypto'
34]
35polyfill: [
36 'aziondev:async_hooks:/async-hooks/async-hooks.polyfills.js',
37 'aziondev:fs:/fs/fs.polyfills.js',
38 'aziondev:fs/promises:/fs/promises/promises.polyfills.js',
39 'aziondev:stream:/stream/stream.polyfills.js',
40 'aziondev:crypto:/crypto/crypto.polyfills.js',
41 'azionprd:fs:/fs.js'
42]

The object has four properties:

PropertyTypeDescription
injectobjectThe globals the build injects, each key mapped to a string. For the list, refer to Global polyfills.
aliasobjectThe module names the build maps to a replacement, each key mapped to a string: @aziontech/utils, @aziontech/utils/edge, @aziontech/utils/node, fetch-to-node, accepts, assert, buffer, https, module, string_decoder, timers, util, and zlib.
externalstring[]Four module names: node:async_hooks, node:fs/promises, node:stream, and node:crypto.
polyfillstring[]The polyfill entries. Entries that start with aziondev: serve development builds and cover async_hooks, fs, fs/promises, stream, and crypto. The one azionprd: entry serves production builds and covers fs.

The build applies this object for you, so a project does not pass it to unenv by hand. The unenv preset is not the preset field of build in azion.config.js, which names the framework or language preset of a project.

Global polyfills

The inject property of the unenv preset lists the Node.js globals that the build adds to a function. A function uses these globals as it would in Node.js, with nothing to import.

GlobalDescription
__dirnameThe name of the current directory.
__filenameThe name of the current file.
processProcess information and the environment, including the environment variables.
performancePerformance timing.

The preset also injects import.meta.url, setInterval, clearInterval, console, asyncStorage, and dateToString.

Node.js modules in a function

A function reaches the polyfills of the unenv preset through the Node.js module names. Import node:fs or node:crypto in the function code, and the build swaps in the polyfill when build.polyfills is true in azion.config.js. The JavaScript template that azion init creates sets polyfills to true.

Import the Node.js module, never a file of the package. The polyfill files of @aziontech/unenv-preset cannot be imported in Node.js or in a function, and the package has no crypto polyfill file. The messages each attempt returns are in Errors.

The node:fs calls read the files that build.memoryFS embeds in the build. A file is read by its path relative to removePathPrefix. The node:fs samples on this page use a project whose azion.config.js sets build.memoryFS to { injectionDirs: ['./data'], removePathPrefix: './data' }. Its data/ folder holds hello.txt, index.html, about/index.html, and docs/readme.txt, so data/hello.txt is read as /hello.txt.

Under azion dev, node:fs reads the embedded files from the .edge/storage/ folder of the project. The local node:fs has no writeFileSync, mkdirSync, or readSync.

createHash and randomUUID

The createHash and randomUUID functions come from node:crypto. createHash returns a hash object for an algorithm, such as sha256, and randomUUID returns a random UUID. For the full module, refer to node

.

This function hashes a string and generates a UUID:

JavaScript
01import { createHash, randomUUID } from 'node:crypto';
02
03export default {
04 async fetch() {
05 // Create a hash
06 const hash = createHash('sha256');
07 hash.update('some data');
08 const digest = hash.digest('hex');
09
10 // Generate a UUID
11 const uuid = randomUUID();
12
13 return new Response(`sha256=${digest}\nuuid=${uuid}\n`);
14 },
15};

Served locally with azion dev, the function returns:

Text
01$ curl http://localhost:3333/x
02HTTP/1.1 200 OK
03content-type: text/plain;charset=UTF-8
04
05sha256=1307990e6ba5ca145eb35e99182a9bec46531bc54ddf656a602c780fa0240dee
06uuid=e2ebf3ce-e7e9-4393-855c-ccdd93ea26f3

readFileSync

The readFileSync function of node:fs reads the whole content of a file that build.memoryFS embeds in the build.

ParameterTypeRequiredDescription
pathstringYesThe path of the file.
options—NoOptions for the read, such as the encoding utf8.

Returns the content of the file as a string or a Buffer. With the encoding utf8, the content is a string.

This function returns the content of /hello.txt, the file data/hello.txt of the project:

JavaScript
01import { readFileSync } from 'node:fs';
02
03export default {
04 async fetch() {
05 // Read a file embedded with build.memoryFS (data/hello.txt is served as /hello.txt)
06 const content = readFileSync('/hello.txt', 'utf8');
07 return new Response(content);
08 },
09};

Served locally with azion dev, the function returns:

Text
01$ curl http://localhost:3333/x
02HTTP/1.1 200 OK
03content-type: text/plain;charset=UTF-8
04
05Hello from memoryFS

readdirSync

The readdirSync function of node:fs lists the content of a directory that build.memoryFS embeds in the build.

ParameterTypeRequiredDescription
pathstringYesThe path of the directory.
options—NoOptions for the listing.

Returns a string[] with the names of the files and directories in the directory.

This function lists the root directory and the /docs directory:

JavaScript
01import { readdirSync } from 'node:fs';
02
03export default {
04 async fetch() {
05 // List directory contents
06 const files = readdirSync('/');
07 const docs = readdirSync('/docs');
08 return Response.json({ files, docs });
09 },
10};

Served locally with azion dev, the function returns:

Text
01$ curl http://localhost:3333/x
02HTTP/1.1 200 OK
03content-type: application/json
04
05{"files":["about","docs","hello.txt","index.html"],"docs":["readme.txt"]}

statSync and existsSync

The existsSync function of node:fs checks whether a path exists in the files that build.memoryFS embeds.

ParameterTypeRequiredDescription
pathstringYesThe path to check.

Returns true when the path exists and false when it does not.

The statSync function of node:fs returns the stats of a file or a directory.

ParameterTypeRequiredDescription
pathstringYesThe path of the file or directory.
options—NoOptions for the call.

Returns an fs.Stats object, with size, isFile(), and isDirectory().

This function checks /hello.txt, reads its stats, and checks a path the build did not embed:

JavaScript
01import { statSync, existsSync } from 'node:fs';
02
03export default {
04 async fetch() {
05 const lines = [];
06 // Check if file exists
07 if (existsSync('/hello.txt')) {
08 // Get file stats
09 const stats = statSync('/hello.txt');
10 lines.push(`File size: ${stats.size}`);
11 lines.push(`Is directory: ${stats.isDirectory()}`);
12 lines.push(`Is file: ${stats.isFile()}`);
13 }
14 lines.push(`existsSync('/missing.txt'): ${existsSync('/missing.txt')}`);
15 return new Response(lines.join('\n') + '\n');
16 },
17};

Served locally with azion dev, the function returns:

Text
01$ curl http://localhost:3333/x
02HTTP/1.1 200 OK
03content-type: text/plain;charset=UTF-8
04
05File size: 20
06Is directory: false
07Is file: true
08existsSync('/missing.txt'): false

openSync and closeSync

The openSync function of node:fs opens a file.

ParameterTypeRequiredDescription
pathstringYesThe path of the file.
flagsstringYesThe open mode, such as 'r' or 'w'.
mode—NoThe file mode.

Returns the file descriptor, a number.

The closeSync function of node:fs closes a file descriptor.

ParameterTypeRequiredDescription
fdnumberYesThe file descriptor to close.

This function opens /hello.txt and closes its file descriptor:

JavaScript
01import { openSync, closeSync } from 'node:fs';
02
03export default {
04 async fetch() {
05 // Open file and get file descriptor
06 const fd = openSync('/hello.txt', 'r');
07 // Close file descriptor
08 closeSync(fd);
09 return new Response(`opened and closed fd ${fd}\n`);
10 },
11};

Served locally with azion dev, the function returns:

Text
01$ curl http://localhost:3333/x
02HTTP/1.1 200 OK
03content-type: text/plain;charset=UTF-8
04
05opened and closed fd 17

Under azion dev, the file descriptor is one the operating system assigns.

Errors

These messages appear when code imports a file of @aziontech/unenv-preset or calls a node:fs function the local runtime does not have.

MessageCauseWhat to do
ERR_MODULE_NOT_FOUND Cannot find module '…/node_modules/@aziontech/unenv-preset/src/polyfills/node/crypto'The code imports @aziontech/unenv-preset/polyfills/node/crypto. The package has no crypto polyfill file.Import from node:crypto in a function, as in createHash and randomUUID.
TypeError: Cannot read properties of undefined (reading '__FILES__')A Node.js script imports @aziontech/unenv-preset/polyfills/node/fs.js. The file reads the embedded files of a build, which a Node.js script does not have.Import from node:fs in a function that the Azion CLI builds.
ReferenceError: SRC_NODE_FS is not definedA function imports @aziontech/unenv-preset/polyfills/node/fs.js, and azion dev stops at server start.Import from node:fs, as in readFileSync.
TypeError: (void 0) is not a functionA function calls writeFileSync, mkdirSync, or readSync from node:fs under azion dev. The build warns that the import will always be undefined because there is no matching export in "internal-env-dev:fs".Read files with the calls on this page.
How Azion Lib works

Where each Azion Lib module runs, in Node.js or in a function, and what differs between the two.

Use Node.js APIs through polyfills

Create a function project, import a Node.js API, and run it locally and deployed.

Node.js APIs

The Node.js modules Azion Runtime resolves, with the behavior of each one.

azion.config.js

The build.polyfills and build.memoryFS settings that decide which polyfills and files a build carries.