optional-require

What is optional-require?

The 'optional-require' npm package allows you to require modules that may or may not exist without throwing an error. This is useful for optional dependencies or plugins that are not always needed.

What are optional-require's main functionalities?

Basic Optional Require

This feature allows you to require a module that may not be installed. If the module is not available, it returns null instead of throwing an error.

const optionalRequire = require('optional-require')(require);
const myModule = optionalRequire('my-module');
if (myModule) {
  console.log('my-module is available');
} else {
  console.log('my-module is not available');
}

Optional Require with Default Value

This feature allows you to provide a default value if the module is not available. This can be useful to ensure your code continues to work even if the optional module is missing.

const optionalRequire = require('optional-require')(require);
const myModule = optionalRequire('my-module', { default: {} });
console.log(myModule);

Optional Require with Logging

This feature allows you to log a custom message if the module is not available. This can be useful for debugging or informing the user about missing optional dependencies.

const optionalRequire = require('optional-require')(require);
const myModule = optionalRequire('my-module', { message: 'my-module is not installed' });
if (!myModule) {
  console.log('my-module is not installed');
}

Other packages similar to optional-require

require-optional

The 'require-optional' package provides similar functionality by allowing you to require modules that may not be installed. It also returns null if the module is not available, but it does not provide options for default values or custom logging messages.

try-require

The 'try-require' package attempts to require a module and returns undefined if the module is not found. It is similar to 'optional-require' but does not offer as many customization options such as default values or custom messages.

README

Optional Require

node.js require that let you handle module not found error without try/catch. Allows you to gracefully require a module only if it exists and contains no error.

Why not try/catch?

So why not just do:

let some;
try {
  some = require("some-optional-module");
} catch {
  // do nothing
}

• Variable scoping: You need to keep the variable outside: let some before try/catch
• Error differentiation: You need additional logic to distinguish between "module not found" vs "module has syntax/runtime errors". If "some-optional-module" contains error itself, above code will silently ignore it, leaving you, and more importantly, your users, puzzling on why it's not working -- the original reason that prompted the creation of this package.
• Code readability: Nested try/catch blocks make code harder to read and maintain, especially when dealing with multiple optional modules

Usage

ES Modules:

import { optionalRequire } from "optional-require";

const some = optionalRequire("some-optional-module");
const bar = optionalRequire("bar", true); // log message when not found
const xyz = optionalRequire("xyz", "test"); // log with custom message
const fbPath = optionalRequire.resolve("foo", "foo doesn't exist");

CommonJS:

const { optionalRequire } = require("optional-require");

const foo = optionalRequire("foo") || {};
const rel = optionalRequire("../foo/bar", { require }); // relative paths need require

Custom Context

To require modules relative to your file, bind the function to your context:

ESM:

import { makeOptionalRequire } from "optional-require";
const optionalRequire = makeOptionalRequire(import.meta.url);
const myModule = optionalRequire("./my-module");

CommonJS:

const { makeOptionalRequire } = require("optional-require");
const optionalRequire = makeOptionalRequire(__dirname);
// or
const optionalRequire = makeOptionalRequire(require);
const myModule = optionalRequire("./my-module");

Requirements

• Node.js 20+: Full support for both ESM and CommonJS through conditional exports

Legacy Usage

In older versions, this module exports makeOptionalRequire directly and this is the legacy usage in CommonJS only, which is still supported:

const optionalRequire = require("optional-require")(require);

const foo = optionalRequire("foo") || {};
const bar = optionalRequire("bar", true); // true enables console.log a message when not found
const xyz = optionalRequire("xyz", "test"); // "test" enables console.log a message with "test" added.
const fbPath = optionalRequire.resolve("foo", "foo doesn't exist");
const rel = optionalRequire("../foo/bar"); // relative module path works

Note: This legacy pattern only works in CommonJS mode since it relies on the require function.

API

https://jchip.github.io/optional-require/modules.html#optionalrequire

LICENSE

Apache-2.0 © Joel Chen