feat(base-url): support EVERSHOP_HOME_URL env override with boot validation

Resolve the store base URL with precedence: EVERSHOP_HOME_URL env >
shop.homeUrl config > http://localhost:<PORT>. getBaseUrl() is the single
chokepoint for absolute URLs (router, emails, GraphQL context), so the
override applies everywhere.

EVERSHOP_HOME_URL is validated at boot in the base module bootstrap: if it is
set but not a valid absolute http(s) URL it throws, and the server refuses to
start (build/dev/start all wrap bootstrap in a try/catch that exits) before any
broken absolute link or email can be emitted. An unset/empty value falls back
to shop.homeUrl, which the configuration schema validates.

Adds util.getBaseUrl unit tests: precedence, whitespace-as-unset, trailing
slash stripping, and the boot-guard accept/reject cases.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: treoden

packages/evershop/src/lib/util/getBaseUrl.ts

@@ -1,8 +1,54 @@
 import { normalizePort } from '../../bin/lib/normalizePort.js';
 import { getConfig } from './getConfig.js';
 
+/**
+ * Environment variable that overrides the configured `shop.homeUrl`. When set,
+ * it takes precedence over every config file; when unset (or empty) the store
+ * falls back to `shop.homeUrl` and then to `http://localhost:<PORT>`.
+ */
+export const HOME_URL_ENV = 'EVERSHOP_HOME_URL';
+
+/**
+ * Resolve the store's base URL. Precedence (highest first):
+ *   1. process.env.EVERSHOP_HOME_URL
+ *   2. config `shop.homeUrl`
+ *   3. http://localhost:<PORT>
+ * Trailing slashes are always stripped.
+ */
 export function getBaseUrl(): string {
   const port = normalizePort();
-  const baseUrl = getConfig('shop.homeUrl', `http://localhost:${port}`);
+  const envUrl = process.env[HOME_URL_ENV]?.trim();
+  const baseUrl =
+    envUrl || getConfig('shop.homeUrl', `http://localhost:${port}`);
   return baseUrl.replace(/\/+$/, ''); // Remove trailing slashes
 }
+
+/**
+ * Boot-time guard for the `EVERSHOP_HOME_URL` override. If the variable is set,
+ * it must be a valid absolute http(s) URL — otherwise every absolute link and
+ * email the store generates would be broken. Throwing here halts boot (the
+ * caller in module bootstrap is wrapped in the start/build try/catch that calls
+ * `process.exit`). A missing/empty variable is allowed: the store then falls
+ * back to `shop.homeUrl`, which the configuration schema validates separately.
+ */
+export function assertValidHomeUrlEnv(): void {
+  const raw = process.env[HOME_URL_ENV];
+  if (raw === undefined || raw.trim() === '') {
+    return;
+  }
+  const value = raw.trim();
+  let parsed: URL;
+  try {
+    parsed = new URL(value);
+  } catch {
+    throw new Error(
+      `Invalid ${HOME_URL_ENV}: "${value}" is not a valid URL. ` +
+        `Set an absolute URL such as "https://example.com".`
+    );
+  }
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+    throw new Error(
+      `Invalid ${HOME_URL_ENV}: "${value}" must use the http or https protocol.`
+    );
+  }
+}

packages/evershop/src/lib/util/tests/unit/util.getBaseUrl.test.js

