# ![nx–ngrok — Secure tunnels for your targets.](https://github.com/domjtalbot/nx-ngrok/raw/main/.github/banner-3.png 'nx–ngrok — Secure tunnels for your targets.')

## Contents - [](#) - [Features](#features) - [Installing](#installing) - [Getting Started](#getting-started) - [Supported Environment Variables](#supported-environment-variables) - [Executors](#executors) - [`tunnel`](#tunnel) - [Generators](#generators) - [`tunnel`](#tunnel-1) - [Examples](#examples) - [Compatibility](#compatibility) - [Credits](#credits)
## Features - Use Ngrok to create a secure tunnel to your applications. - Manually define the tunnel settings. - Alternatively, let Ngrok wrap your existing targets to automatically read the server URL. - Generate a new Ngrok tunnel target for your existing apps.
## Installing Using [pnpm](http://pnpm.io): ```bash pnpm add -D nx-ngrok ```

Using npm

```bash npm install -D nx-ngrok ```

Using yarn

```bash yarn add -D nx-ngrok ```

## Getting Started Before you can serve HTML content, Ngrok requires you to [sign up for a free ngrok account](https://dashboard.ngrok.com/signup) to get an authtoken. It is recommended to follow Ngrok's documentation and [install your authtoken](https://dashboard.ngrok.com/get-started/your-authtoken). Alternatively, you can set the authtoken via an Environment Variable or as an option in each executor. > **Warning** > > Keep your authtoken private and safe. Do not commit it to git!
### Supported Environment Variables - `NGROK_AUTHTOKEN` - Specifies the authentication token ([authtoken](https://dashboard.ngrok.com/get-started/your-authtoken)) used to connect to the ngrok service.
## Executors ### `tunnel` Start a new Ngrok tunnel. ```json "targets": { "dev": { "executor": "nx-ngrok:tunnel", "options": { "target": "examples-nextjs:serve", }, }, } ```

tunnel executor options

| Name | Type | Required | Default | Description | | ------------- | ---------------------------------------- | :------: | --------------- | -------------------------------------------------------------------------------------------------------- | | `target` | `string` | - | - | Server target to run tunnel for. | | `protocol` | `http`, `tcp`, `tls` | - | `http` | The tunnel protocol name. This defines the type of tunnel you would like to start. | | `address` | `string`, `number` | - | - | Forward traffic to this local port number or network address. | | `auth` | `string` | - | - | HTTP Basic authentication for tunnel. | | `port` | `targetDefault`, `auto`, `number` | - | `targetDefault` | Override the target's port number — only supported if the target accepts a port setting. | | `subdomain` | `string` | - | - | Subdomain name to request. If unspecified, ngrok provides a unique subdomain based on your account type. | | `authToken` | `string` | - | - | Specifies the authentication token (authtoken) used to connect to the ngrok service. | | `region` | `us`, `eu`, `au`, `ap`, `sa`, `jp`, `in` | - | `us` | Choose the region where the ngrok agent will connect to host its tunnels. | | `ngrokConfig` | `string` | - | - | Custom path for ngrok config file. |

## Generators ### `tunnel` Generate a target to run a Ngrok tunnel for a local server. ```bash nx generate nx-grok:tunnel dev --project=my-app --target=serve ```

tunnel generator output

```bash > NX Generating nx-ngrok:tunnel UPDATE apps/my-app/project.json ```

tunnel generator options

| Name | Alias | Type | Required | Default | Description | | ----------- | --------------------------------- | ---------------------------------------- | :-------------: | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | | `name` | - | `string` | ✅ | - | Target name. | | `project` | - | `string` | ✅ | - | What project does the target belong to? | | `target` | - | `string` | - | - | Server target to run tunnel for. | | `port` | `targetDefault`, `auto`, `number` | - | `targetDefault` | Override the target's port number — only supported if the target accepts a port setting. | | `protocol` | - | `http`, `tcp`, `tls` | - | `http` | The tunnel protocol name. This defines the type of tunnel you would like to start. | | `address` | - | `string`, `number` | - | - | Forward traffic to this local port number or network address. | | `auth` | - | `string` | - | - | HTTP Basic authentication for tunnel. | | `subdomain` | - | `string` | - | - | Subdomain name to request. If unspecified, ngrok provides a unique subdomain based on your account type. | | `region` | - | `us`, `eu`, `au`, `ap`, `sa`, `jp`, `in` | - | `us` | Choose the region where the ngrok agent will connect to host its tunnels. |

## Examples | Name | Path | | ------- | --------------------------------------------------------------------------------------------- | | nest | [examples/nest](https://github.com/domjtalbot/nx-ngrok/tree/main/examples/nest) | | nextjs | [examples/nextjs](https://github.com/domjtalbot/nx-ngrok/tree/main/examples/nextjs) | | nx-mesh | [examples/nx-mesh-app](https://github.com/domjtalbot/nx-ngrok/tree/main/examples/nx-mesh-app) |
## Compatibility | `nx-ngrok` | Nx | | ---------- | --------- | | `^1.0.0` | `^15.7.1` |
## Credits This plugin wouldn't be possible without the great teams behind these projects: - [Ngrok](https://github.com/ngrok) - A simplified API-first ingress-as-a-service that adds connectivity, security, and observability to your apps in one line - [Ngrok Node API](https://github.com/bubenshchykov/ngrok) - A Node wrapper for Ngrok's API. - [Nrwl](https://github.com/nrwl) - The team behind [Nx](https://github.com/nrwl/nx) Please show them your support! ❤️

🌳 🦌 🌳