which-url 0.0.6 → 0.0.8

package/README.md

@@ -20,7 +20,7 @@ Preview       https://myapp-git-feat.vercel.app     "preview"
 Production    https://myapp.com                     "production"
 ```
 
-Works across environments (local, preview, production), runtimes (server, client, edge), and [platforms](#platform-support).
+Works across environments (local, preview, production), browser bundles, Node/Bun servers, and edge runtimes that expose compatible env vars through `process.env` or build-time public env replacement.
 
 The default export gives you everything as an object:
 
@@ -85,7 +85,31 @@ Reads environment variables that hosting providers set automatically:
 3. `window.location.origin` (browser fallback)
 4. `http://localhost:${PORT || 3000}` (development fallback)
 
-If nothing is detected in production, the singleton logs a warning and returns empty strings. Call `createUrl()` directly if you want it to throw instead.
+When you call `createUrl({ env })`, the passed object replaces `process.env` as the source for steps 1–2.
+
+If nothing is detected in production, the default singleton returns empty URL strings so imports stay safe in tests, client bundles, and build tools. Call `createUrl()` directly when a missing URL should throw.
+
+## Strict mode with `createUrl()`
+
+Use the default export or named constants for convenience:
+
+```typescript
+import { origin } from 'which-url'
+```
+
+Use `createUrl()` for production-critical configuration like auth, CORS, emails, and webhooks:
+
+```typescript
+import { createUrl } from 'which-url'
+
+const appUrl = createUrl()
+
+auth({ baseURL: appUrl.origin })
+```
+
+`createUrl()` resolves fresh environment values when called. If no URL can be detected in production, it throws with instructions to set `APP_URL`.
+
+For runtimes that pass env as an argument (e.g. Cloudflare Workers), call `createUrl({ env })` and the passed object replaces `process.env` for that resolution. See [Cloudflare Workers](#cloudflare-workers) below.
 
 ## Override with `APP_URL`
 
@@ -160,6 +184,8 @@ Zero config — [portless](https://portless.sh) sets `PORTLESS_URL` and `which-u
 origin → https://myapp.localhost
 ```
 
+When sharing via Tailscale (`portless run --tailscale`), `PORTLESS_TAILSCALE_URL` takes priority so `origin` returns the publicly-reachable URL.
+
 ### Tunnels (ngrok, Cloudflare Tunnel)
 
 Tunnel URLs can't be auto-detected — they're external to the app process. Set `APP_URL`:
@@ -170,29 +196,54 @@ APP_URL=https://abc123.ngrok-free.app npm run dev
 
 ### Cloudflare Workers
 
-Cloudflare Workers use runtime `env` bindings instead of `process.env`. Set `APP_URL` in `wrangler.toml`:
+Cloudflare Workers pass config through the `env` argument to `fetch`, not `process.env`. Pass it to `createUrl({ env })`:
+
+```typescript
+import { createUrl } from "which-url"
+
+export default {
+  async fetch(request: Request, env: Env) {
+    const appUrl = createUrl({ env })
+
+    return Response.json({ origin: appUrl.origin, env: appUrl.env })
+  },
+}
+```
 
 ```toml
+# wrangler.toml
 [vars]
-APP_URL = "https://myapp.workers.dev"
+APP_URL = "https://api.example.com"
+APP_ENV = "production"
 ```
 
-Modern wrangler polyfills `process.env` from `[vars]`, so `which-url` picks it up automatically.
+Non-string bindings (KV, Durable Objects, R2, service bindings) are ignored automatically — only string `[vars]` participate in URL detection.
+
+> ⚠️ The default singleton (`import appUrl from "which-url"`) and named exports (`origin`, `env`, etc.) resolve at **module load**, before your `fetch` handler runs. On Workers they will not see your `[vars]`. Use `createUrl({ env })` from inside your handler.
+
+If you're on `nodejs_compat` and prefer `process.env`, the default singleton works too — but `createUrl({ env })` is the runtime-native path and doesn't require the compat flag.
 
 ### Debugging
 
 ```typescript
-import { debug } from 'which-url'
+import appUrl from 'which-url'
 
-console.log(debug)
-// "platform=vercel | source=provider | url=https://myapp.com | env=production"
+console.log(appUrl.debug)
+// "[provider:vercel] url=myapp.com | env=production (vercel:production)"
+// "[override] APP_URL=https://custom.com | env=production (NODE_ENV=production)"
+// "[portless] PORTLESS_URL=https://myapp.localhost | env=local (NODE_ENV=development)"
+// "[fallback] PORT=3004 | env=local (NODE_ENV=development)"
 ```
 
 ## API
 
 ### Default export
 
-An object with URL properties and environment helpers.
+An import-safe singleton object with URL properties and environment helpers. It resolves once when the package is imported.
+
+### `createUrl()`
+
+Strict resolver function. It resolves when called and throws if no URL can be detected.
 
 ### Named exports
 
@@ -206,11 +257,13 @@ An object with URL properties and environment helpers.
 | `port` | `string` | `""` or `"3000"` |
 | `env` | `AppEnv` | `"production"` \| `"preview"` \| `"local"` |
 | `platform` | `Platform` | `"vercel"` \| `"netlify"` \| ... \| `null` |
-| `source` | `Source` | `"override"` \| `"provider"` \| `"browser"` \| `"fallback"` \| `null` |
-| `debug` | `string` | `"platform=vercel \| source=provider \| url=https://myapp.com \| env=production"` |
+| `debug`* | `string` | `"[provider:vercel] url=myapp.com \| env=production (vercel:production)"` |
 | `isProduction` | `boolean` | |
 | `isPreview` | `boolean` | |
 | `isLocal` | `boolean` | |
+| `createUrl` | `(options?: { env?: Record<string, unknown> }) => WhichUrlWithDebug` | strict resolver |
+
+\* `debug` is non-enumerable on the default export and objects returned by `createUrl()` — excluded from `JSON.stringify` to avoid React hydration mismatches. It is also available as a named export.
 
 ## License
 

package/dist/env-var.d.ts

@@ -7,5 +7,5 @@
  * falls back to dynamic lookup for test/server compatibility.
  */
 export declare function getVar(env: Record<string, string | undefined>, name: string): string | undefined;
-export declare function getEnv(): Record<string, string | undefined>;
+export declare function getEnv(override?: Record<string, unknown>): Record<string, string | undefined>;
 //# sourceMappingURL=env-var.d.ts.map

package/dist/env-var.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"env-var.d.ts","sourceRoot":"","sources":["../src/env-var.ts"],"names":[],"mappings":"AAgGA;;;;;;;GAOG;AACH,wBAAgB,MAAM,CACpB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,EACvC,IAAI,EAAE,MAAM,GACX,MAAM,GAAG,SAAS,CA0BpB;AAED,wBAAgB,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAK3D"}
+{"version":3,"file":"env-var.d.ts","sourceRoot":"","sources":["../src/env-var.ts"],"names":[],"mappings":"AAkGA;;;;;;;GAOG;AACH,wBAAgB,MAAM,CACpB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,EACvC,IAAI,EAAE,MAAM,GACX,MAAM,GAAG,SAAS,CA4BpB;AAED,wBAAgB,MAAM,CACpB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACjC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAQpC"}

package/dist/env.d.ts

@@ -3,5 +3,5 @@ export interface EnvResult {
     env: AppEnv;
     debugLabel: string;
 }
-export declare function resolveEnv(): EnvResult;
+export declare function resolveEnv(envOverride?: Record<string, unknown>): EnvResult;
 //# sourceMappingURL=env.d.ts.map

package/dist/env.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AAIrC,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,MAAM,CAAA;IACX,UAAU,EAAE,MAAM,CAAA;CACnB;AAED,wBAAgB,UAAU,IAAI,SAAS,CAyBtC"}
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AAIrC,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,MAAM,CAAA;IACX,UAAU,EAAE,MAAM,CAAA;CACnB;AAED,wBAAgB,UAAU,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAyB3E"}

package/dist/index.d.ts

@@ -1,16 +1,43 @@
-import type { WhichUrl, AppEnv, Platform } from "./types";
-declare let _resolved: WhichUrl;
+import type { WhichUrlWithDebug, AppEnv, Platform, CreateUrlOptions } from "./types";
+export declare function createUrl(options?: CreateUrlOptions): WhichUrlWithDebug;
+declare let _resolved: WhichUrlWithDebug;
+/** Full URL including protocol — `"https://myapp.com"` */
 export declare const href: string;
+/** Full origin — `"https://myapp.com"` (same as href) */
 export declare const origin: string;
+/** Hostname without port — `"myapp.com"` */
 export declare const hostname: string;
+/** Hostname with port — `"myapp.com"` or `"localhost:3000"` */
 export declare const host: string;
+/** Protocol with colon — `"https:"` or `"http:"` */
 export declare const protocol: string;
+/** Port string — `""` for default ports, `"3000"` for custom */
 export declare const port: string;
+/** Current environment — `"production"`, `"preview"`, or `"local"` */
 export declare const env: AppEnv;
+/** Detected hosting platform — `"vercel"`, `"netlify"`, etc. or `null` */
 export declare const platform: Platform;
+/** Resolution debug string. */
+export declare const debug: string;
+/** `true` when running in production */
 export declare const isProduction: boolean;
+/** `true` when running in a preview/staging deployment */
 export declare const isPreview: boolean;
+/** `true` when running locally (development) */
 export declare const isLocal: boolean;
+/**
+ * Auto-detected app URL with environment metadata.
+ *
+ * @example
+ * ```ts
+ * import appUrl from 'which-url'
+ *
+ * appUrl.origin      // "https://myapp.com"
+ * appUrl.env         // "production"
+ * appUrl.platform    // "vercel"
+ * appUrl.debug       // "[provider:vercel] url=myapp.com | env=production (vercel:production)"
+ * ```
+ */
 export default _resolved;
-export type { WhichUrl, AppEnv, Platform };
+export type { WhichUrl, WhichUrlWithDebug, AppEnv, Platform, PlatformName, CreateUrlOptions } from "./types";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AAqCzD,QAAA,IAAI,SAAS,EAAE,QAAQ,CAAA;AA8BvB,eAAO,MAAM,IAAI,EAAE,MAAuB,CAAA;AAC1C,eAAO,MAAM,MAAM,EAAE,MAAyB,CAAA;AAC9C,eAAO,MAAM,QAAQ,EAAE,MAA2B,CAAA;AAClD,eAAO,MAAM,IAAI,EAAE,MAAuB,CAAA;AAC1C,eAAO,MAAM,QAAQ,EAAE,MAA2B,CAAA;AAClD,eAAO,MAAM,IAAI,EAAE,MAAuB,CAAA;AAC1C,eAAO,MAAM,GAAG,EAAE,MAAsB,CAAA;AACxC,eAAO,MAAM,QAAQ,EAAE,QAA6B,CAAA;AACpD,eAAO,MAAM,YAAY,EAAE,OAAgC,CAAA;AAC3D,eAAO,MAAM,SAAS,EAAE,OAA6B,CAAA;AACrD,eAAO,MAAM,OAAO,EAAE,OAA2B,CAAA;AAGjD,eAAe,SAAS,CAAA;AAExB,YAAY,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAYpF,wBAAgB,SAAS,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,iBAAiB,CAwBvE;AAkCD,QAAA,IAAI,SAAS,EAAE,iBAAiB,CAAA;AAOhC,0DAA0D;AAC1D,eAAO,MAAM,IAAI,EAAE,MAAuB,CAAA;AAC1C,yDAAyD;AACzD,eAAO,MAAM,MAAM,EAAE,MAAyB,CAAA;AAC9C,4CAA4C;AAC5C,eAAO,MAAM,QAAQ,EAAE,MAA2B,CAAA;AAClD,+DAA+D;AAC/D,eAAO,MAAM,IAAI,EAAE,MAAuB,CAAA;AAC1C,oDAAoD;AACpD,eAAO,MAAM,QAAQ,EAAE,MAA2B,CAAA;AAClD,gEAAgE;AAChE,eAAO,MAAM,IAAI,EAAE,MAAuB,CAAA;AAC1C,sEAAsE;AACtE,eAAO,MAAM,GAAG,EAAE,MAAsB,CAAA;AACxC,0EAA0E;AAC1E,eAAO,MAAM,QAAQ,EAAE,QAA6B,CAAA;AACpD,+BAA+B;AAC/B,eAAO,MAAM,KAAK,EAAE,MAAwB,CAAA;AAC5C,wCAAwC;AACxC,eAAO,MAAM,YAAY,EAAE,OAAgC,CAAA;AAC3D,0DAA0D;AAC1D,eAAO,MAAM,SAAS,EAAE,OAA6B,CAAA;AACrD,gDAAgD;AAChD,eAAO,MAAM,OAAO,EAAE,OAA2B,CAAA;AAEjD;;;;;;;;;;;;GAYG;AACH,eAAe,SAAS,CAAA;AAExB,YAAY,EAAE,QAAQ,EAAE,iBAAiB,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA"}

package/dist/index.js

@@ -1,4 +1,12 @@
 // src/env-var.ts
+var ENV_VARS = [
+  "VERCEL_ENV",
+  "VERCEL_URL",
+  "VERCEL_BRANCH_URL",
+  "VERCEL_PROJECT_PRODUCTION_URL",
+  "APP_URL",
+  "APP_ENV"
+];
 function readStatic(name) {
   switch (name) {
     case "VERCEL_ENV":
@@ -13,13 +21,17 @@ function readStatic(name) {
       return process.env.APP_URL || process.env.NEXT_PUBLIC_APP_URL || process.env.NUXT_ENV_APP_URL || process.env.VITE_APP_URL || process.env.PUBLIC_APP_URL || process.env.REACT_APP_APP_URL || process.env.GATSBY_APP_URL || process.env.VUE_APP_APP_URL || process.env.REDWOOD_ENV_APP_URL || process.env.SANITY_STUDIO_APP_URL || undefined;
     case "APP_ENV":
       return process.env.APP_ENV || process.env.NEXT_PUBLIC_APP_ENV || process.env.NUXT_ENV_APP_ENV || process.env.VITE_APP_ENV || process.env.PUBLIC_APP_ENV || process.env.REACT_APP_APP_ENV || process.env.GATSBY_APP_ENV || process.env.VUE_APP_APP_ENV || process.env.REDWOOD_ENV_APP_ENV || process.env.SANITY_STUDIO_APP_ENV || undefined;
+    default:
+      return;
   }
 }
 function getVar(env, name) {
   if (typeof process !== "undefined" && process?.env && env === process.env) {
-    const val = readStatic(name);
-    if (val)
-      return val;
+    if (ENV_VARS.includes(name)) {
+      const val = readStatic(name);
+      if (val)
+        return val;
+    }
   }
   const PREFIXES = [
     "",
@@ -40,12 +52,24 @@ function getVar(env, name) {
   }
   return;
 }
-function getEnv() {
+function getEnv(override) {
+  if (override !== undefined) {
+    return filterStrings(override);
+  }
   if (typeof process !== "undefined" && process?.env) {
     return process.env;
   }
   return {};
 }
+function filterStrings(source) {
+  const out = {};
+  for (const key in source) {
+    const value = source[key];
+    if (typeof value === "string")
+      out[key] = value;
+  }
+  return out;
+}
 
 // src/providers.ts
 var providers = [
@@ -144,13 +168,17 @@ function normalizeUrl(raw) {
 }
 
 // src/resolve.ts
-function resolveUrl() {
-  const env = getEnv();
+function resolveUrl(envOverride) {
+  const env = getEnv(envOverride);
   const override = getVar(env, "APP_URL");
   if (override)
     return { url: normalizeUrl(override), debugLabel: `[override] APP_URL=${override}` };
-  if (env.PORTLESS_URL)
+  if (env.PORTLESS_TAILSCALE_URL) {
+    return { url: env.PORTLESS_TAILSCALE_URL, debugLabel: `[portless:tailscale] PORTLESS_TAILSCALE_URL=${env.PORTLESS_TAILSCALE_URL}` };
+  }
+  if (env.PORTLESS_URL) {
     return { url: env.PORTLESS_URL, debugLabel: `[portless] PORTLESS_URL=${env.PORTLESS_URL}` };
+  }
   for (const p of providers) {
     if (p.detect(env)) {
       const url = p.resolveUrl(env);
@@ -168,8 +196,8 @@ function resolveUrl() {
   }
   throw new Error("which-url: Cannot detect app URL. Set APP_URL environment variable.");
 }
-function resolvePlatform() {
-  const env = getEnv();
+function resolvePlatform(envOverride) {
+  const env = getEnv(envOverride);
   for (const p of providers) {
     if (p.detect(env)) {
       return p.name;
@@ -180,8 +208,8 @@ function resolvePlatform() {
 
 // src/env.ts
 var validEnvs = ["production", "preview", "local"];
-function resolveEnv() {
-  const env = getEnv();
+function resolveEnv(envOverride) {
+  const env = getEnv(envOverride);
   const appEnv = getVar(env, "APP_ENV");
   if (appEnv && validEnvs.includes(appEnv)) {
     return { env: appEnv, debugLabel: `APP_ENV=${appEnv}` };
@@ -200,11 +228,20 @@ function resolveEnv() {
 }
 
 // src/index.ts
-function resolve() {
-  const { url, debugLabel: urlDebug } = resolveUrl();
+function makeDebugNonEnumerable(result) {
+  Object.defineProperty(result, "debug", {
+    value: result.debug,
+    enumerable: false,
+    configurable: false
+  });
+  return result;
+}
+function createUrl(options) {
+  const envOverride = options?.env;
+  const { url, debugLabel: urlDebug } = resolveUrl(envOverride);
   const parsed = new URL(url);
-  const { env, debugLabel: envDebug } = resolveEnv();
-  const platform = resolvePlatform();
+  const { env, debugLabel: envDebug } = resolveEnv(envOverride);
+  const platform = resolvePlatform(envOverride);
   const debug = `${urlDebug} | env=${env} (${envDebug})`;
   const result = {
     href: parsed.origin,
@@ -220,18 +257,17 @@ function resolve() {
     isPreview: env === "preview",
     isLocal: env === "local"
   };
-  Object.defineProperty(result, "debug", {
-    value: debug,
-    enumerable: false,
-    configurable: false
-  });
-  return result;
+  return makeDebugNonEnumerable(result);
 }
-var _resolved;
-try {
-  _resolved = resolve();
-} catch (e) {
-  console.warn(`[which-url] Could not detect app URL. Set APP_URL (e.g. APP_URL=https://myapp.com or APP_URL=myapp.com)`);
+function createFallback(error) {
+  const message = error instanceof Error ? error.message : "resolution failed";
+  let resolvedEnv = "local";
+  let envDebug = "default";
+  try {
+    const result = resolveEnv();
+    resolvedEnv = result.env;
+    envDebug = result.debugLabel;
+  } catch {}
   const fallback = {
     href: "",
     origin: "",
@@ -239,19 +275,20 @@ try {
     host: "",
     protocol: "",
     port: "",
-    env: "local",
-    platform: null,
-    debug: "[error] resolution failed",
-    isProduction: false,
-    isPreview: false,
-    isLocal: true
+    env: resolvedEnv,
+    platform: resolvePlatform(),
+    debug: `[error] ${message} | env=${resolvedEnv} (${envDebug})`,
+    isProduction: resolvedEnv === "production",
+    isPreview: resolvedEnv === "preview",
+    isLocal: resolvedEnv === "local"
   };
-  Object.defineProperty(fallback, "debug", {
-    value: "[error] resolution failed",
-    enumerable: false,
-    configurable: false
-  });
-  _resolved = fallback;
+  return makeDebugNonEnumerable(fallback);
+}
+var _resolved;
+try {
+  _resolved = createUrl();
+} catch (e) {
+  _resolved = createFallback(e);
 }
 var href = _resolved.href;
 var origin = _resolved.origin;
@@ -261,6 +298,7 @@ var protocol = _resolved.protocol;
 var port = _resolved.port;
 var env = _resolved.env;
 var platform = _resolved.platform;
+var debug = _resolved.debug;
 var isProduction = _resolved.isProduction;
 var isPreview = _resolved.isPreview;
 var isLocal = _resolved.isLocal;
@@ -277,5 +315,7 @@ export {
   hostname,
   host,
   env,
-  src_default as default
+  src_default as default,
+  debug,
+  createUrl
 };

package/dist/resolve.d.ts

@@ -3,6 +3,6 @@ export interface ResolveResult {
     url: string;
     debugLabel: string;
 }
-export declare function resolveUrl(): ResolveResult;
-export declare function resolvePlatform(): Platform;
+export declare function resolveUrl(envOverride?: Record<string, unknown>): ResolveResult;
+export declare function resolvePlatform(envOverride?: Record<string, unknown>): Platform;
 //# sourceMappingURL=resolve.d.ts.map

package/dist/resolve.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../src/resolve.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AAEvC,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAA;IACX,UAAU,EAAE,MAAM,CAAA;CACnB;AAED,wBAAgB,UAAU,IAAI,aAAa,CAkC1C;AAED,wBAAgB,eAAe,IAAI,QAAQ,CAQ1C"}
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../src/resolve.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AAEvC,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAA;IACX,UAAU,EAAE,MAAM,CAAA;CACnB;AAED,wBAAgB,UAAU,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,aAAa,CAuC/E;AAED,wBAAgB,eAAe,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,QAAQ,CAQ/E"}

package/dist/types.d.ts

@@ -1,21 +1,48 @@
 export type AppEnv = "production" | "preview" | "local";
-export type Platform = "vercel" | "netlify" | "cloudflare" | "railway" | "fly" | "render" | "digitalocean" | "heroku" | null;
+export type PlatformName = "vercel" | "netlify" | "cloudflare" | "railway" | "fly" | "render" | "digitalocean" | "heroku";
+export type Platform = PlatformName | null;
 export interface WhichUrl {
-    href: string;
-    origin: string;
-    hostname: string;
-    host: string;
-    protocol: string;
-    port: string;
-    env: AppEnv;
-    platform: Platform;
-    debug: string;
-    isProduction: boolean;
-    isPreview: boolean;
-    isLocal: boolean;
+    /** Full URL including protocol — `"https://myapp.com"` */
+    readonly href: string;
+    /** Full origin — `"https://myapp.com"` (same as href) */
+    readonly origin: string;
+    /** Hostname without port — `"myapp.com"` */
+    readonly hostname: string;
+    /** Hostname with port — `"myapp.com"` or `"localhost:3000"` */
+    readonly host: string;
+    /** Protocol with colon — `"https:"` or `"http:"` */
+    readonly protocol: string;
+    /** Port string — `""` for default ports, `"3000"` for custom */
+    readonly port: string;
+    /** Current environment — `"production"`, `"preview"`, or `"local"` */
+    readonly env: AppEnv;
+    /** Detected hosting platform — `"vercel"`, `"netlify"`, etc. or `null` */
+    readonly platform: Platform;
+    /** `true` when running in production */
+    readonly isProduction: boolean;
+    /** `true` when running in a preview/staging deployment */
+    readonly isPreview: boolean;
+    /** `true` when running locally (development) */
+    readonly isLocal: boolean;
+}
+export interface WhichUrlWithDebug extends WhichUrl {
+    /** Resolution debug string (non-enumerable — excluded from JSON.stringify and object spread). */
+    readonly debug: string;
+}
+export interface CreateUrlOptions {
+    /**
+     * Runtime environment source. Pass this when `process.env` isn't available
+     * or doesn't contain your config — e.g. on Cloudflare Workers, where the
+     * Worker `env` argument carries `[vars]` from `wrangler.toml`.
+     *
+     * When provided, `process.env` is ignored entirely. Only string-valued
+     * entries participate in URL detection — non-string Workers bindings
+     * (KV namespaces, Durable Objects, R2 buckets, service bindings) are dropped.
+     */
+    env?: Record<string, unknown>;
 }
 export interface ProviderDetector {
-    name: string;
+    name: PlatformName;
     detect: (env: Record<string, string | undefined>) => boolean;
     resolveUrl: (env: Record<string, string | undefined>) => string | null;
     resolveEnv: (env: Record<string, string | undefined>) => AppEnv;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,MAAM,GAAG,YAAY,GAAG,SAAS,GAAG,OAAO,CAAA;AAEvD,MAAM,MAAM,QAAQ,GAChB,QAAQ,GACR,SAAS,GACT,YAAY,GACZ,SAAS,GACT,KAAK,GACL,QAAQ,GACR,cAAc,GACd,QAAQ,GACR,IAAI,CAAA;AAER,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,MAAM,CAAA;IACX,QAAQ,EAAE,QAAQ,CAAA;IAClB,KAAK,EAAE,MAAM,CAAA;IACb,YAAY,EAAE,OAAO,CAAA;IACrB,SAAS,EAAE,OAAO,CAAA;IAClB,OAAO,EAAE,OAAO,CAAA;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,KAAK,OAAO,CAAA;IAC5D,UAAU,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,KAAK,MAAM,GAAG,IAAI,CAAA;IACtE,UAAU,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,KAAK,MAAM,CAAA;CAChE"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,MAAM,GAAG,YAAY,GAAG,SAAS,GAAG,OAAO,CAAA;AAEvD,MAAM,MAAM,YAAY,GACpB,QAAQ,GACR,SAAS,GACT,YAAY,GACZ,SAAS,GACT,KAAK,GACL,QAAQ,GACR,cAAc,GACd,QAAQ,CAAA;AAEZ,MAAM,MAAM,QAAQ,GAAG,YAAY,GAAG,IAAI,CAAA;AAE1C,MAAM,WAAW,QAAQ;IACvB,0DAA0D;IAC1D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,yDAAyD;IACzD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,4CAA4C;IAC5C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,oDAAoD;IACpD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,gEAAgE;IAChE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,sEAAsE;IACtE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;IAC3B,wCAAwC;IACxC,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAA;IAC9B,0DAA0D;IAC1D,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;IAC3B,gDAAgD;IAChD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;CAC1B;AAED,MAAM,WAAW,iBAAkB,SAAQ,QAAQ;IACjD,iGAAiG;IACjG,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACvB;AAED,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;;OAQG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC9B;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,YAAY,CAAA;IAClB,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,KAAK,OAAO,CAAA;IAC5D,UAAU,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,KAAK,MAAM,GAAG,IAAI,CAAA;IACtE,UAAU,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,KAAK,MAAM,CAAA;CAChE"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "which-url",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "description": "Auto-detect your app's URL across hosting providers. Zero config.",
   "type": "module",
   "exports": {