Introducing the ngrok JavaScript SDK

We’re pleased to announce ngrok-javascript, our native and idiomatic support for adding secure ingress directly into your JavaScript and TypeScript applications. If you’ve used ngrok in the past, you can think of ngrok-javascript as the ngrok agent packaged as a Node.js library. ngrok-javascript is open source on GitHub, including docs and a quick start guide. ngrok-javascript lets developers deliver JavaScript and TypeScript services on the internet using a single line of code without setting up low-level network primitives like IPs, NATs, certificates, load balancers, or even ports! Applications using ngrok-javascript listen on ngrok’s global ingress network for HTTP or TCP traffic.

Try out the ngrok JavaScript SDK

Check out how easy it is to run a Hello World web app with ngrok-javascript:

import * as http from "http";
import * as ngrok from "@ngrok/ngrok";

// setup your server
http.createServer(function (req, res) {
 res.writeHead(200, { "Content-Type": "text/html" });
 res.write("Congrats you have a created an ngrok web server");
 res.end();
}).listen(8080);

// establish connectivity with ngrok
(async function () {
 const listener = await ngrok.forward({
   domain: "my-app.ngrok.io",
   addr: 8080,
   authtoken_from_env: true,
   ip_restriction_allow_cidrs: ["192.30.252.0/22"],
   circuit_breaker: 0.8,
   oauth_provider: "github"
 });
 
 console.log(`Ingress established at: ${listener.url()}`);
})();

How it works

Similar to how the other ngrok SDKs work, such as ngrok-go, in the example above, when calling <code>ngrok.forward()</code> ngrok-javascript creates a secure and persistent outbound TLS connection to ngrok’s ingress-as-a-service platform.

Once a connection has been established, ngrok transmits the configuration information through the nearest Point of Presence (PoP) and applies the modules defined by your application. Any unauthorized requests are blocked at the ngrok edge to ensure that only authorized requests reach your application.

Why we built ngrok-javascript

Ingress should be a high-level abstraction

Creating ingress can be frustrating for developers, as it entails managing various low-level networking components at different layers of the network stack, such as DNS, TLS certificates, CIDR policies, IP and subnet routing, load balancing, VPNs, and NATs. Essentially, developers are forced to work with the intricate details of networking, akin to navigating the complexities of assembly language. Developers also shoulder the responsibility of ensuring high performance, security, and resilience for their applications and APIs. Slowdowns or downtime can significantly impact user experience. Rather than focusing on core business logic, developers often invest substantial time and effort adding non-functional capabilities outside their area of expertise, such as authentication, authorization, observability, and high availability. 

To resolve this issue, we developed ngrok-javascript. It empowers application developers to define ingress policies at a higher level of abstraction, without compromising security and control. With ngrok-javascript, developers can easily specify ingress using declarative options, eliminating the need to deal with low-level intricacies. We do the heavy lifting so that you don’t have to: enabling you to achieve high performance, security, and resilience for your apps without wasting time and effort building it yourself.

ngrok.forward({
 addr: "localhost:8080",
 authtoken_from_env: true,
 circuit_breaker: 0.5,
 compression: true,
 deny_user_agent: "bar/(d)+",
 domain: "my-app.ngrok.dev",
 ip_restriction_deny_cidrs: "200.2.0.0/16",
 ip_restriction_allow_cids: "0.0.0.0/0",
 oauth_provider: "google",
 oauth_allow_domains: ["example.com"],
 oauth_allow_emails: ["bob@example.com"],
 request_header_add: "X-Requester:app",
});

Ingress should be environment-independent

In traditional scenarios, managing ingress depends on where and how you deploy your app. For example, deploying your app to a data center, an EC2 instance, or a Kubernetes cluster involves varying networking configurations. To run your app in each of these distinct environments, you typically have to manage three separate ingress configurations.

When your application uses ngrok-javascript, you can run it anywhere, and it will receive traffic the same way. Ingress-wise, your application becomes portable, no matter whether it runs on bare metal, VMs, AWS, Azure, Kubernetes, serverless platforms like Heroku or Render, a racked data-center server, a Raspberry Pi, or on your laptop.

Ingress shouldn’t require sidecars

Developers often distribute the ngrok agent alongside their own applications to create ingress for their IoT devices, SaaS offerings, and CI/CD pipelines. Yet bundling and managing the ngrok agent as a sidecar process can be challenging. ngrok-javascript eliminates the agent, thereby simplifying distribution and management and enabling developers to easily deliver private-label experiences.

How we designed ngrok-javascript

We designed ngrok-javascript with the goal of integrating seamlessly into the JavaScript and TypeScript ecosystem.

• Easy installation: Installed from npm via npm, yarn, pnpm, etc.
• Easy integration: Forwards to a standard NodeJS net.Server directly with <code>`ngrok.listen(net.Server)`</code> 
• Works in one-line: Provides ingress with a single <code>ngrok.forward(port)</code> call
• Idiomatic functional options: Enables developers to declare behaviors like authentication simply—e.g. <code>ngrok.forward({oauth_provider: ”google”})</code>
• Built-in forwarding: Forwards to any framework that can listen to a tcp or unix socket.‍
• Out-of-the-box logging support - Supports standard logging via console or winston, which you can enable using <code>`ngrok.consoleLog("INFO");</code>

We validated our approach by collecting feedback on our library design from the following open-source communities:. 

• Twurple - Interact with Twitch API & Twitch Chat API
• Solana Payments App - Solana Pay for Commerce Platforms

Here are some examples of integrating our SDK with popular JavaScript and open-source frameworks: 

• Express
• Next.js
• Remix
• Svelte
• And more…

Get started with ngrok-javascript

To stay up to date with ngrok-javascript and begin using it in your applications, try the following resources:

• ‍Quickstart guide: A step-by-step guide on how to use ngrok-javascript
• ‍JavaScript SDK documentation: The JavaScript SDK documentation, including examples
• Repo on GitHub: ngrok-javascript is open source on GitHub. Star the repo to follow along!