feat: runtime baseUrl with optional imports

- BaseUrlRuntime (expression + optional imports), getFullRoute, merge imports in client generator
- Docs (output reference, fetch/set-base-url) and route tests

Author: mikan3rd

docs/content/docs/guides/fetch.mdx

@@ -29,6 +29,18 @@ export default defineConfig({
 });
 ```
 
+## Runtime base URL
+
+For a host that is only known at runtime (for example `process.env.API_BASE_URL` in Node or `import.meta.env.VITE_*` in Vite), use `baseUrl.runtime` instead of a fixed string. The built-in fetch client embeds the expression in generated URL template literals, so you can keep using `override.fetch` options such as `runtimeValidation` and `includeHttpResponseReturnType` without a custom mutator.
+
+```ts title="orval.config.ts"
+baseUrl: {
+  runtime: 'process.env.API_BASE_URL',
+},
+```
+
+See the [output `baseUrl` reference](/docs/reference/configuration/output#runtime) for `imports` and expressions such as `env.API_BASE_URL` from a shared module (for example `import { env } from '../../env'`). MSW mock host filtering uses the separate [`mock.baseUrl`](/docs/reference/configuration/output#mock-options) option.
+
 ## Generated Output
 
 Orval generates three things for each endpoint:

docs/content/docs/guides/set-base-url.mdx

@@ -44,6 +44,10 @@ export default defineConfig({
 });
 ```
 
+## Runtime base URL
+
+To resolve the API base URL when your app runs (for example from environment variables) while using Orval's generated fetch client and built-in `override.fetch` features, set [`baseUrl.runtime`](/docs/reference/configuration/output#runtime) in your output config. This is separate from [`mock.baseUrl`](/docs/reference/configuration/output#mock-options), which only affects generated MSW handlers.
+
 ## HTTP Client Configuration
 
 ### Axios

docs/content/docs/reference/configuration/output.mdx

