3. Troubleshooting

While we do our best to make Plug’n’Play a delightful experience, sometimes things might go wrong. The following page describes some common scenario one should be aware of, and provides some guidance to fix them.

<name> is trying to require <name> without it being listed in its dependencies

This error simply means that the specified package is requiring something without explicitly declaring it in its dependencies. Since this behavior is unsafe and relies on the hoisting being done a certain way, Plug’n’Play doesn’t allow it.

That being said, it might happen that the use is pseudo-legitimate. For example, Jest does something similar to require(`jest-environment-${config.environment}`) - in this circumstances the intent is obviously to use the package as provided by the package setting up the package configuration. Still, this is an unsafe behavior that must be fixed in one of three ways:

• Either the code has to be modified so that the user becomes responsible for calling require.resolve(`jest-environment-jsdom`) (and then Jest can simply do require(config.environment))

• Or the code has to be modified in order to use the paths option from require.resolve: require(require.resolve(`jest-environment-${config.environment}`, {paths:[config.projectPath]})) (note that this is the recommended option, being unintrusive for users and a good idea in general)

• Or, finally, the jest-environment-jsdom package can be specified as dependency of the top-level package - usually your own. In those circumstances, Yarn will allow Jest to access it even if it isn’t declared in its dependencies (we do this because this is the only case where this is safe: it isn’t possible for the top-level dependencies to be ambiguous).

The third option is typically meant as a way to unblock yourself, but please report it on the repository of the affected package and link them to this documentation (feel free to ping @arcanis as well so that we can track those problems).

Couldn't find a suitable Node resolution for unqualified path <path>

This error message means that Plug’n’Play was able to locate the package part of the require (so for example it understood that foo should be resolved into /usr/cache/yarn/foo-1.0.0), but couldn’t resolve the file part of the resolution (to use the same example, it couldn’t find an index.js file in /usr/cache/yarn/foo-1.0.0/). This problem typically isn’t caused by Plug’n’Play itself, but rather by your application requiring something that doesn’t exist (under non-PnP mode you’d likely have a generic “Cannot find module” error).

Cannot find module <require-path>

This error message is not generated by Plug’n’Play. Ever. If you get it, it very likely means that your application is not running with the PnP resolver, meaning that your require calls won’t be able to load files from your dependencies (since the node_modules needed for the regular Node resolution won’t have been generated). Make sure to either run your code using NODE_OPTIONS="--require /path/to/.pnp.js" or to call it using yarn node which does the right thing transparently (whether you’re using PnP or not).