Using Ngrok and Node.js to share our localhost publicly

Running apps locally on our own computers is great for development, but there are many cases where software developers such as us would want to show off our work with people outside our network!  Maybe we are working on a prototype or a feature request, maybe we do not have a server to deploy to, or maybe we are behind a restrictive corporate firewall or network. Whatever the reason, there is a way to still expose our app to the work with a public URL: ngrok!

Ngrok creates a secure tunnel to expose local networked services (like a web server) at a publicly-accessible URL.  Simply put, we can run a local Node.js app on our computer at localhost:8080 and have someone across the world and outside our network access this local web server at a URL such as http://6897021c.ngrok.io.

Here are some more ideas of what you can do with ngrok:

  • Utilize a ngrok URL with a API webhook that would normally require a deployment and public URL
  • Inspect the HTTP traffic on your development machine to debug web services and APIs

Learn more about what ngrok can do at their website!

Before We Begin…

Make sure that you have Node.js installed on your computer.  Installers for all major operating systems can be found here: https://nodejs.org/en/download/

If you plan to use ngrok at work, you should also have a talk about what ngrok is with your system administrator or whomever is responsible for network security.  Punching a hole in a corporate firewall or NAT can be disastrous, especially if malicious users of your publicly-accessible app can manipulate your filesystem or access other computers on your network.

ngrok offers a free service in addition to a paid subscription.  In the following tutorials, we will be using the free plan.  One drawback to this is that our ngrok URL will change every time that we start our application.  Paid subscriptions allow you to have set subdomains (i.e. stevescoolapp.ngrok.io)

Sample App From Scratch

Let’s create a very basic Node.js app with ngrok to expose it to the world!

First, open a terminal and create a new directory for our code, then navigate into it:

mkdir app
cd app

Create a new Node.js project by creating our package.json file with the following command:

npm init

Enter your project details, or hit enter multiple times to use the defaults.

Next, let’s install ngrok from npm (https://www.npmjs.com/package/ngrok).

npm install ngrok

You should end up with a package.json file that looks like this:

{
  "name": "ngrok-node-example",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "",
  "license": "ISC",
  "dependencies": {
    "ngrok": "^2.2.24"
  }
}

Create a file called index.js and paste the following code:

const http = require('http');
const ngrok = require('ngrok');

const port = 8080;
const server = http.createServer((req, res) => {
    res.end('Hello, World!');
});

server.listen(port, (err) => {
    if (err) return console.log(`Something bad happened: ${err}`);
    console.log(`Node.js server listening on ${port}`);

    ngrok.connect(port, function (err, url) {
        console.log(`Node.js local server is publicly-accessible at ${url}`);
    });

});

The code above is fairly straightforward.  We first create our HTTP server that will reply with “Hello, World” for every request.  We then start listening on port 8080, with a callback to display a message to the console once our web server is up and running.  We then connect ngrok, passing the port number in so that ngrok knows which port to use to set up the tunnel.  A success message with our ngrok subdomain url is then displayed, which will be different each time that we run this app.

Let’s test the code to make sure it works:

node index.js

You should see two messages: one indicating that our local server is listening on port 8080, and another message of where our app can be reached by the public Internet.

Open up your favorite browser and check out the ngrok URL.

Congrats, that’s how easy it is to use ngrok with Node.js!

Sample App From GitHub

If you are running into any issues with the previous tutorial, feel free to clone the source code repository with Git (make sure you have this installed). Run the following commands:

git clone https://github.com/ssenkus/ngrok-node-example.git
cd ngrok-node-example
npm install
node index.js

Just like in the previous sample app tutorial, you should see two messages printed to the console in your console. Success!

Ngrok Status

We can inspect our tunneled traffic by opening http://localhost:4040 for a very detailed web interface.  You will be able to see everything from headers to request payloads to raw bytes.  You can also replay requests, which can be very helpful when debugging application interactions with webhooks and external APIs.

Conclusion

Ngrok is a very useful tool to use when you need to make your localhost-running applications public.  The sample Nodejs app should be enough to get you exploring, but be sure to check out ngrok documentation as well as the npm ngrok package page for more features and use-cases.  Ngrok also offers a paid service that includes parked ngrok.io subdomains, more connections, and other features you may deem useful.  Happy hacking!