@@ -235,9 +235,71 @@ export default defineConfig({
 });
 ```
 
-### getBaseUrlFromSpecification
+### runtime {#runtime}
 
-Read URL from the OpenAPI `servers` field:
+Embed a JavaScript expression into generated request URLs so the same build can call different hosts at runtime (for example with Docker images and environment variables). The value is emitted inside template literals in generated clients; only use trusted expressions from your configuration.
+
+```ts title="orval.config.ts"
+export default defineConfig({
+  petstore: {
+    output: {
+      baseUrl: {
+        runtime: 'process.env.API_BASE_URL',
+      },
+    },
+  },
+});
+```
+
+#### runtime
+
+**Type:** `String`
+
+JavaScript expression used inside generated template literals for the request base URL. Set this to the expression only (for example `process.env.API_BASE_URL`), not including `` `${...}` ``; Orval wraps it for you.
+
+#### imports
+
+**Type:** `GeneratorImport[]`
+
+Optional. When `runtime` references a symbol from another module, list the imports Orval should emit into generated clients. Paths are relative to the generated file, same idea as mutator imports. The `runtime` expression must be valid where the generated code runs (after those imports).
+
+Use a default import:
+
+```ts title="orval.config.ts"
+export default defineConfig({
+  petstore: {
+    output: {
+      baseUrl: {
+        runtime: 'apiBase',
+        imports: [{ name: 'apiBase', importPath: '../config/api' }],
+      },
+    },
+  },
+});
+```
+
+Or a named export used as an object (for example `import { env } from '../../env'` and `env.API_BASE_URL` in application code) — set `runtime` to that property access and import the object under `name`:
+
+```ts title="orval.config.ts"
+export default defineConfig({
+  petstore: {
+    output: {
+      baseUrl: {
+        runtime: 'env.API_BASE_URL',
+        imports: [{ name: 'env', importPath: '../../env' }],
+      },
+    },
+  },
+});
+```
+
+Adjust `importPath` so it resolves from the generated client file to your module (the example assumes the client is nested deeper than `env.ts`).
+
+### getBaseUrlFromSpecification {#getbaseurlfromspecification}
+
+**Type:** `Boolean`
+
+Read the base URL from the OpenAPI `servers` field instead of a fixed string. When `true`, Orval resolves it from the spec’s `servers` entry (optionally with `variables` and `index` below).
 
 ```ts title="orval.config.ts"
 export default defineConfig({
@@ -254,11 +316,17 @@ export default defineConfig({
 });
 ```
 
-### index
+#### variables
+
+**Type:** `Record<string, string>`
+
+Values for variables used in server URL templates from the OpenAPI `servers` field.
+
+#### index
 
 **Type:** `Number`
 
-Select which server URL index to use (when `getBaseUrlFromSpecification: true`):
+Which `servers` entry to use (0-based) when multiple URLs are defined:
 
 ```ts title="orval.config.ts"
 export default defineConfig({

packages/core/src/getters/route.test.ts

@@ -3,9 +3,15 @@ import { describe, expect, it, test } from 'vitest';
 import type {
   BaseUrlFromConstant,
   BaseUrlFromSpec,
+  BaseUrlRuntime,
   OpenApiServerObject,
 } from '../types';
-import { getFullRoute, getRoute, getRouteAsArray } from './route';
+import {
+  getBaseUrlRuntimeImports,
+  getFullRoute,
+  getRoute,
+  getRouteAsArray,
+} from './route';
 
 describe('getRoute getter', () => {
   for (const [input, expected] of [
@@ -139,6 +145,31 @@ describe('getFullRoute getter', () => {
       expect(getFullRoute(path, servers, config)).toBe(expected);
     });
   }
+  for (const [path, servers, config, expected] of [
+    [
+      '/pets',
+      undefined,
+      { runtime: 'process.env.API_BASE_URL' },
+      '${process.env.API_BASE_URL}/pets',
+    ],
+    [
+      '/pets',
+      undefined,
+      { runtime: 'import.meta.env.VITE_API_URL' },
+      '${import.meta.env.VITE_API_URL}/pets',
+    ],
+    [
+      '/pets',
+      undefined,
+      { runtime: 'env.API_BASE_URL' },
+      '${env.API_BASE_URL}/pets',
+    ],
+    ['/path', undefined, { runtime: '' }, '/path'],
+  ] as [string, OpenApiServerObject[] | undefined, BaseUrlRuntime, string][]) {
+    it(`should make path ${path} with runtime baseUrl ${JSON.stringify(config)} be ${expected}`, () => {
+      expect(getFullRoute(path, servers, config)).toBe(expected);
+    });
+  }
   for (const [path, servers, config, error] of [
     [
       '/path',
@@ -169,6 +200,55 @@ describe('getFullRoute getter', () => {
   }
 });
 
+describe('getBaseUrlRuntimeImports', () => {
+  it('returns [] when baseUrl is omitted', () => {
+    expect(getBaseUrlRuntimeImports()).toEqual([]);
+  });
+
+  it('returns [] for string baseUrl', () => {
+    expect(getBaseUrlRuntimeImports('https://api.example.com')).toEqual([]);
+  });
+
+  it('returns [] for BaseUrlFromSpec', () => {
+    expect(
+      getBaseUrlRuntimeImports({ getBaseUrlFromSpecification: true }),
+    ).toEqual([]);
+  });
+
+  it('returns [] for BaseUrlFromConstant', () => {
+    expect(
+      getBaseUrlRuntimeImports({
+        getBaseUrlFromSpecification: false,
+        baseUrl: 'https://x.com',
+      }),
+    ).toEqual([]);
+  });
+
+  it('returns [] for BaseUrlRuntime without imports', () => {
+    expect(getBaseUrlRuntimeImports({ runtime: 'process.env.X' })).toEqual([]);
+  });
+
+  it('returns imports for BaseUrlRuntime with imports', () => {
+    const imports = [{ name: 'apiBase', importPath: '../config/api' }];
+    expect(
+      getBaseUrlRuntimeImports({
+        runtime: 'apiBase',
+        imports,
+      }),
+    ).toEqual(imports);
+  });
+
+  it('returns imports for env object pattern (runtime uses property access)', () => {
+    const imports = [{ name: 'env', importPath: '../../env' }];
+    expect(
+      getBaseUrlRuntimeImports({
+        runtime: 'env.API_BASE_URL',
+        imports,
+      }),
+    ).toEqual(imports);
+  });
+});
+
 describe('getRouteAsArray getter', () => {
   test.each([
     ['/v${version}/the/nope/${param}', "'v',version,'the','nope',param"],

packages/core/src/getters/route.ts

@@ -2,9 +2,32 @@ import { TEMPLATE_TAG_REGEX } from '../constants';
 import type {
   BaseUrlFromConstant,
   BaseUrlFromSpec,
+  BaseUrlRuntime,
+  GeneratorImport,
+  NormalizedOutputOptions,
   OpenApiServerObject,
 } from '../types';
-import { camel, isString, sanitize } from '../utils';
+import { camel, isObject, isString, sanitize } from '../utils';
+
+function isBaseUrlRuntime(
+  baseUrl: string | BaseUrlFromConstant | BaseUrlFromSpec | BaseUrlRuntime,
+): baseUrl is BaseUrlRuntime {
+  return (
+    isObject(baseUrl) &&
+    'runtime' in baseUrl &&
+    typeof baseUrl.runtime === 'string'
+  );
+}
+
+/**
+ * Wraps a runtime expression for generated URL template literals.
+ * Pass the expression only (e.g. `process.env.API_BASE_URL`), not a `${...}` fragment.
+ */
+function runtimeExpressionToUrlPrefix(expression: string): string {
+  const t = expression.trim();
+  if (!t) return '';
+  return '${' + t + '}';
+}
 
 const TEMPLATE_TAG_IN_PATH_REGEX = /\/([\w]+)(?:\$\{)/g; // all dynamic parts of path
 
@@ -47,11 +70,19 @@ export function getRoute(route: string) {
 export function getFullRoute(
   route: string,
   servers: OpenApiServerObject[] | undefined,
-  baseUrl: string | BaseUrlFromConstant | BaseUrlFromSpec | undefined,
+  baseUrl:
+    | string
+    | BaseUrlFromConstant
+    | BaseUrlFromSpec
+    | BaseUrlRuntime
+    | undefined,
 ): string {
   const getBaseUrl = (): string => {
     if (!baseUrl) return '';
     if (isString(baseUrl)) return baseUrl;
+    if (isBaseUrlRuntime(baseUrl)) {
+      return runtimeExpressionToUrlPrefix(baseUrl.runtime);
+    }
     if (baseUrl.getBaseUrlFromSpecification) {
       if (!servers) {
         throw new Error(
@@ -99,6 +130,17 @@ export function getFullRoute(
   return fullRoute;
 }
 
+/**
+ * Returns `GeneratorImport` entries for {@link BaseUrlRuntime.imports} when `baseUrl` is a runtime config.
+ */
+export function getBaseUrlRuntimeImports(
+  baseUrl?: NormalizedOutputOptions['baseUrl'],
+): GeneratorImport[] {
+  if (!baseUrl) return [];
+  if (!isBaseUrlRuntime(baseUrl)) return [];
+  return baseUrl.imports ?? [];
+}
+
 // Creates a mixed use array with path variables and string from template string route
 export function getRouteAsArray(route: string): string {
   return route

packages/core/src/types.ts

@@ -52,7 +52,7 @@ export interface NormalizedOutputOptions {
   packageJson?: PackageJson;
   headers: boolean;
   indexFiles: boolean;
-  baseUrl?: string | BaseUrlFromSpec | BaseUrlFromConstant;
+  baseUrl?: string | BaseUrlFromSpec | BaseUrlFromConstant | BaseUrlRuntime;
   allParamsOptional: boolean;
   urlEncodeParameters: boolean;
   unionAddMissingProperties: boolean;
@@ -215,6 +215,18 @@ export interface BaseUrlFromConstant {
   baseUrl: string;
 }
 
+/**
+ * Embed a runtime JavaScript expression into generated URL template literals
+ * (e.g. `process.env.API_BASE_URL`) so the same build can target different hosts at runtime.
+ */
+export interface BaseUrlRuntime {
+  runtime: string;
+  /** Named imports for symbols used in `runtime` (e.g. `{ name: 'apiBase', importPath: '../config' }`). */
+  imports?: GeneratorImport[];
+  getBaseUrlFromSpecification?: never;
+  baseUrl?: never;
+}
+
 export const PropertySortOrder = {
   ALPHABETICAL: 'Alphabetical',
   SPECIFICATION: 'Specification',
@@ -279,7 +291,7 @@ export interface OutputOptions {
   packageJson?: string;
   headers?: boolean;
   indexFiles?: boolean;
-  baseUrl?: string | BaseUrlFromSpec | BaseUrlFromConstant;
+  baseUrl?: string | BaseUrlFromSpec | BaseUrlFromConstant | BaseUrlRuntime;
   allParamsOptional?: boolean;
   urlEncodeParameters?: boolean;
   unionAddMissingProperties?: boolean;

packages/orval/src/client.ts

@@ -22,6 +22,7 @@ import type {
 import {
   asyncReduce,
   generateDependencyImports,
+  getBaseUrlRuntimeImports,
   isFunction,
   OutputClient,
   pascal,
@@ -254,6 +255,8 @@ export const generateOperations = (
   options: GeneratorOptions,
   output: NormalizedOutputOptions,
 ): Promise<GeneratorOperations> => {
+  const baseUrlImports = getBaseUrlRuntimeImports(output.baseUrl);
+
   return asyncReduce(
     verbsOptions,
     async (acc, verbOption) => {
@@ -293,7 +296,7 @@ export const generateOperations = (
         implementation: hasImplementation
           ? verbOption.doc + client.implementation
           : client.implementation,
-        imports: client.imports,
+        imports: [...baseUrlImports, ...client.imports],
         implementationMock: generatedMock.implementation,
         importsMock: generatedMock.imports,
         tags: verbOption.tags,