Surge

Surge is a network toolbox. Protocol Launcher allows you to generate Surge URL scheme links.

Usage

There are two ways to use this library:

• On-Demand import from subpaths enables tree-shaking and keeps bundles small.
• Full Import from the root package is convenient but includes all app modules.

Pick On-Demand for production builds; Full Import is fine for quick scripts or demos.

Select Installation Method

On-Demand

Recommended. Optimized for production.

Full Import

Convenient. Good for quick scripts.

Notes

Surge's official manual documents four iOS URL scheme actions: surge:///start, surge:///stop, surge:///toggle, and surge:///install-config?url=x. The url value for install-config must be percent-encoded, so installConfig() accepts the raw configuration URL and serializes it as the official url query parameter.

The only documented option is autoclose=true, which can be used with start, stop, and toggle, but cannot be used with install-config.

Surge also documents x-callback-url support from v3.4 with the surge scheme and only the start, stop, and toggle actions. This module therefore exposes only those three x-callback action URLs and does not add callback query parameters that are not listed on the Surge page.

Start

On-Demand

import { start } from 'protocol-launcher/surge'

const url = start()

Start And Auto Close

On-Demand

import { start } from 'protocol-launcher/surge'

const url = start({
  autoclose: true,
})

Stop

On-Demand

import { stop } from 'protocol-launcher/surge'

const url = stop()

Toggle

On-Demand

import { toggle } from 'protocol-launcher/surge'

const url = toggle({
  autoclose: true,
})

Install Config

On-Demand

import { installConfig } from 'protocol-launcher/surge'

const url = installConfig({
  url: 'https://example.com/surge.conf',
})

X-Callback Start

On-Demand

import { xCallbackStart } from 'protocol-launcher/surge'

const url = xCallbackStart()

X-Callback Stop

On-Demand

import { xCallbackStop } from 'protocol-launcher/surge'

const url = xCallbackStop()

X-Callback Toggle

On-Demand

import { xCallbackToggle } from 'protocol-launcher/surge'

const url = xCallbackToggle()

Generated URLs

start()
// => 'surge:///start'

start({ autoclose: true })
// => 'surge:///start?autoclose=true'

stop()
// => 'surge:///stop'

toggle({ autoclose: true })
// => 'surge:///toggle?autoclose=true'

installConfig({
  url: 'https://example.com/surge.conf',
})
// => 'surge:///install-config?url=https%3A%2F%2Fexample.com%2Fsurge.conf'

xCallbackStart()
// => 'surge://x-callback-url/start'

xCallbackStop()
// => 'surge://x-callback-url/stop'

xCallbackToggle()
// => 'surge://x-callback-url/toggle'

Official Documentation

• Surge URL Scheme