unplugin-cloudflare-tunnel 0.0.4 → 0.1.0

package/.github/README.md

@@ -29,16 +29,80 @@ 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`
+
+### 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',
+    }),
   ],
 })
 ```
@@ -134,6 +198,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/api.d.mts

@@ -1,42 +1,45 @@
-import * as z from "zod/mini";
+import { a as ZodMiniObject, c as ZodMiniUnknown, i as ZodMiniNumber, n as ZodMiniBoolean, o as ZodMiniOptional, r as ZodMiniNullable, s as ZodMiniString, t as ZodMiniArray, u as $strip } from "./schemas-DKJtFAG_.mjs";
 
 //#region src/api.d.ts
-declare const CloudflareErrorSchema: z.ZodMiniObject<{
-  code: z.ZodMiniNumber<number>;
-  message: z.ZodMiniString<string>;
-}, z.core.$strip>;
-declare const CloudflareApiResponseSchema: z.ZodMiniObject<{
-  success: z.ZodMiniBoolean<boolean>;
-  errors: z.ZodMiniOptional<z.ZodMiniArray<z.ZodMiniObject<{
-    code: z.ZodMiniNumber<number>;
-    message: z.ZodMiniString<string>;
-  }, z.core.$strip>>>;
-  messages: z.ZodMiniOptional<z.ZodMiniArray<z.ZodMiniString<string>>>;
-  result: z.ZodMiniUnknown;
-}, z.core.$strip>;
-declare const AccountSchema: z.ZodMiniObject<{
-  id: z.ZodMiniString<string>;
-  name: z.ZodMiniString<string>;
-}, z.core.$strip>;
-declare const ZoneSchema: z.ZodMiniObject<{
-  id: z.ZodMiniString<string>;
-  name: z.ZodMiniString<string>;
-}, z.core.$strip>;
-declare const TunnelSchema: z.ZodMiniObject<{
-  id: z.ZodMiniString<string>;
-  name: z.ZodMiniString<string>;
-  account_tag: z.ZodMiniString<string>;
-  created_at: z.ZodMiniString<string>;
-  connections: z.ZodMiniOptional<z.ZodMiniArray<z.ZodMiniUnknown>>;
-}, z.core.$strip>;
-declare const DNSRecordSchema: z.ZodMiniObject<{
-  id: z.ZodMiniString<string>;
-  type: z.ZodMiniString<string>;
-  name: z.ZodMiniString<string>;
-  content: z.ZodMiniString<string>;
-  proxied: z.ZodMiniBoolean<boolean>;
-  comment: z.ZodMiniOptional<z.ZodMiniNullable<z.ZodMiniString<string>>>;
-}, z.core.$strip>;
+declare const CloudflareErrorSchema: ZodMiniObject<{
+  code: ZodMiniNumber<number>;
+  message: ZodMiniString<string>;
+}, $strip>;
+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>;
+  account: ZodMiniOptional<ZodMiniObject<{
+    id: ZodMiniString<string>;
+  }, $strip>>;
+}, $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>;
 declare function normalizeAddress(address: string | {
   address?: string;
   port?: number;

package/dist/api.mjs

@@ -1,7 +1,6 @@
-import { a as number, c as string, i as nullish, l as unknown, n as array, o as object, r as boolean, s as optional } from "./schemas-CwcXCIyR.mjs";
+import { a as number, c as string, i as nullish, l as unknown, n as array, o as object, r as boolean, s as optional } from "./schemas-Cpk3vGGi.mjs";
 import NodeFS from "node:fs/promises";
 import { install } from "cloudflared";
-
 //#region src/api.ts
 const CloudflareErrorSchema = object({
 	code: number(),
@@ -19,7 +18,8 @@ const AccountSchema = object({
 });
 const ZoneSchema = object({
 	id: string(),
-	name: string()
+	name: string(),
+	account: optional(object({ id: string() }))
 });
 const TunnelSchema = object({
 	id: string(),
@@ -54,6 +54,5 @@ async function ensureCloudflaredBinary(binPath) {
 function getLocalTarget(host, port) {
 	return `http://${host.includes(":") ? `[${host}]` : host}:${port}`;
 }
-
 //#endregion
-export { AccountSchema, CloudflareApiResponseSchema, CloudflareErrorSchema, DNSRecordSchema, TunnelSchema, ZoneSchema, ensureCloudflaredBinary, getLocalTarget, normalizeAddress };
+export { AccountSchema, CloudflareApiResponseSchema, CloudflareErrorSchema, DNSRecordSchema, TunnelSchema, ZoneSchema, ensureCloudflaredBinary, getLocalTarget, normalizeAddress };

package/dist/astro.mjs

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

package/dist/esbuild.d.mts

@@ -1,8 +1,7 @@
 import { CloudflareTunnelOptions } from "./index.mjs";
-import * as esbuild0 from "esbuild";
+import * as _$esbuild from "esbuild";
 
 //#region src/esbuild.d.ts
-
 /**
  * This entry file is for esbuild plugin.
  *
@@ -19,6 +18,6 @@ import * as esbuild0 from "esbuild";
  * build({ plugins: [Starter()] })
 ```
  */
-declare const esbuild: (options?: CloudflareTunnelOptions | undefined) => esbuild0.Plugin;
+declare const esbuild: (options?: CloudflareTunnelOptions | undefined) => _$esbuild.Plugin;
 //#endregion
 export { esbuild as default, esbuild as "module.exports" };

package/dist/esbuild.mjs

@@ -1,5 +1,4 @@
 import { CloudflareTunnel } from "./index.mjs";
-
 //#region src/esbuild.ts
 /**
 * This entry file is for esbuild plugin.
@@ -18,7 +17,5 @@ import { CloudflareTunnel } from "./index.mjs";
 ```
 */
 const esbuild = CloudflareTunnel.esbuild;
-var esbuild_default = esbuild;
-
 //#endregion
-export { esbuild_default as default, esbuild as "module.exports" };
+export { esbuild as default, esbuild as "module.exports" };

package/dist/farm.d.mts

@@ -1,7 +1,6 @@
 import { CloudflareTunnelOptions } from "./index.mjs";
 
 //#region src/farm.d.ts
-
 /**
  * This entry file is for Farm plugin.
  *

package/dist/farm.mjs

@@ -1,5 +1,4 @@
 import { CloudflareTunnel } from "./index.mjs";
-
 //#region src/farm.ts
 /**
 * This entry file is for Farm plugin.
@@ -20,7 +19,5 @@ import { CloudflareTunnel } from "./index.mjs";
 * ```
 */
 const farm = CloudflareTunnel.farm;
-var farm_default = farm;
-
 //#endregion
-export { farm_default as default, farm as "module.exports" };
+export { farm as default, farm as "module.exports" };

package/dist/index.d.mts

@@ -1,5 +1,5 @@
+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 { UnpluginInstance } from "unplugin";
-import * as z from "zod/mini";
 
 //#region src/index.d.ts
 /**
@@ -13,49 +13,61 @@ import * as z from "zod/mini";
 * @version 1.0.0
 * @license MIT
 */
-declare const CloudflareApiResponseSchema: z.ZodMiniObject<{
-  success: z.ZodMiniBoolean<boolean>;
-  errors: z.ZodMiniOptional<z.ZodMiniArray<z.ZodMiniObject<{
-    code: z.ZodMiniNumber<number>;
-    message: z.ZodMiniString<string>;
-  }, z.core.$strip>>>;
-  messages: z.ZodMiniOptional<z.ZodMiniArray<z.ZodMiniString<string>>>;
-  result: z.ZodMiniUnknown;
-}, z.core.$strip>;
-declare const AccountSchema: z.ZodMiniObject<{
-  id: z.ZodMiniString<string>;
-  name: z.ZodMiniString<string>;
-}, z.core.$strip>;
-declare const ZoneSchema: z.ZodMiniObject<{
-  id: z.ZodMiniString<string>;
-  name: z.ZodMiniString<string>;
-}, z.core.$strip>;
-declare const TunnelSchema: z.ZodMiniObject<{
-  id: z.ZodMiniString<string>;
-  name: z.ZodMiniString<string>;
-  account_tag: z.ZodMiniString<string>;
-  created_at: z.ZodMiniString<string>;
-  connections: z.ZodMiniOptional<z.ZodMiniArray<z.ZodMiniUnknown>>;
-}, z.core.$strip>;
-declare const DNSRecordSchema: z.ZodMiniObject<{
-  id: z.ZodMiniString<string>;
-  type: z.ZodMiniString<string>;
-  name: z.ZodMiniString<string>;
-  content: z.ZodMiniString<string>;
-  proxied: z.ZodMiniBoolean<boolean>;
-  comment: z.ZodMiniOptional<z.ZodMiniNullable<z.ZodMiniString<string>>>;
-}, z.core.$strip>;
-type CloudflareApiResponse<T = unknown> = z.infer<typeof CloudflareApiResponseSchema> & {
+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>;
+  account: ZodMiniOptional<ZodMiniObject<{
+    id: ZodMiniString<string>;
+  }, $strip>>;
+}, $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 = z.infer<typeof AccountSchema>;
-type Zone = z.infer<typeof ZoneSchema>;
-type Tunnel = z.infer<typeof TunnelSchema>;
-type DNSRecord = z.infer<typeof DNSRecordSchema>;
+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 {
+  /**
+   * Tunnel mode.
+   * - `quick`: temporary `trycloudflare.com` URL, no hostname required
+   * - `named`: persistent tunnel using your configured hostname
+   *
+   * When omitted, the plugin uses named mode if `hostname` is provided,
+   * otherwise it uses quick mode.
+   */
+  mode?: 'quick' | 'named';
   /**
    * Local port your dev server listens on
    * If not specified, will automatically use the bundler's configured port
@@ -68,10 +80,19 @@ interface BaseTunnelOptions {
    */
   logFile?: string;
   /**
-   * Log level for cloudflared process
-   * @default undefined (uses cloudflared default)
+   * Log level for cloudflared output shown by the plugin.
+   * The plugin still runs cloudflared with at least `info` internally so it can
+   * detect tunnel readiness and print the tunnel URL.
+   * @default undefined
    */
   logLevel?: 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+  /**
+   * Transport protocol used by cloudflared.
+   * `http2` is the default because it is more reliable for local development
+   * networks than QUIC.
+   * @default 'http2'
+   */
+  protocol?: 'http2' | 'quic';
   /**
    * Enable additional verbose logging for easier debugging.
    * When true, the plugin will output extra information prefixed with
@@ -103,7 +124,7 @@ interface NamedTunnelOptions extends BaseTunnelOptions {
    *
    * Fallback priority:
    * 1. Provided apiToken option
-   * 2. CLOUDFLARE_API_KEY environment variable
+   * 2. CLOUDFLARE_API_TOKEN environment variable
    */
   apiToken?: string;
   /**
@@ -158,8 +179,8 @@ 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
+ * - Named tunnel mode: set `mode: 'named'` or provide `hostname`
+ * - Quick tunnel mode: set `mode: 'quick'` or omit `hostname`
  */
 type CloudflareTunnelOptions = NamedTunnelOptions | QuickTunnelOptions;
 declare const CloudflareTunnel: UnpluginInstance<CloudflareTunnelOptions | undefined, false>;