Node.js v20: .env files, import modules, and Permission Model

Node.js v20.6 was released with amazing new features that are part of the LTS versions from October 24th, 2023. Let's see!

The INI configuration files

Say goodbye to the dotenv package, now Node.js can load environment variables from a .env file.

node --env-file path/to/.env index.js

💡 The path to the INI file is required because Node.js didn't choose a default name for the INI file.

🧠 If the INI file does not exist, the node process will not fail; instead, it will start running without the environment variables.

Loading NODE_OPTIONS

You can load Node.js' specific environment variables (like NODE_OPTIONS) using an INI configuration file like the following example:

NODE_NO_WARNINGS=1
NODE_OPTIONS="--experimental-permission --allow-fs-read=*"
TZ=Pacific/Honolulu
UV_THREADPOOL_SIZE=5

You can use this with the same method:

node --env-file .env index.js

Preload ES modules

Preload ES modules at startup using the --import flag, the module will be loaded before any application code runs, even the entry point.

node --import path/to/file.js index.js

This flag is similar to the well known --require flag used to load CommonJS modules.

💡 Modules preloaded with --require will run before modules preloaded with --import.

Permission Model

We have a new mechanism to restrict access to specific resources during the execution of a Node.js process called Permission Model. The API exists behind a flag --experimental-permission which, when enabled, will restrict access to all resources not explicitly allowed.

File System permissions

The --allow-fs-read flag allows all FileSystemRead operations using *, or to specific paths using absolute routes.

node --experimental-permission --allow-fs-read=* index.js

To only allow access to specific paths you should use absolute routes

node --experimental-permission --allow-fs-read=/path/to/index.js --allow-fs-read=/path/to/directory index.js

🧠 The initializer module also needs to be allowed. Otherwise index.js file cannot be loaded by the Node.js process itself.

💡 You can use . to allow access to the working directory, but you can't use it to specify the path to a file (e.g. ./index.js).

node --experimental-permission --allow-fs-read=. index.js

The --allow-fs-write flag allows access to specific paths or the whole file system using *.

node --experimental-permission --allow-fs-read=. --allow-fs-write=/tmp/ index.js

Child Process

When the Permission Model is enabled, the process will not be able to spawn any child process by default, you should use the --allow-child-process to allow this operation. Let's use the following code for the index.js.

const childProcess = require('node:child_process');
childProcess.spawn('node', ['-e', 'require("fs").writeFileSync("./new-file.txt", "Hello, World!")']);

To run this snippet with the Permission Model enabled you should execute index.js using the following command:

node --experimental-permission --allow-fs-read . --allow-child-process index.js

🧠 The child process doesn't inherit the Permission Model by default, that's why the new-file.txt is created successfully.

More options

You can check the --allow-worker flag if you want to create Worker Threads under this Permission Model and --allow-wasi to allow the creation of WASI instances

Conclusion

We have a lot of new tools to load environment variables for our application, a method to import preload ES modules required in our code and a new Permission Model to increase the security of our systems.

Stay tuned to the Node.js' blog, this team is adding awesome features in every version! We have initial TypeScript support and a Network Inspection using the DevTools in v22.6.0.