Navigating the World of ES Modules in Node.js

The Mysterious Case of Missing Globals

When writing an ES module with the.mjs extension or using {“type”: “module”} in your package.json file, you might encounter an error due to the absence of certain globals. These include __filename, exports, module, and require.

Getting __dirname Back

To retrieve __dirname (and __filename), you can add a simple code snippet to the top of your file:

import { fileURLToPath } from 'url';
import { dirname } from 'path';

const __dirname = dirname(fileURLToPath(import.meta.url));

This code utilizes the new import.meta.url global, which provides a standardized way to access the current file’s URL. By combining it with fileURLToPath from the url module, you can retrieve the path to the current file.

Understanding import.meta.url

The import.meta.url global is a string that represents the URL of the current file. It’s available in all browsers and Node.js when running module code. This new global brings Node.js in line with ES modules in the browser, providing a standardized way to access file URLs.

Goals: Load a File, Dynamically Import Code, and Perform Path-Like Operations

Now that you have __dirname back, let’s explore some common use cases:

Load a File

To load a file in the same directory as the current file, you can construct a new URL:

const fileUrl = new URL('./data.txt', import.meta.url);
const filePath = fileURLToPath(fileUrl);

Node’s internal functions will handle the file:/// protocol just fine.

Dynamically Import Code

You can pass a URL into the dynamic import() helper:

const moduleUrl = new URL('./module.mjs', import.meta.url);
import(moduleUrl);

Again, Node’s import function will happily understand the URL object.

Perform Path-Like Operations and Gotchas

When working with URLs, you’ll encounter some differences in behavior compared to path helpers. For example, the path.dirname helper is equivalent to finding the parent path to the current path. In contrast, URL objects care about trailing slashes and respond differently to . and .. notation.

Interoperability between URL and Path Strings

While URL objects are powerful, you may eventually want to work with simple path strings. To achieve this, use Node’s url.fileURLToPath helper to convert URLs to paths. Be cautious when using the pathname property of URL objects, as it can lead to issues with spaces in filenames and Windows path normalization.

• Use Node’s built-in helpers to convert between URLs and paths.
• Be aware of the differences in behavior between URL objects and path helpers.

By understanding the nuances of import.meta.url and URL objects, you can unlock the full potential of ES modules and create more versatile code.