Registry / devops / vite-plugin-cloudflare-tunnel

vite-plugin-cloudflare-tunnel

library1.0.12jsnpmunverified

A Vite plugin (v1.0.12) that automatically creates and manages Cloudflare tunnels for local development, exposing local dev servers to the internet with HTTPS without port forwarding. Offers two modes: Quick Tunnel (zero-config, generates random trycloudflare.com URL) and Named Tunnel (custom domains via Cloudflare API). Requires Vite 4/5/7 and Node >=16. Releases via npm; TypeScript types included. Simpler than manual cloudflared usage or ngrok alternatives.

devops http-networking web-framework

npm install vite-plugin-cloudflare-tunnel

github ↗package ↗

INSTALL

IMPORT

SIG · VITE-PLUGIN-CLOUDF

vite-plugin-cloudflare-tunnel

devopsjavascriptv1.0.12

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

cloudflareTunnel

✓ import cloudflareTunnel from 'vite-plugin-cloudflare-tunnel'

✗ import { cloudflareTunnel } from 'vite-plugin-cloudflare-tunnel'

This is the default export; named import will fail. TypeScript definitions are included.

default import (CommonJS require)

✓ const cloudflareTunnel = require('vite-plugin-cloudflare-tunnel').default

✗ const cloudflareTunnel = require('vite-plugin-cloudflare-tunnel')

CommonJS require must access .default. For ESM projects, use default import.

CloudflareTunnelOptions (TypeScript type)

✓ import type { CloudflareTunnelOptions } from 'vite-plugin-cloudflare-tunnel'

Type is not exported as a value; only use for type annotations.

Zero-configuration setup: imports the plugin and adds it to Vite's plugin array. Running npm run dev will print a public https://*.trycloudflare.com URL.

// vite.config.ts import { defineConfig } from 'vite'; import cloudflareTunnel from 'vite-plugin-cloudflare-tunnel'; export default defineConfig({ plugins: [ cloudflareTunnel() // Quick Tunnel mode – no config needed ] });

Debug

Known issues

gotchaThe plugin requires cloudflared binary to be installed. It attempts to download it automatically, but may fail in restricted environments.

fix

Install cloudflared manually via package manager or ensure internet access for automatic download.

affects: >=1.0.0

gotchaNamed Tunnel mode requires CLOUDFLARE_API_KEY environment variable or apiToken option with correct permissions (Cloudflare Tunnel:Edit, SSL/Certs:Edit, DNS:Edit). Missing or wrong permissions cause cryptic errors.

fix

Set CLOUDFLARE_API_KEY environment variable. If passing apiToken, use string value, not object.

affects: >=1.0.0

gotchaQuick Tunnel mode (no options) does NOT require any Cloudflare account or API token. It uses trycloudflare.com subdomain which is ephemeral and may be blocked on corporate networks requiring HTTPS inspection.

fix

Use Named Tunnel mode if you need a persistent URL or if corporate firewall blocks trycloudflare.com.

affects: >=1.0.0

deprecatedThe package README references vite ^4.0.0 || ^5.0.0 || ^7.0.0 as peer dep, but Vite 7 might not be released yet. Ensure compatibility with your Vite version.

fix

Use Vite 4 or 5; Vite 6 may be incompatible unless the plugin explicitly supports it.

affects: >=1.0.0

gotchaThe plugin starts the tunnel asynchronously after Vite dev server boots. Hot reload works but initial page load on the tunnel URL may have a brief delay while tunnel is established.

fix

Wait a few seconds after dev server starts before accessing tunnel URL.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Cannot find module 'cloudflared'

Automatic cloudflared download failed or was blocked.

fix

Manually install cloudflared (e.g., 'npm install -g cloudflared' or download from Cloudflare), or ensure network access.

TypeError: cloudflareTunnel is not a function

Using named import instead of default import.

fix

Change to 'import cloudflareTunnel from 'vite-plugin-cloudflare-tunnel'' (no curly braces).

Invalid token: The token provided is not valid

CLOUDFLARE_API_KEY environment variable is not set or incorrect for Named Tunnel mode.

fix

Set CLOUDFLARE_API_KEY to a valid Cloudflare API token with proper permissions.

Error: You need to specify a hostname or leave empty for quick tunnel

Passed an empty object or invalid options to cloudflareTunnel({}) where hostname is missing for named tunnel mode.

fix

Either call cloudflareTunnel() without arguments for quick mode, or provide hostname and tunnelName for named mode.

Upgrade

Version history

1.0.12latest on npm

Audit

Dependencies

viterequiredPeer dependency; plugin integrates with Vite's dev server lifecycle.

Agent activity

20 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/eastlondoner/vite-plugin-cloudflare-tunnel ↗

packagehttps://www.npmjs.com/package/vite-plugin-cloudflare-tunnel ↗