which-url 0.0.4 → 0.0.6

package/README.md

@@ -148,6 +148,18 @@ Framework-prefixed env vars like `NEXT_PUBLIC_VERCEL_PROJECT_PRODUCTION_URL` are
 
 ## Advanced
 
+### Portless
+
+Zero config — [portless](https://portless.sh) sets `PORTLESS_URL` and `which-url` picks it up automatically.
+
+```json
+"dev": "portless run next dev"
+```
+
+```
+origin → https://myapp.localhost
+```
+
 ### Tunnels (ngrok, Cloudflare Tunnel)
 
 Tunnel URLs can't be auto-detected — they're external to the app process. Set `APP_URL`:
@@ -167,15 +179,13 @@ APP_URL = "https://myapp.workers.dev"
 
 Modern wrangler polyfills `process.env` from `[vars]`, so `which-url` picks it up automatically.
 
-### `createUrl(options?)`
-
-Re-resolves the URL from the current environment. Unlike the singleton (which catches errors), `createUrl()` throws in production if no URL is detected.
+### Debugging
 
 ```typescript
-import { createUrl } from 'which-url'
+import { debug } from 'which-url'
 
-const url = createUrl({ fallback: 'https://fallback.example.com' })
-url.origin // never throws
+console.log(debug)
+// "platform=vercel | source=provider | url=https://myapp.com | env=production"
 ```
 
 ## API
@@ -196,6 +206,8 @@ 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"` |
 | `isProduction` | `boolean` | |
 | `isPreview` | `boolean` | |
 | `isLocal` | `boolean` | |

package/dist/env.d.ts

@@ -1,3 +1,7 @@
 import type { AppEnv } from "./types";
-export declare function resolveEnv(): AppEnv;
+export interface EnvResult {
+    env: AppEnv;
+    debugLabel: string;
+}
+export declare function resolveEnv(): 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,wBAAgB,UAAU,IAAI,MAAM,CAwBnC"}
+{"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"}

package/dist/index.d.ts

@@ -1,5 +1,4 @@
-import type { WhichUrl, AppEnv, Platform, CreateUrlOptions } from "./types";
-export declare function createUrl(options?: CreateUrlOptions): WhichUrl;
+import type { WhichUrl, AppEnv, Platform } from "./types";
 declare let _resolved: WhichUrl;
 export declare const href: string;
 export declare const origin: string;
@@ -13,5 +12,5 @@ export declare const isProduction: boolean;
 export declare const isPreview: boolean;
 export declare const isLocal: boolean;
 export default _resolved;
-export type { WhichUrl, AppEnv, Platform, CreateUrlOptions };
+export type { WhichUrl, AppEnv, Platform };
 //# 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,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAE3E,wBAAgB,SAAS,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,QAAQ,CAkB9D;AAGD,QAAA,IAAI,SAAS,EAAE,QAAQ,CAAA;AAuBvB,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,gBAAgB,EAAE,CAAA"}
+{"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"}

package/dist/index.js

@@ -144,28 +144,27 @@ function normalizeUrl(raw) {
 }
 
 // src/resolve.ts
-function resolveUrl(options) {
+function resolveUrl() {
   const env = getEnv();
   const override = getVar(env, "APP_URL");
   if (override)
-    return normalizeUrl(override);
+    return { url: normalizeUrl(override), debugLabel: `[override] APP_URL=${override}` };
+  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);
       if (url)
-        return normalizeUrl(url);
+        return { url: normalizeUrl(url), debugLabel: `[provider:${p.name}] url=${url}` };
     }
   }
   if (typeof window !== "undefined" && window.location) {
-    return window.location.origin;
+    return { url: window.location.origin, debugLabel: `[browser] window.location.origin` };
   }
   const isProduction = env.NODE_ENV === "production";
   if (!isProduction) {
     const port = env.PORT || "3000";
-    return `http://localhost:${port}`;
-  }
-  if (options?.fallback) {
-    return normalizeUrl(options.fallback);
+    return { url: `http://localhost:${port}`, debugLabel: `[fallback] PORT=${port}` };
   }
   throw new Error("which-url: Cannot detect app URL. Set APP_URL environment variable.");
 }
