Vite Plugin Cloudflare Tunnel

1.0.12 verified Mon Apr 27 auth: no javascript

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.

Common errors

error Error: Cannot find module 'cloudflared' ↓

cause 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.

error TypeError: cloudflareTunnel is not a function ↓

cause Using named import instead of default import.

fix

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

error Invalid token: The token provided is not valid ↓

cause 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 Error: You need to specify a hostname or leave empty for quick tunnel ↓

cause 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.

Warnings

gotcha The 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.

gotcha Named 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.

gotcha Quick 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.

deprecated The 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.

gotcha The 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.

Install

npm install vite-plugin-cloudflare-tunnel

yarn add vite-plugin-cloudflare-tunnel

pnpm add vite-plugin-cloudflare-tunnel

Imports

cloudflareTunnel

wrong

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

correct

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

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

default import (CommonJS require)

wrong

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

correct

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

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.

Quickstart

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
  ]
});