vite-plugin-ngrok

2.0.1 verified Mon Apr 27 auth: no javascript

Vite plugin (v2.0.1) for automatically creating ngrok tunnels during local development, enabling instant sharing of local Vite dev servers over the internet. Uses the official @ngrok/ngrok JavaScript SDK. Supports configuration via string (auth token) or full ngrok Config object. Dynamically updates URLs on server restart or tunnel reopen. Peer dependency on Vite ^5.4.12, ^6.0.0, or ^7.0.0. Ships TypeScript types. Differentiator: minimal setup (single line plugin) vs manual ngrok CLI or separate tools.

Common errors

error Error: Cannot find module '@ngrok/ngrok' ↓

cause @ngrok/ngrok is not installed or is a missing dependency.

fix

Run 'npm install @ngrok/ngrok' (or your package manager equivalent) and ensure it is in your dependencies.

error TypeError: ngrok is not a function ↓

cause Default import used instead of named import.

fix

Use import { ngrok } from 'vite-plugin-ngrok' instead of import ngrok from 'vite-plugin-ngrok'.

error Error: The 'authtoken' property must be a string ↓

cause An object was passed to ngrok() that does not have a valid authtoken or authtoken_from_env set.

fix

Ensure the object contains either authtoken: 'YOUR_TOKEN' or authtoken_from_env: true (and NGROK_AUTHTOKEN env var is set).

error error:0308010C:digital envelope routines::unsupported ↓

cause This error is not from vite-plugin-ngrok itself, but occurs when using ngrok tunnels with older Node.js versions (e.g., Node 17+ with OpenSSL 3).

fix

Set environment variable NODE_OPTIONS=--openssl-legacy-provider or upgrade Node.js.

Warnings

breaking In v2.0.0, the plugin switched from @ngrok/ngrok SDK v1 to v2, which has breaking changes in configuration options (see ngrok SDK changelog). ↓

fix Update your ngrok config object to match @ngrok/ngrok v2 API. If using string argument, API remains same.

breaking In v2.0.0, the peer dependency on Vite changed to '^5.4.12 || ^6.0.0 || ^7.0.0'. Vite versions below 5.4.12 are no longer supported. ↓

fix Upgrade Vite to ^5.4.12, ^6.0.0, or ^7.0.0.

deprecated Passing a plain string with the auth token directly in code is discouraged for security reasons (token stored in git). ↓

fix Use environment variables: load via loadEnv() or process.env, or set authtoken_from_env: true and set NGROK_AUTHTOKEN env var.

gotcha The plugin only creates tunnels during local dev (vite dev). It does not run during build (vite build). ↓

fix This is by design. Do not expect tunnels in production builds.

gotcha When passing an object to ngrok(), the default port from Vite is automatically set, but any explicitly provided port will override that default. ↓

fix If you need a specific port, set it in the ngrok config object. Otherwise, Vite's dev port is used automatically.

Install

npm install vite-plugin-ngrok

yarn add vite-plugin-ngrok

pnpm add vite-plugin-ngrok

Imports

ngrok
wrong
```
import ngrok from 'vite-plugin-ngrok'
```
correct
```
import { ngrok } from 'vite-plugin-ngrok'
```
The plugin exports a named export 'ngrok'. Default import is not available.

default

wrong

const ngrok = require('vite-plugin-ngrok')

correct

import { ngrok } from 'vite-plugin-ngrok'

Package is ESM-only. CommonJS require will not work.

type
```
import type { ngrok } from 'vite-plugin-ngrok'
```
TypeScript type import for type-checking only. The 'ngrok' export is a function.

Quickstart

Basic usage: configure ngrok plugin with auth token from environment variable. Requires @ngrok/ngrok and Vite as dependencies.

// vite.config.ts
import { defineConfig } from 'vite'
import { ngrok } from 'vite-plugin-ngrok'

export default defineConfig({
  plugins: [
    ngrok(process.env.NGROK_AUTH_TOKEN ?? ''),
  ],
})