# Protocol-registry

Registers protocols like:- yourapp:// or myapp:// etc. to open your nodejs app from different browsers.

This is meant to be used in command-line tools and scripts, not in the browser.

Why?

• Actively maintained.
• Handles Cross Platform.
• Supports WSL paths to Windows apps.
• Handles multi-line commands.
• Works on electron.

Install

$ npm install protocol-registry

Usage

const path = require("path");

const ProtocolRegistry = require("protocol-registry");

console.log("Registering...");
// Registers the Protocol
ProtocolRegistry.register({
  protocol: "testproto", // sets protocol for your command , testproto://**
  command: `node ${path.join(__dirname, "./tester.js")} $_URL_`, // this will be executed with a extra argument %url from which it was initiated
  override: true, // Use this with caution as it will destroy all previous Registrations on this protocol
  terminal: true, // Use this to run your command inside a terminal
  script: false,
  scriptName: 'my-custom-script-name' // Custom script name.
}).then(async () => {
  console.log("Successfully registered");
});

On Electron :

On electron, you can use the protocol-registry to open your app through custom protocols.

Note : Electron's built-in app.setAsDefaultProtocolClient is recommended to be used in production but as it has some issues in development you can use ProtocolRegistry.register instead while developing.

const dev = require("electron-is-dev");
const ProtocolRegistry = require("protocol-registry")

if (dev) {
  ProtocolRegistry
    .register({
      protocol: "testproto",
      command: `"${process.execPath}" "${path.resolve(
        process.argv[1]
      )}" $_URL_`,
      override: true,
      script: true,
      terminal: dev,
    })
    .then(() => console.log("Successfully registered"))
    .catch(console.error);
} else {
  if (!app.isDefaultProtocolClient('testproto')) {
    app.setAsDefaultProtocolClient('testproto');
  }
}

API

At present it supports :

register(options, cb(err))

Options are mentioned in the above example, more details below. If a valid callback is provided then it returns cb(err) Otherwise it returns a promise.

Example

const path = require("path");

const ProtocolRegistry = require("protocol-registry");

// Registers the Protocol
ProtocolRegistry.register({
  protocol: "testproto",
  command: `node ${path.join(__dirname, "./tester.js")} $_URL_`,
  terminal: true,
})
  .then(() => {
    // do something
  })
  .catch((e) => {
    // do something
  });
// Above will run tester.js when testproto://** is called as
// node .../tester.js testproto://**
// you can further parse the url to run in different modes
// As override is not passed true it will throw an error is protocol already exists

ProtocolRegistry.register(
  {
    protocol: "testproto",
    command: `node ${path.join(__dirname, "./tester.js")} $_URL_`,
    terminal: true,
  },
  (err) => {
    if (err) {
      // do something
    }
  }
);
// Example with callback

ProtocolRegistry.register(
  {
    protocol: "testproto",
    command: `node ${path.join(__dirname, "./tester.js")} $_URL_`,
    terminal: false, // Terminal is set to false
  },
  (err) => {
    if (err) {
      // do something
    }
  }
);
// The above code will run your command in background
// You wont be able to see any logs
// But if your program launches any UI / webpage / file will be visible

const commands = `cd path/to/destination
ls
node ${path.join(__dirname, "./tester.js")} $_URL_
`;

ProtocolRegistry.register(
  {
    protocol: "testproto",
    command: commands,
    terminal: true, // Terminal is set to false
    script: true, // This will save your commands in a script file and execute it when the protocol is hit.
    scriptName: 'my-custom-script-name' // This is the name of the script file that will be created if script option is set true.
  },
  (err) => {
    if (err) {
      // do something
    }
  }
);
// the above code will save your commands to a script file
// and execute it when ever required
// use this for multiline commands

checkifExists(protocol)

Checks if the provided protocol already exists or not. Returns a Promise which resolves in true or false.

Example

const path = require("path");

const ProtocolRegistry = require("protocol-registry");

// Registers the Protocol
ProtocolRegistry.checkifExists("testproto")
  .then((res) => {
    console.log(res); // true or false
    // do something
  })
  .catch((e) => {
    // do something
  });
// Above snippet will check it already some app uses the given protocol or not

options

Supported platforms

• Windows - OS - Supported
• linux - OS - Supported
• MacOS - OS - Supported with some anomalies mentioned below.

MacOS Anomalies

terminal: false

In MacOS if you don't launch the terminal it will run your command without logging in.

Thus you need to use absolute address of each command in your command string.

Example

Suppose you want to run :

$ node /path/to/index.js

Then first you need to find the path of node using the command below in terminal :

$ type node
> node is /usr/local/bin/node

Then replace the address of node in original command. So your final command will be :

$ /usr/local/bin/node /path/to/index.js

To check if your program is running in MacOS you can use the code below:

if (process.platform === "darwin") {
  // running in MacOS do some thing
}

To run shell commands such as "type node" using nodeJS please check the ShellJS documentation

Contributors:

Credits goes to these people: ✨

Visitor's Count