@@ -0,0 +1,102 @@
+/**
+ * @jest-environment node
+ */
+import {
+  jest,
+  describe,
+  it,
+  expect,
+  beforeEach,
+  afterEach
+} from '@jest/globals';
+
+// `undefined` => the getConfig mock returns the default argument passed by
+// getBaseUrl (i.e. the localhost fallback). Any string => that config value.
+let mockConfigValue;
+
+await jest.unstable_mockModule('../../getConfig.js', () => ({
+  getConfig: (_path, def) => (mockConfigValue !== undefined ? mockConfigValue : def)
+}));
+
+const { getBaseUrl, assertValidHomeUrlEnv, HOME_URL_ENV } = await import(
+  '../../getBaseUrl.js'
+);
+
+const ORIGINAL_ENV = process.env[HOME_URL_ENV];
+const restoreEnv = () => {
+  if (ORIGINAL_ENV === undefined) {
+    delete process.env[HOME_URL_ENV];
+  } else {
+    process.env[HOME_URL_ENV] = ORIGINAL_ENV;
+  }
+};
+
+describe('getBaseUrl — EVERSHOP_HOME_URL override precedence', () => {
+  beforeEach(() => {
+    mockConfigValue = undefined;
+    delete process.env[HOME_URL_ENV];
+  });
+  afterEach(restoreEnv);
+
+  it('uses the env var when set (highest precedence)', () => {
+    mockConfigValue = 'https://from-config.example.com';
+    process.env[HOME_URL_ENV] = 'https://from-env.example.com';
+    expect(getBaseUrl()).toBe('https://from-env.example.com');
+  });
+
+  it('falls back to config when env is unset', () => {
+    mockConfigValue = 'https://from-config.example.com';
+    expect(getBaseUrl()).toBe('https://from-config.example.com');
+  });
+
+  it('treats whitespace-only env as unset and falls back to config', () => {
+    mockConfigValue = 'https://from-config.example.com';
+    process.env[HOME_URL_ENV] = '   ';
+    expect(getBaseUrl()).toBe('https://from-config.example.com');
+  });
+
+  it('falls back to http://localhost:<port> when neither env nor config is set', () => {
+    expect(getBaseUrl()).toMatch(/^http:\/\/localhost:\d+$/);
+  });
+
+  it('strips trailing slashes from the env value', () => {
+    process.env[HOME_URL_ENV] = 'https://from-env.example.com///';
+    expect(getBaseUrl()).toBe('https://from-env.example.com');
+  });
+});
+
+describe('assertValidHomeUrlEnv — boot guard', () => {
+  beforeEach(() => {
+    delete process.env[HOME_URL_ENV];
+  });
+  afterEach(restoreEnv);
+
+  it('does not throw when the env var is unset', () => {
+    expect(() => assertValidHomeUrlEnv()).not.toThrow();
+  });
+
+  it('does not throw when the env var is empty/whitespace', () => {
+    process.env[HOME_URL_ENV] = '  ';
+    expect(() => assertValidHomeUrlEnv()).not.toThrow();
+  });
+
+  it('accepts a valid https URL', () => {
+    process.env[HOME_URL_ENV] = 'https://example.com';
+    expect(() => assertValidHomeUrlEnv()).not.toThrow();
+  });
+
+  it('accepts a valid http URL with a port', () => {
+    process.env[HOME_URL_ENV] = 'http://localhost:3000';
+    expect(() => assertValidHomeUrlEnv()).not.toThrow();
+  });
+
+  it('throws for a non-URL string', () => {
+    process.env[HOME_URL_ENV] = 'not a url';
+    expect(() => assertValidHomeUrlEnv()).toThrow(/not a valid URL/);
+  });
+
+  it('throws for a non-http(s) protocol', () => {
+    process.env[HOME_URL_ENV] = 'ftp://example.com';
+    expect(() => assertValidHomeUrlEnv()).toThrow(/http or https/);
+  });
+});

packages/evershop/src/modules/base/bootstrap.js

@@ -1,8 +1,13 @@
 import { loadAllLocales } from '../../lib/locale/dictionary.js';
+import { assertValidHomeUrlEnv } from '../../lib/util/getBaseUrl.js';
 import { merge } from '../../lib/util/merge.js';
 import { addProcessor } from '../../lib/util/registry.js';
 
 export default async () => {
+  // Fail fast if EVERSHOP_HOME_URL is set to something that isn't a valid
+  // http(s) URL. Throwing here halts boot (build/dev/start all wrap bootstrap
+  // in a try/catch that exits), before any broken absolute URL can be emitted.
+  assertValidHomeUrlEnv();
   // Build the runtime locale registry from disk (spec §6.2/§6.3). `translate()` and
   // `_()` now read this registry / the per-request ALS context — no separate loadCsv.
   await loadAllLocales();