unplugin-cloudflare-tunnel 0.0.5 → 0.1.1

package/.github/README.md

@@ -1,23 +1,21 @@
 # unplugin-cloudflare-tunnel
 
-[![NPM version](https://img.shields.io/npm/v/unplugin-cloudflare-tunnel?color=a1b858&label=)](https://npm.im/unplugin-cloudflare-tunnel)
-[![pkg.pr.new](https://pkg.pr.new/badge/o-az/unplugin-cloudflare-tunnel)](https://pkg.pr.new/~/o-az/unplugin-cloudflare-tunnel)
+[![Open on npmx.dev](https://npmx.dev/api/registry/badge/version/unplugin-cloudflare-tunnel)](https://npmx.dev/package/unplugin-cloudflare-tunnel) [![pkg.pr.new](https://pkg.pr.new/badge/o-az/unplugin-cloudflare-tunnel)](https://pkg.pr.new/~/o-az/unplugin-cloudflare-tunnel)
 
-A plugin that automatically creates and manages Cloudflare tunnels for local development.
-Available for:
+A plugin that automatically creates and manages Cloudflare tunnels for local development. Available for:
 
-- [Vite](https://vite.dev),
+- [Vite](https://vite.dev)
 - [Rspack](https://rspack.rs)
 - [Webpack](https://webpack.js.org)
+- [esbuild](https://esbuild.github.io)
+- [Rollup](https://rollupjs.org)
+- [Rolldown](https://rolldown.rs)
 - [Astro](https://astro.build) <sup>soon</sup>
 - [Farm](https://farmfe.org) <sup>soon</sup>
-- [esbuild](https://esbuild.github.io) <sup>soon</sup>
-- [Rollup](https://rollupjs.org) <sup>soon</sup>
-- [Rolldown](https://rolldown.rs) <sup>soon</sup>
 
 > [!NOTE]
-> This is under active development.
-> If you have any suggestions, I'm all ears, please open an issue.
+>
+> This is under active development. If you have any suggestions, I'm all ears, please open an issue.
 
 ## Install
 
@@ -29,21 +27,89 @@ npm add unplugin-cloudflare-tunnel
 
 ## Usage
 
+### Modes
+
+The plugin supports two modes:
+
+- **Quick mode**: temporary `trycloudflare.com` URL, no Cloudflare credentials required
+- **Named mode**: persistent tunnel on your own hostname
+
+Mode selection rules:
+
+- `mode: 'quick'` → always quick mode
+- `mode: 'named'` → always named mode, requires `hostname`
+- if `mode` is omitted:
+  - `hostname` provided → named mode
+  - otherwise → quick mode
+
+### Common options
+
+- `mode?: 'quick' | 'named'`
+- `protocol?: 'http2' | 'quic'` — defaults to `http2` for better local dev reliability
+- `logLevel?: 'debug' | 'info' | 'warn' | 'error' | 'fatal'`
+- `port?: number`
+- `logFile?: string`
+- `debug?: boolean`
+- `enabled?: boolean`
+
+> [!TIP]
+>
+> For esbuild, Rollup, and Rolldown dev usage, set `port` explicitly so the tunnel can target the local dev server.
+
+### Quick mode example
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite'
+import CloudflareTunnel from 'unplugin-cloudflare-tunnel/vite'
+
+export default defineConfig({
+  plugins: [
+    CloudflareTunnel({
+      mode: 'quick',
+      protocol: 'http2'
+    })
+  ]
+})
+```
+
+### Named mode example
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite'
+import CloudflareTunnel from 'unplugin-cloudflare-tunnel/vite'
+
+export default defineConfig({
+  plugins: [
+    CloudflareTunnel({
+      mode: 'named',
+      hostname: 'dev.example.com',
+      apiToken: process.env.CLOUDFLARE_API_TOKEN,
+      protocol: 'http2'
+    })
+  ]
+})
+```
+
 <details>
 <summary>Vite</summary><br>
 
 ```ts
 // vite.config.ts
+import { defineConfig } from 'vite'
 import CloudflareTunnel from 'unplugin-cloudflare-tunnel/vite'
 
 export default defineConfig({
   plugins: [
-    CloudflareTunnel(),
-  ],
+    CloudflareTunnel({
+      mode: 'quick'
+    })
+  ]
 })
 ```
 
-Example in [./example/vite.config.ts](../example/vite.config.ts): `bun --filter example dev:vite`
+Example in [./example/vite.config.ts](../example/vite.config.ts): `cd example && bun run dev:vite`
 
 <br></details>
 
@@ -56,13 +122,11 @@ import CloudflareTunnel from 'unplugin-cloudflare-tunnel/rspack'
 
 export default {
   /* ... */
-  plugins: [
-    CloudflareTunnel(),
-  ]
+  plugins: [CloudflareTunnel()]
 }
 ```
 
-Example in [./example/rspack.config.ts](../example/rspack.config.ts): `bun --filter example dev:rspack`
+Example in [./example/rspack.config.ts](../example/rspack.config.ts): `cd example && bun run dev:rspack`
 
 <br></details>
 
@@ -71,23 +135,116 @@ Example in [./example/rspack.config.ts](../example/rspack.config.ts): `bun --fil
 
 ```ts
 // webpack.config.js
+const CloudflareTunnel = require('unplugin-cloudflare-tunnel/webpack')
+
 module.exports = {
   /* ... */
+  plugins: [CloudflareTunnel()]
+}
+```
+
+Example in [./example/webpack.config.ts](../example/webpack.config.ts): `cd example && bun run dev:webpack`
+
+<br></details>
+
+<details>
+<summary>esbuild</summary><br>
+
+```ts
+// esbuild.config.ts
+import { context } from 'esbuild'
+import CloudflareTunnel from 'unplugin-cloudflare-tunnel/esbuild'
+
+const ctx = await context({
+  entryPoints: ['./main.mjs'],
+  bundle: true,
+  outdir: './dist',
+  outExtension: { '.js': '.mjs' },
+  define: {
+    __VIA_TOOL__: JSON.stringify('esbuild')
+  },
   plugins: [
-    require('unplugin-cloudflare-tunnel/webpack')({
-      CloudflareTunnel(),
+    CloudflareTunnel({
+      hostname: 'dev.example.com',
+      apiToken: process.env.CLOUDFLARE_API_TOKEN,
+      port: 6420
+    })
   ]
-}
+})
+
+await ctx.watch()
+await ctx.serve({ port: 6420, servedir: './dist' })
+```
+
+Example in [./example/esbuild.config.ts](../example/esbuild.config.ts): `cd example && bun run esbuild.config.ts`
+
+> [!NOTE]
+>
+> esbuild dev usage requires an explicit `port` option.
+
+<br></details>
+
+<details>
+<summary>Rollup</summary><br>
+
+```ts
+// rollup.config.ts
+import { defineConfig } from 'rollup'
+import CloudflareTunnel from 'unplugin-cloudflare-tunnel/rollup'
+
+export default defineConfig({
+  /* ... */
+  plugins: [
+    CloudflareTunnel({
+      hostname: 'dev.example.com',
+      apiToken: process.env.CLOUDFLARE_API_TOKEN,
+      port: 6421
+    })
+  ]
+})
+```
+
+Example in [./example/rollup.config.ts](../example/rollup.config.ts): `cd example && bun run dev:rollup`
+
+> [!NOTE]
+>
+> Rollup dev usage requires an explicit `port` option.
+
+<br></details>
+
+<details>
+<summary>Rolldown</summary><br>
+
+```ts
+// rolldown.config.ts
+import { defineConfig } from 'rolldown'
+import CloudflareTunnel from 'unplugin-cloudflare-tunnel/rolldown'
+
+export default defineConfig({
+  /* ... */
+  plugins: [
+    CloudflareTunnel({
+      hostname: 'dev.example.com',
+      apiToken: process.env.CLOUDFLARE_API_TOKEN,
+      port: 6422
+    })
+  ]
+})
 ```
 
-Example in [./example/webpack.config.ts](../example/webpack.config.ts): `bun --filter example dev:webpack`
+Example in [./example/rolldown.config.ts](../example/rolldown.config.ts): `cd example && bun run dev:rolldown`
+
+> [!NOTE]
+>
+> Rolldown dev usage requires an explicit `port` option.
 
 <br></details>
 
 ## Virtual Module: Access Tunnel URL
 
 > [!NOTE]
-> This feature is only available in Vite and Vite-based frameworks (i.e., Astro)
+>
+> This feature is available in supported dev integrations, including Vite, Webpack, Rspack, esbuild, Rollup, and Rolldown.
 
 The plugin provides a virtual module that allows you to access the tunnel URL in your application code during development. This is useful for:
 
@@ -98,7 +255,7 @@ The plugin provides a virtual module that allows you to access the tunnel URL in
 
 ### Usage
 
-```typescript
+```ts
 import { getTunnelUrl } from 'virtual:unplugin-cloudflare-tunnel'
 
 // Get the current tunnel URL
@@ -117,14 +274,14 @@ shareButton.onclick = () => {
 
 To get TypeScript support for the virtual module, add a reference to the types:
 
-```typescript
+```ts
 // In your tsconfig.json or a .d.ts file
 /// <reference types="unplugin-cloudflare-tunnel/virtual" />
 ```
 
 Or create a `virtual.d.ts` file in your project:
 
-```typescript
+```ts
 /// <reference types="unplugin-cloudflare-tunnel/virtual" />
 ```
 
@@ -134,6 +291,12 @@ Or create a `virtual.d.ts` file in your project:
 - **Named tunnel mode**: Returns your custom domain URL like `https://dev.example.com`
 - **Plugin disabled**: Returns an empty string `""`
 
+### Notes on modes
+
+- Named-only options such as `hostname`, `apiToken`, `accountId`, `zoneId`, `tunnelName`, `dns`, `ssl`, and `cleanup` are only valid in named mode.
+- Quick mode ignores Cloudflare account setup entirely and creates an ephemeral tunnel.
+- `protocol` applies to both quick and named modes.
+
 ### Notes
 
 - The virtual module is only available during development mode

package/dist/astro.d.mts

@@ -1,4 +1,4 @@
-import { CloudflareTunnelOptions } from "./index.mjs";
+import { t as CloudflareTunnelOptions } from "./options-DI3sWmXl.mjs";
 
 //#region src/astro.d.ts
 declare const _default: (options: CloudflareTunnelOptions) => any;

package/dist/astro.mjs

@@ -1,8 +1,9 @@
-import { CloudflareTunnel } from "./index.mjs";
+import { t as CloudflareTunnel } from "./src-D0eR3kCb.mjs";
 //#region src/astro.ts
 var astro_default = (options) => ({
 	name: "unplugin-cloudflare-tunnel",
 	hooks: { "astro:config:setup": async (astro) => {
+		astro.config.vite ||= {};
 		astro.config.vite.plugins ||= [];
 		astro.config.vite.plugins.push(CloudflareTunnel.vite(options));
 	} }

package/dist/esbuild.d.mts

@@ -1,4 +1,4 @@
-import { CloudflareTunnelOptions } from "./index.mjs";
+import { t as CloudflareTunnelOptions } from "./options-DI3sWmXl.mjs";
 import * as _$esbuild from "esbuild";
 
 //#region src/esbuild.d.ts

package/dist/esbuild.mjs

@@ -1,4 +1,4 @@
-import { CloudflareTunnel } from "./index.mjs";
+import { t as CloudflareTunnel } from "./src-D0eR3kCb.mjs";
 //#region src/esbuild.ts
 /**
 * This entry file is for esbuild plugin.

package/dist/farm.d.mts

@@ -1,4 +1,4 @@
-import { CloudflareTunnelOptions } from "./index.mjs";
+import { t as CloudflareTunnelOptions } from "./options-DI3sWmXl.mjs";
 
 //#region src/farm.d.ts
 /**

package/dist/farm.mjs

@@ -1,4 +1,4 @@
-import { CloudflareTunnel } from "./index.mjs";
+import { t as CloudflareTunnel } from "./src-D0eR3kCb.mjs";
 //#region src/farm.ts
 /**
 * This entry file is for Farm plugin.

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { a as ZodMiniObject, c as ZodMiniUnknown, i as ZodMiniNumber, l as output, n as ZodMiniBoolean, o as ZodMiniOptional, r as ZodMiniNullable, s as ZodMiniString, t as ZodMiniArray, u as $strip } from "./schemas-DKJtFAG_.mjs";
+import { t as CloudflareTunnelOptions } from "./options-DI3sWmXl.mjs";
 import { UnpluginInstance } from "unplugin";
 
 //#region src/index.d.ts
@@ -13,155 +13,6 @@ import { UnpluginInstance } from "unplugin";
 * @version 1.0.0
 * @license MIT
 */
-declare const CloudflareApiResponseSchema: ZodMiniObject<{
-  success: ZodMiniBoolean<boolean>;
-  errors: ZodMiniOptional<ZodMiniArray<ZodMiniObject<{
-    code: ZodMiniNumber<number>;
-    message: ZodMiniString<string>;
-  }, $strip>>>;
-  messages: ZodMiniOptional<ZodMiniArray<ZodMiniString<string>>>;
-  result: ZodMiniUnknown;
-}, $strip>;
-declare const AccountSchema: ZodMiniObject<{
-  id: ZodMiniString<string>;
-  name: ZodMiniString<string>;
-}, $strip>;
-declare const ZoneSchema: ZodMiniObject<{
-  id: ZodMiniString<string>;
-  name: ZodMiniString<string>;
-}, $strip>;
-declare const TunnelSchema: ZodMiniObject<{
-  id: ZodMiniString<string>;
-  name: ZodMiniString<string>;
-  account_tag: ZodMiniString<string>;
-  created_at: ZodMiniString<string>;
-  connections: ZodMiniOptional<ZodMiniArray<ZodMiniUnknown>>;
-}, $strip>;
-declare const DNSRecordSchema: ZodMiniObject<{
-  id: ZodMiniString<string>;
-  type: ZodMiniString<string>;
-  name: ZodMiniString<string>;
-  content: ZodMiniString<string>;
-  proxied: ZodMiniBoolean<boolean>;
-  comment: ZodMiniOptional<ZodMiniNullable<ZodMiniString<string>>>;
-}, $strip>;
-type CloudflareApiResponse<T = unknown> = output<typeof CloudflareApiResponseSchema> & {
-  result: T;
-};
-type Account = output<typeof AccountSchema>;
-type Zone = output<typeof ZoneSchema>;
-type Tunnel = output<typeof TunnelSchema>;
-type DNSRecord = output<typeof DNSRecordSchema>;
-/**
- * Base configuration options shared between named and quick tunnel modes
- */
-interface BaseTunnelOptions {
-  /**
-   * Local port your dev server listens on
-   * If not specified, will automatically use the bundler's configured port
-   * @default undefined (auto-detect from bundler config)
-   */
-  port?: number;
-  /**
-   * Path to write cloudflared logs to a file
-   * Useful for debugging tunnel issues
-   */
-  logFile?: string;
-  /**
-   * Log level for cloudflared process
-   * @default undefined (uses cloudflared default)
-   */
-  logLevel?: 'debug' | 'info' | 'warn' | 'error' | 'fatal';
-  /**
-   * Enable additional verbose logging for easier debugging.
-   * When true, the plugin will output extra information prefixed with
-   * `[cloudflare-tunnel:debug]`.
-   * @default false
-   */
-  debug?: boolean;
-  /**
-   * Enable or disable the tunnel plugin. When set to `false` the plugin is
-   * completely disabled — cloudflared will NOT be downloaded or started.
-   * @default true
-   */
-  enabled?: boolean;
-}
-/**
- * Configuration options for named tunnel mode (requires hostname and API token)
- */
-interface NamedTunnelOptions extends BaseTunnelOptions {
-  /**
-   * Public hostname for the tunnel (e.g., "dev.example.com")
-   * Must be a domain in your Cloudflare account
-   */
-  hostname: string;
-  /**
-   * Cloudflare API token with required permissions:
-   * - Zone:Zone:Read
-   * - Zone:DNS:Edit
-   * - Account:Cloudflare Tunnel:Edit
-   *
-   * Fallback priority:
-   * 1. Provided apiToken option
-   * 2. CLOUDFLARE_API_TOKEN environment variable
-   */
-  apiToken?: string;
-  /**
-   * Cloudflare account ID
-   * If omitted, uses the first account associated with the API token
-   */
-  accountId?: string;
-  /**
-   * Cloudflare zone ID
-   * If omitted, automatically resolved from the hostname
-   */
-  zoneId?: string;
-  /**
-   * Name for the tunnel in your Cloudflare dashboard
-   * Must contain only letters, numbers, and hyphens. Cannot start or end with a hyphen.
-   * @default "dev-tunnel"
-   */
-  tunnelName?: string;
-  /**
-   * Wildcard DNS domain to ensure exists (e.g., "*.example.com").
-   * When provided the plugin will ensure both A and AAAA records exist.
-   */
-  dns?: string;
-  /**
-   * Wildcard SSL domain to ensure exists (e.g., "*.example.com").
-   * When provided the plugin will request/ensure a wildcard edge certificate.
-   * If omitted the plugin will attempt to detect an existing wildcard certificate
-   * or Total TLS; otherwise it will request a regular certificate for the provided hostname.
-   */
-  ssl?: string;
-  /**
-   * Cleanup configuration for managing orphaned resources
-   */
-  cleanup?: {
-    /**
-     * Whether to automatically clean up orphaned DNS records on startup
-     * @default true
-     */
-    autoCleanup?: boolean;
-    /**
-     * Array of tunnel names to preserve during cleanup (in addition to current tunnel)
-     * @default []
-     */
-    preserveTunnels?: Array<string>;
-  };
-}
-/**
- * Configuration options for quick tunnel mode (no hostname required, generates random URL)
- */
-interface QuickTunnelOptions extends BaseTunnelOptions {}
-/**
- * Configuration options for the Cloudflare Tunnel plugin
- *
- * Two modes are supported:
- * - Named tunnel mode: Provide `hostname` for a persistent tunnel with custom domain
- * - Quick tunnel mode: Omit `hostname` for a temporary tunnel with random trycloudflare.com URL
- */
-type CloudflareTunnelOptions = NamedTunnelOptions | QuickTunnelOptions;
 declare const CloudflareTunnel: UnpluginInstance<CloudflareTunnelOptions | undefined, false>;
 //#endregion
-export { Account, CloudflareApiResponse, CloudflareTunnel, CloudflareTunnel as default, CloudflareTunnelOptions, DNSRecord, Tunnel, Zone };
+export { CloudflareTunnel, CloudflareTunnel as default };