The ngrok Agent SDK for NodeJS

Note: This is beta-quality software. Interfaces may change without warning.

ngrok is a globally distributed reverse proxy commonly used for quickly getting a public URL to a service running inside a private network, such as on your local laptop. The ngrok agent is usually deployed inside a private network and is used to communicate with the ngrok cloud service.

This is the ngrok agent in library form, suitable for integrating directly into NodeJS applications. This allows you to quickly build ngrok into your application with no separate process to manage.

Installation

The published library is available on npm.

npm install @ngrok/ngrok

Documentation

A quickstart guide and a full API reference are included in the ngrok-nodejs API documentation.

Quickstart

After you've installed the package, you'll need an Auth Token. Retrieve one on the Auth Token page of your ngrok dashboard

There are multiple examples in the /examples directory. A minimal use-case looks like the following:

var ngrok = require("@ngrok/ngrok");

async function create_tunnel() {
  const session = await new ngrok.NgrokSessionBuilder().authtokenFromEnv().connect();
  const tunnel = await session.httpEndpoint().listen();
  console.log("Ingress established at:", tunnel.url());
  tunnel.forwardTcp("localhost:8081");
}

or with the 'connect' convenience function:

const ngrok = require("@ngrok/ngrok");
ngrok.connect({addr: 8080, authtoken_from_env: true}).then((url) => {
  console.log(`Ingress established at: ${url}`);
});

Examples

Degit can be used for cloning and running an example directory like this:

npx degit github:ngrok/ngrok-nodejs/examples/<example> <folder-name>
cd <folder-name>
npm i

For example:

npx degit github:ngrok/ngrok-nodejs/examples/express express && cd express && npm i

Frameworks

AWS App Runner - See the ngrok SDK Serverless Example repository
Express - Quickstart Example, Configuration Example
Fastify - Example
Hapi - Example
Koa - Example
Nest.js - Example main.ts
Next.js - Example next.config.js loading ngrok.config.js
Remix - Example remix.config.js loading ngrok.config.js
Svelte - Example svelte.config.js (works in vite.config.js too) loading ngrok.config.cjs
Typescript - Example ts-node
Vue - Example vite.config.ts loading ngrok.config.ts
Winston Logging - Example

Tunnel Types

ngrok.connect - ngrok.connect Minimal Example, Full ngrok.connect Example
HTTP - ngrok.listen Example, Minimal Example, Full Configuration Example
Labeled - Example
TCP - Example
TLS - Example
Windows Pipe - Example

Async Programming

All methods return a Promise and are suitable for use in asynchronous programming. You can use callback chaining with .then() and .catch() syntax or the await keyword to wait for completion of an API call.

Error Handling

The asynchronous functions will throw an error on failure to set up a session or tunnel, which can be caught and dealt with using standard then/catch semantics.

new ngrok.NgrokSessionBuilder().authtokenFromEnv().connect()
    .then((session) => {
        session.httpEndpoint().listen()
            .then((tun) => {})
            .catch(err => console.log('tunnel setup error: ' + err))
    })
    .catch(err => console.log('session setup error: ' + err))
    .await;

Platform Support

Pre-built binaries are provided on NPM for the following platforms:

OS	i686	x64	aarch64	arm
Windows	✓	✓	*
MacOS		✓	✓
Linux		✓	✓	✓
Linux musl		✓	✓
FreeBSD		✓
Android			✓	✓

ngrok-nodejs, and ngrok-rust which it depends on, are open source, so it may be possible to build them for other platforms.

Windows-aarch64 will be supported after the next release of Ring.

Dependencies

This project relies on NAPI-RS, an excellent system to ease development and building of Rust plugins for NodeJS.

License

This project is licensed under either of

Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in ngrok-nodejs by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

ngrok / ngrok-nodejs