Anyone who has done web development for any significant length of time has probably had one or more of these situations arise:
- I need to expose an API or webhook running locally to an external service or application
- My application has external services or integrations that require special handling or emulation when developing locally
- I want my deployed application or service in a higher environment to call the endpoint(s) that I am running locally
The common problem here is the need to expose a locally running endpoint to an external service or application. Enter ngrok (https://ngrok.com/).
Ngrok solves this problem by creating and exposing a public url on the ngrok.io domain, and then forwarding the traffic that arrives at that endpoint through to a specified localhost port. Conceptually, it looks something like this:
This diagram was taken directly from https://ngrok.com/product, where the curious can find a full explanation of ngrok’s architecture and features. In addition to being repetitive with the documentation found there, a full description is beyond the scope of this post; but the core idea (as illustrated above) is this:
- The ngrok client is run on a local machine and takes a localhost port as an argument at runtime
- After being provided the local port to forward traffic to, the ngrok client connects to the ngrok cloud service, which exposes http and https endpoints corresponding to the client: cloud service connection
- At this point, the ngrok cloud service will forward all traffic that arrives at the exposed endpoints to the local ngrok client, which will in turn forward that traffic to the localhost port supplied at runtime.
And that’s it. Traffic will be forwarded for as long as the client is running locally; stopping the client will terminate the connection.
Like many of you (probably) I am always wary of adding new tools and extensions to my development environment; I think we’ve all had the experience of tools that look great but cost more setup and troubleshooting time than they end up saving. Ngrok is not one of those tools. If anything, installing and using the tool is even simpler than the explanation above would suggest. There are three steps:
Download the client for your OS:
Unzip the download package. Ngrok is now ready to use. It has no installer and no dependencies.
Run the executable and use the ‘http’ command to create a tunnel:
The tunnel is now created and traffic is being forwarded.
Ngrok has an abundance of extra functionality as well, some available in the free version and some relying on a paid plan. The free functionality includes request inspection, request replay, and username/password endpoint authentication, among others. Paid plans allow custom subdomains, multisession endpoint persistence, and lots of customization options.
The combination of functionality and ease-of-use makes ngrok a great addition to every web developer’s toolbox. The problem that it solves is a common one, and it solves that problem without introducing the overhead typical of new tools and extensions. In fact, I’ve found the most difficult thing about using ngrok is pronouncing it correctly: en-grok (not en-gee-rok, as many who have worked with Angular or AngularJS will be tempted to pronounce it). But once I get past my struggle to say the name, my opinion is always the same on ngrok – it’s a great tool and everyone should know about it.