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

NodeJS 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.

Usage

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

Install

$ npm i optional-require --save

API

optionalRequire(require)

The single function this module exports. Call it with require to get a custom function for you to do optional require from your file's require context. See Usage above.

customOptionalRequire(path, [message|options])

The function optionalRequire returns for you to do optional require from your file's require context.

Params

• path - name/path to the module your want to optionally require
• message - optional flag/message to enable console.log a message when module is not found
• options - an optional object with the following fields
  • message - see above
  • fail - callback for when an error that's not MODULE_NOT_FOUND for path occurred
  • notFound - callback for when path was not found
    • The value from this is returned
  • default - default value to returned when not found - not allowed with notFound together

Returns

• module required or one of the following if not found
  • undefined or
  • return value from options.notFound if it's specified
  • options.default if it's specified

Throws

• rethrows any error that's not MODULE_NOT_FOUND for the module path

customOptionalRequire.resolve(path, [message])

Same as customOptionalRequire but acts like require.resolve

optionalRequire.log(message, path)

The function that will be called to log the message when optional module is not found. You can override this with your own function.

optionalRequire.try(require, path, [message|options])

Same as customOptionalRequire but you have to pass in require from your file's context.

optionalRequire.resolve(require, path, [message|options])

Same as customOptionalRequire.resolve but you have to pass in require from your file's context.

LICENSE

Apache-2.0 © Joel Chen