Skip to main content

ngrok JavaScript SDK Quickstart

The ngrok JavaScript (Node.js) SDK is an open-source package that enables you to quickly and efficiently serve Node.js applications on the internet without the need to configure low-level network primitives like IPs, certificates, load balancers, or ports. You can think of it as the ngrok Agent CLI packaged as a JS library.

This quickstart uses the ngrok JavaScript SDK to create an agent endpoint that forwards traffic from the internet to a Node.js app running on your local device, then secure it by requiring visitors to log in with a Google account to access it.

What you'll need​

1. Reserve your domain​

A new URL is generated for you every time you start an endpoint. To maintain a consistent URL, you can reserve a free static domain connected to your ngrok account.

Navigate to the dashboard, visit the Domains section, and select + New Domain. You can choose a free static domain, or you can use a custom domain you already own.

2. Start your app or service​

Start up the app or service you'd like to put online. This is the app that your agent endpoint will forward online traffic to.

If you don't have an app to work with, you can create a minimal Node.js app using the following code to set up a basic HTTP server at port 8080.

Loading…

Navigate to the directory where this file is located and run the following command to start the server:

Loading…

3. Install the JavaScript SDK​

Open a new terminal, then run the following command to install the JavaScript SDK:

Loading…

4. Create a .env file​

Create a .env file and add your ngrok auth token to it. This file needs to be in the same directory where you'll put the script using ngrok's JavaScript SDK. The following terminal commands will create this directory, navigate into it, and add the .env file there:

Loading…

Add your ngrok auth token to this file:

Loading…

Finally, you'll need to install the dotenv package to access your environment variable from your code.

Loading…
tip

If you don't want to use a .env file, you can instead export your auth token as an environment variable in your terminal session, or pass the auth token directly to the forward method in your code.

5. Create your endpoint​

Create your agent endpoint, which will forward public traffic to your app.

Create a new file named example.js in the same directory as your .env file and add the following code. This example:

  • Starts an agent endpoint that forwards from your reserved domain to your service running on port 8080.
  • Secures the endpoint with Google OAuth authentication.
note

This example uses ngrok's default Google OAuth application. To use your own, see the OAuth Traffic Policy Action documentation.

Loading…

6. Test your endpoint​

Test your endpoint by running the following terminal command:

Loading…

This should print your reserved domain URL to the terminal. When you visit the URL, you should be prompted to log in with Google. After logging in, you'll see your app or service.

If you used the example app in this quickstart, you'll see "Hello from Node.js HTTP Server!" displayed in your browser.

What's next?​

In this guide, you learned how to use the JavaScript SDK to an create agent endpoint that forwards traffic to your localhost. You saw one way to implement a directly in your codebase, including an action that adds authentication to your app with no configuration required. What else can you do with these features?