https://github.com/kettanaito/protocol-handlers

Utilities to work with protocol handlers (like "vscode://") on the web.
https://github.com/kettanaito/protocol-handlers

custom handler handlers navigator protocol protocols web

Last synced: 3 months ago
JSON representation

Utilities to work with protocol handlers (like "vscode://") on the web.

• Host: GitHub
• URL: https://github.com/kettanaito/protocol-handlers
• Owner: kettanaito
• License: mit
• Created: 2022-08-19T09:45:29.000Z (over 2 years ago)
• Default Branch: main
• Last Pushed: 2022-08-22T10:24:12.000Z (over 2 years ago)
• Last Synced: 2024-05-22T16:24:11.469Z (8 months ago)
• Topics: custom, handler, handlers, navigator, protocol, protocols, web
• Language: TypeScript
• Homepage: https://www.npmjs.com/package/protocol-handlers
• Size: 101 KB
• Stars: 13
• Watchers: 3
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

        
# Protocol Handlers

Utilities to work with protocol handlers on the web.

## Why?

While the [Navigator API](https://developer.mozilla.org/en-US/docs/Web/API/Navigator) provides methods to `.registerProtocolHandler()` and `.unregisterProtocolHandler()`, there's no way to check if a given protocol _has_ a handler. Instead, when trying to open a URL with an unsupported protocol the browser will throw an error that you cannot handle by any normal means (can be handled only in Firefox).

This package fills in the gap and provides API to work with protocol handlers.

## Install

```sh

npm install protocol-handlers

```

## API

### `openUrl`

Returns a promise that resolves if the given URL has successfuly opened (has a registered handler for its protocol) or rejects if it doesn't have a registered handler.

```ts

import { openUrl, UnsupportedProtocolError } from 'protocol-handlers'

// For example, try to open a Visual Studio Code Insiders URI.

// If that application is not installed, handle the rejection.

openUrl('vscode-insiders://resource').catch((error) => {

  if (error instanceof UnsupportedProtocolError) {

    console.log('The "%s" protocol is not supported!', error.protocol)

  }

})

```

#### Options

##### `timeout: number`

A custom timeout duration.

```ts

openUrl('my-app://resource', {

  // Wait for 2s for the navigation modal to appear

  // before rejecting this Promise.

  timeout: 2000,

})

```