Safely detect if a Node.js module is installed before using require() to load it

By: ( +David Herron; Date: 2015-05-05 17:20

Tags: Node.JS

Sometimes you need to detect whether a Node.js module is installed, and print a useful error message if it isn't. For example Grunt does this. The instructions are to install "grunt-cli" then add "grunt" to the package.json for the project for which you want to use Grunt. If you haven't installed grunt locally, typing "grunt" gives you a nice error message telling you what to do. It does that instead of printing an ugly message from the "require" function saying your module wasn't loaded.

Grunt, in turn, requires that all modules used in a particular build are installed locally. That means if you're developing a tool for use with Grunt, where you want both a command line tool and some business logic to be called from the Gruntfile, that your users must also install two modules for your tool. One is a CLI module providing the command line tool, and the other is installed locally to provide the business logic.

In my case, the tool I've developed is ( AkashaCMS, a static website generator. It currently has a command line script that turns into the global command akashacms, and the module itself is installed with npm install -g akashacms to put it in the global context. But using AkashaCMS with Grunt means installing the akashacms module in the local context. That means I need to change AkashaCMS so users npm install -g akashacms-cli then list akashacms in the package.json dependencies in their website.

The required pattern is this split:

  • CLI Module: A simple shell in global context
  • Local Module: The rest of your tool installed as a local module - e.g. a module with a `package.json` listing your module in the `dependencies` or `devDependencies`

Turns out to be very easy.

We start by making a new module named something like xyzzy-cli (I named it akashacms-cli - or (

It requires three or maybe four files, at a minimum:

  • package.json
  • cli.js

In the package.json there's a critical entry:

  "bin": {
    "xyzzy": "cli.js"

Substitute your preferred command name for xyzzy.

The should of course say how great your tool is, and link to its homepage. The LICENSE file should have whatever license statement you want to make.

In the package.json list this dependency

  "dependencies": {
    "resolve": "*"

You might well have other dependencies, but list at least this one. Do not list the module containing your business logic because that module must be installed locally to your users project.

The next critical piece is the content of cli.js. The exact content for your cli.js is up to you, but there is a critical step required in order to locate the module with your business logic.

That step is made possible by the resolve module ( ( It is an implementation of Node.js's algorithm behind the require function. It's necessary to let us do this:

var fnxyzzy;
try {
    fnxyzzy = resolve('xyzzy', { basedir: process.cwd() });
} catch (ex) {
    console.error("Could not find XYZZY because: "+ ex);
var xyzzy = require(fnxyzzy);

What this does is search for your module (again - substitute the name of your module for xyzzy) from the current directory. This will find your module if it's been installed locally. For example if your current directory has a package.json listing xyzzy causing your module to have been installed in the local node_modules directory.

The console.error line should print out a nice message telling the person how to proceed to get started. For example this is what Grunt shows:

$ grunt
grunt-cli: The grunt command line interface. (v0.1.13)

Fatal error: Unable to find local grunt.

If you're seeing this message, either a Gruntfile wasn't found or grunt
hasn't been installed locally to your project. For more information about
installing and configuring grunt, please see the Getting Started guide:

Your CLI module should then go ahead and do its business parsing command line options and performing the requested operation.

« Where should you put routes in an Express/Node.js web application for simple easy coding enjoyment? Easily deploy files or directory hierarchies to a server using Grunt »
2016 Election 2018 Elections Acer C720 Ad block Affiliate marketing Air Filters Air Quality Air Quality Monitoring AkashaCMS Amazon Amazon Kindle Amazon Web Services America Amiga and Jon Pertwee Android Anti-Fascism AntiVirus Software Apple Apple Flexgate Apple Hardware History Apple Hardware Mistakes Apple iPhone Apple iPhone Hardware April 1st Arduino ARM Compilation Artificial Intelligence Astronomy Astrophotography Asynchronous Programming Authoritarianism Automated Social Posting AWS DynamoDB AWS Lambda Ayo.JS Bells Law Big Brother Big Data Big Finish Big Science Bitcoin Mining Black Holes Blade Runner Blockchain Blogger Blogging Books Botnets Cassette Tapes Cellphones China China Manufacturing Christopher Eccleston Chrome Chrome Apps Chromebook Chromebox ChromeOS CIA CitiCards Citizen Journalism Civil Liberties Climate Change Clinton Cluster Computing Command Line Tools Comment Systems Computer Accessories Computer Hardware Computer Repair Computers Conservatives Cross Compilation Crouton Cryptocurrency Curiosity Rover Currencies Cyber Security Cybermen Cybersecurity Daleks Darth Vader Data backup Data Formats Data Storage Database Database Backup Databases David Tenant DDoS Botnet Department of Defense Department of Justice Detect Adblocker Developers Editors Digital audio Digital Nomad Digital Photography Direct Attach Storage Diskless Booting Disqus DIY DIY Repair DNP3 Do it yourself Docker Docker MAMP Docker Swarm Doctor Who Doctor Who Paradox Doctor Who Review Drobo Drupal Drupal Themes DuckDuckGo DVD E-Books E-Readers Early Computers eGPU Election Hacks Electric Bicycles Electric Vehicles Electron Eliminating Jobs for Human Emdebian Encabulators Energy Efficiency Enterprise Node EPUB ESP8266 Ethical Curation Eurovision Event Driven Asynchronous Express Face Recognition Facebook Fake Advertising Fake News Fedora VirtualBox Fifth Doctor File transfer without iTunes FireFly Flash Flickr Fraud Freedom of Speech Front-end Development G Suite Gallifrey Gig Economy git Github GitKraken Gitlab GMAIL Google Google Adsense Google Chrome Google Gnome Google+ Government Spying Great Britain Green Transportation Hate Speech Heat Loss Hibernate High Technology Hoax Science Home Automation HTTP Security HTTPS Human ID I2C Protocol Image Analysis Image Conversion Image Processing ImageMagick In-memory Computing Incognito Mode InfluxDB Infrared Thermometers Insulation Internet Internet Advertising Internet Law Internet of Things Internet Policy Internet Privacy iOS iOS Devices iPad iPhone iPhone hacking Iron Man iShowU Audio Capture iTunes Janet Fielding Java JavaFX JavaScript JavaScript Injection JDBC John Simms Journalism Joyent jQuery Kaspersky Labs Kext Kindle Kindle Marketplace Large Hadron Collider Lets Encrypt LibreOffice Linux Linux Hints Linux Single Board Computers Logging Mac Mini Mac OS Mac OS X Mac Pro MacBook Pro Machine Learning Machine Readable ID Macintosh macOS macOS High Sierra macOS Kext MacOS X setup Make Money Online Make Money with Gigs March For Our Lives MariaDB Mars Mass Violence Matt Lucas MEADS Anti-Missile Mercurial MERN Stack Michele Gomez Micro Apartments Microsoft Military AI Military Hardware Minification Minimized CSS Minimized HTML Minimized JavaScript Missy Mobile Applications Mobile Computers MODBUS Mondas Monetary System MongoDB Mongoose Monty Python MQTT Music Player Music Streaming MySQL NanoPi Nardole NASA Net Neutrality Network Attached Storage Node Web Development Node.js Node.js Database Node.js Performance Node.js Testing Node.JS Web Development Node.x North Korea npm NSA NVIDIA NY Times Online advertising Online Community Online Fraud Online Journalism Online News Online Photography Online Video Open Media Vault Open Source Open Source and Patents Open Source Governance Open Source Licenses Open Source Software OpenAPI OpenJDK OpenVPN Palmtop PDA Patrick Troughton PayPal Paywalls Personal Flight Peter Capaldi Peter Davison Phishing Photography PHP Plex Plex Media Server Political Protest Politics Postal Service Power Control President Trump Privacy Private E-mail server Production use Public Violence Raspberry Pi Raspberry Pi 3 Raspberry Pi Zero ReactJS Recaptcha Recycling Refurbished Computers Remote Desktop Removable Storage Renewable Energy Republicans Retro Computing Retro-Technology Reviews RFID Rich Internet Applications Right to Repair River Song Robotics Robots Rocket Ships RSS News Readers rsync Russia Russia Troll Factory Russian Hacking Rust SCADA Scheme Science Fiction SD Cards Search Engine Ranking Search Engines Season 1 Season 10 Season 11 Security Security Cameras Server-side JavaScript Serverless Framework Servers Shell Scripts Silence Simsimi Skype SmugMug Social Media Social Media Networks Social Media Warfare Social Network Management Social Networks Software Development Software Patents Space Flight Space Ship Reuse Space Ships SpaceX Spear Phishing Spring Spring Boot Spy Satellites SQLite3 SSD Drives SSD upgrade SSH SSH Key SSL Stand For Truth Strange Parts Swagger Synchronizing Files Tegan Jovanka Telescopes Terrorism The Cybermen The Daleks The Master Time-Series Database Tom Baker Torchwood Total Information Awareness Trump Trump Administration Trump Campaign Twitter Ubuntu Udemy UDOO US Department of Defense Video editing Virtual Private Networks VirtualBox VLC VNC VOIP Vue.js Walmart Weapons Systems Web Applications Web Developer Resources Web Development Web Development Tools Web Marketing Webpack Website Advertising Website Business Models Website Security Weeping Angels WhatsApp William Hartnell Window Insulation Windows Windows Alternatives Wordpress World Wide Web Yahoo YouTube YouTube Adpocalypse YouTube Monetization