Cannot import 'zx/globals' in global installed zx

[atuk721]

For better autocomplete in VS Code, I'm going to add import 'zx/globals' to my script.

But when I added it to my script, the script became to raise an error of ERR_MODULE_NOT_FOUND.
I added global node modules path to NODE_PATH but it also has an error with a message of "Did you mean to import zx/build/globals.js?".

When npm link zx is executed, it works successfully but I don't want to have node_modules in current path.

So is there any way to achieve to use global installed zx and to have import 'zx/globals' in the script without local node_modules?

Expected Behavior

A script is executed successfully.

Actual Behavior

A script throws an error of "ERR_MODULE_NOT_FOUND".

Steps to Reproduce the Problem

$ docker run -it --rm node:18-alpine sh
/ # mkdir work
/ # cd work
/work # npm i -g zx

added 55 packages in 4s

10 packages are looking for funding
  run `npm fund` for details
npm notice 
npm notice New minor version of npm available! 9.5.0 -> 9.6.1
npm notice Changelog: https://github.com/npm/cli/releases/tag/v9.6.1
npm notice Run npm install -g npm@9.6.1 to update!
npm notice 
/work # echo "import 'zx/globals'" > test.mjs
/work # zx test.mjs
Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'zx' imported from /work/test.mjs
    at new NodeError (node:internal/errors:399:5)
    at packageResolve (node:internal/modules/esm/resolve:889:9)
    at moduleResolve (node:internal/modules/esm/resolve:938:20)
    at defaultResolve (node:internal/modules/esm/resolve:1153:11)
    at nextResolve (node:internal/modules/esm/loader:163:28)
    at ESMLoader.resolve (node:internal/modules/esm/loader:838:30)
    at ESMLoader.getModuleJob (node:internal/modules/esm/loader:424:18)
    at ModuleWrap.<anonymous> (node:internal/modules/esm/module_job:77:40)
    at link (node:internal/modules/esm/module_job:76:36) {
  code: 'ERR_MODULE_NOT_FOUND'
}
/work # export NODE_PATH=$(npm root -g)
/work # zx test.mjs
Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'zx' imported from /work/test.mjs
Did you mean to import zx/build/globals.js?
    at new NodeError (node:internal/errors:399:5)
    at packageResolve (node:internal/modules/esm/resolve:889:9)
    at moduleResolve (node:internal/modules/esm/resolve:938:20)
    at defaultResolve (node:internal/modules/esm/resolve:1153:11)
    at nextResolve (node:internal/modules/esm/loader:163:28)
    at ESMLoader.resolve (node:internal/modules/esm/loader:838:30)
    at ESMLoader.getModuleJob (node:internal/modules/esm/loader:424:18)
    at ModuleWrap.<anonymous> (node:internal/modules/esm/module_job:77:40)
    at link (node:internal/modules/esm/module_job:76:36) {
  code: 'ERR_MODULE_NOT_FOUND'
}
/work # npm link zx

added 1 package in 139ms
/work # zx test.mjs
/work # 

Specifications

• Version: 7.2.0
• Platform: Linux (Docker image of node:18-alpine)

[mogoh]

Sadly es modules do not support importing from the global installation space.
NODE_PATH is ignored.
See: https://nodejs.org/api/esm.html#no-node_path

This is a bummer, because one can not import globally installed modules.
import 'zx/globals' does only work for autocompletion and has to be removed before running.

I don't know why the README.md does not reflect that.

See also: #499

[antonmedv]

One possibility is to use:

/// <reference path="/usr/local/lib/node_modules/zx/build/globals.d.ts" />

[mogoh]

/// <reference path="/usr/local/lib/node_modules/zx/build/globals.d.ts" />

Isn't that typescript-only magic?

If not, can we replace the suggested import 'zx/globals' in the README.md?

Semi-related: Is there a way to import a globally installed library (e.g. dotenv)?

[atuk721]

Hello everyone, thank you for your comments.

Sadly es modules do not support importing from the global installation space.
NODE_PATH is ignored.
See: https://nodejs.org/api/esm.html#no-node_path

I didn't know it. Thank you @mogoh .
I'll install node_modules to current or parent directory for now.

[3rd]

Ran into the same "how to import global types" problem in one of my projects and kinda solved it by using a tsconfig.json in the directory that includes the global types through the typeRoots option.

[mgutz]

References must be absolute paths so not portable. A simple workaround for VS Code on non node projects

1. Install zx globally as usual

2. Install zx again in $HOME for referencing d.ts files

cd ~
pnpm init 
pnpm add zx

3. Symlink node_modules in your project

link -sf $HOME/node_modules node_modules

Node should look up directories for node_modules, but VS Code doesn't seem to follow.