@@ -185,27 +184,29 @@ function resolveEnv() {
   const env = getEnv();
   const appEnv = getVar(env, "APP_ENV");
   if (appEnv && validEnvs.includes(appEnv)) {
-    return appEnv;
+    return { env: appEnv, debugLabel: `APP_ENV=${appEnv}` };
   }
   if (env.NODE_ENV === "development")
-    return "local";
+    return { env: "local", debugLabel: "NODE_ENV=development" };
   for (const p of providers) {
     if (p.detect(env)) {
-      return p.resolveEnv(env);
+      const resolved = p.resolveEnv(env);
+      return { env: resolved, debugLabel: `${p.name}:${resolved}` };
     }
   }
   if (env.NODE_ENV === "production")
-    return "production";
-  return "local";
+    return { env: "production", debugLabel: "NODE_ENV=production" };
+  return { env: "local", debugLabel: "default" };
 }
 
 // src/index.ts
-function createUrl(options) {
-  const resolved = resolveUrl(options);
-  const parsed = new URL(resolved);
-  const env = resolveEnv();
+function resolve() {
+  const { url, debugLabel: urlDebug } = resolveUrl();
+  const parsed = new URL(url);
+  const { env, debugLabel: envDebug } = resolveEnv();
   const platform = resolvePlatform();
-  return {
+  const debug = `${urlDebug} | env=${env} (${envDebug})`;
+  const result = {
     href: parsed.origin,
     origin: parsed.origin,
     hostname: parsed.hostname,
@@ -214,17 +215,24 @@ function createUrl(options) {
     port: parsed.port,
     env,
     platform,
+    debug,
     isProduction: env === "production",
     isPreview: env === "preview",
     isLocal: env === "local"
   };
+  Object.defineProperty(result, "debug", {
+    value: debug,
+    enumerable: false,
+    configurable: false
+  });
+  return result;
 }
 var _resolved;
 try {
-  _resolved = createUrl();
+  _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)`);
-  _resolved = {
+  const fallback = {
     href: "",
     origin: "",
     hostname: "",
@@ -233,10 +241,17 @@ try {
     port: "",
     env: "local",
     platform: null,
+    debug: "[error] resolution failed",
     isProduction: false,
     isPreview: false,
     isLocal: true
   };
+  Object.defineProperty(fallback, "debug", {
+    value: "[error] resolution failed",
+    enumerable: false,
+    configurable: false
+  });
+  _resolved = fallback;
 }
 var href = _resolved.href;
 var origin = _resolved.origin;
@@ -262,6 +277,5 @@ export {
   hostname,
   host,
   env,
-  src_default as default,
-  createUrl
+  src_default as default
 };

package/dist/resolve.d.ts

@@ -1,4 +1,8 @@
-import type { CreateUrlOptions, Platform } from "./types";
-export declare function resolveUrl(options?: CreateUrlOptions): string;
+import type { Platform } from "./types";
+export interface ResolveResult {
+    url: string;
+    debugLabel: string;
+}
+export declare function resolveUrl(): ResolveResult;
 export declare function resolvePlatform(): 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,gBAAgB,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AAEzD,wBAAgB,UAAU,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,MAAM,CAoC7D;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,IAAI,aAAa,CAkC1C;AAED,wBAAgB,eAAe,IAAI,QAAQ,CAQ1C"}

package/dist/types.d.ts

@@ -9,13 +9,11 @@ export interface WhichUrl {
     port: string;
     env: AppEnv;
     platform: Platform;
+    debug: string;
     isProduction: boolean;
     isPreview: boolean;
     isLocal: boolean;
 }
-export interface CreateUrlOptions {
-    fallback?: string;
-}
 export interface ProviderDetector {
     name: string;
     detect: (env: Record<string, string | undefined>) => boolean;

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,YAAY,EAAE,OAAO,CAAA;IACrB,SAAS,EAAE,OAAO,CAAA;IAClB,OAAO,EAAE,OAAO,CAAA;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;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,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"}

package/package.json

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