Merge pull request #3770 from inas-sirhan/fix/runtime-config-path

fix(client-core): resolve runtimeConfigPath relative to generated output

Author: mrlubos

.changeset/fix-runtime-config-path.md

@@ -0,0 +1,10 @@
+---
+"@hey-api/openapi-ts": minor
+---
+
+**BREAKING** **client**: resolve `runtimeConfigPath` relative to the output folder
+
+### Changed `runtimeConfigPath` behavior
+
+This was a known, long-standing issue confusing first-time users. Before, defining client `runtimeConfigPath` value would paste it verbatim to the generated output. This release changes the behavior to resolve relative to the current working directory the same way output path works.
+

.changeset/weak-avocados-tap.md

@@ -2,4 +2,8 @@
 "@hey-api/openapi-ts": minor
 ---
 
-**plugin(@hey-api/client-ky)**: respect ky instance defaults
+**BREAKING** **plugin(@hey-api/client-ky)**: respect ky instance defaults
+
+### Changed Ky client behavior
+
+The Ky client was updated to be more intuitive. Some Ky options now need to be passed via the `kyOptions` field and you need to pass `undefined` to unset an option.

docs/openapi-ts/migrating.md

@@ -7,6 +7,16 @@ description: Migrating to @hey-api/openapi-ts.
 
 While we try to avoid breaking changes, sometimes it's unavoidable in order to offer you the latest features. This page lists changes that require updates to your code. If you run into a problem with migration, please [open an issue](https://github.com/hey-api/openapi-ts/issues).
 
+## v0.97.0
+
+### Changed `runtimeConfigPath` behavior
+
+This was a known, long-standing issue confusing first-time users. Before, defining client `runtimeConfigPath` value would paste it verbatim to the generated output. This release changes the behavior to resolve relative to the output folder.
+
+### Changed Ky client behavior
+
+The Ky client was updated to be more intuitive. Some Ky options now need to be passed via the `kyOptions` field and you need to pass `undefined` to unset an option.
+
 ## v0.96.0
 
 ### Removed Node 20 support

examples/openapi-ts-next/openapi-ts.config.ts

@@ -13,7 +13,7 @@ export default defineConfig({
   plugins: [
     {
       name: '@hey-api/client-next',
-      runtimeConfigPath: '../hey-api',
+      runtimeConfigPath: './src/hey-api',
     },
     '@hey-api/sdk',
     {

packages/openapi-ts/src/plugins/@hey-api/client-core/__tests__/client.test.ts

@@ -0,0 +1,65 @@
+import path from 'node:path';
+
+import { resolveRuntimeConfigPath } from '../../client-core/client';
+
+describe('resolveRuntimeConfigPath', () => {
+  it('preserves path mapping and module specifiers', () => {
+    const outputPath = path.join(process.cwd(), 'src/client');
+
+    expect(
+      resolveRuntimeConfigPath({
+        outputPath,
+        runtimeConfigPath: '~/foo.ts',
+      }),
+    ).toBe('~/foo.ts');
+
+    expect(
+      resolveRuntimeConfigPath({
+        outputPath,
+        runtimeConfigPath: '@/foo.ts',
+      }),
+    ).toBe('@/foo.ts');
+
+    expect(
+      resolveRuntimeConfigPath({
+        outputPath,
+        runtimeConfigPath: '@scope/runtime-config',
+      }),
+    ).toBe('@scope/runtime-config');
+  });
+
+  it('resolves relative filesystem paths from cwd to output-relative import', () => {
+    const outputPath = path.join(process.cwd(), 'src/client');
+
+    expect(
+      resolveRuntimeConfigPath({
+        outputPath,
+        runtimeConfigPath: './src/hey-api.ts',
+      }),
+    ).toBe('../hey-api.ts');
+  });
+
+  it('resolves absolute filesystem paths to output-relative import', () => {
+    const cwd = process.cwd();
+    const outputPath = path.join(cwd, 'src/client');
+
+    expect(
+      resolveRuntimeConfigPath({
+        outputPath,
+        runtimeConfigPath: path.join(cwd, 'src/runtime/hey-api.ts'),
+      }),
+    ).toBe('../runtime/hey-api.ts');
+  });
+
+  it('adds ./ prefix for same-directory files', () => {
+    const cwd = process.cwd();
+    const outputPath = path.join(cwd, 'src/client');
+
+    expect(
+      resolveRuntimeConfigPath({
+        outputPath,
+        runtimeConfigPath: path.join(cwd, 'src/client/hey-api.ts'),
+      }),
+    ).toBe('./hey-api.ts');
+  });
+});

packages/openapi-ts/src/plugins/@hey-api/client-core/client.ts

@@ -1,3 +1,5 @@
+import path from 'node:path';
+
 import { parseUrl } from '@hey-api/shared';
 
 import { getTypedConfig } from '../../../config/utils';
@@ -6,7 +8,28 @@ import { $ } from '../../../ts-dsl';
 import type { PluginHandler } from './types';
 import { getClientBaseUrlKey } from './utils';
 
-const resolveBaseUrlString = ({ plugin }: Parameters<PluginHandler>[0]): string | undefined => {
+export function resolveRuntimeConfigPath({
+  outputPath,
+  runtimeConfigPath,
+}: {
+  outputPath: string;
+  runtimeConfigPath: string;
+}): string {
+  const isAbsolutePath = path.isAbsolute(runtimeConfigPath);
+  // Use a single regex to match './' or '../' at the start
+  const isFileSystemPath = isAbsolutePath || /^\.\.?\//.test(runtimeConfigPath);
+  if (!isFileSystemPath) {
+    return runtimeConfigPath;
+  }
+
+  const absoluteInputPath = isAbsolutePath
+    ? runtimeConfigPath
+    : path.resolve(process.cwd(), runtimeConfigPath);
+  const relative = path.relative(outputPath, absoluteInputPath).split(path.sep).join('/');
+  return relative.startsWith('.') ? relative : `./${relative}`;
+}
+
+function resolveBaseUrlString({ plugin }: Parameters<PluginHandler>[0]): string | undefined {
   const { baseUrl } = plugin.config;
 
   if (baseUrl === false) {
@@ -24,7 +47,7 @@ const resolveBaseUrlString = ({ plugin }: Parameters<PluginHandler>[0]): string
   }
 
   return servers[typeof baseUrl === 'number' ? baseUrl : 0]?.url;
-};
+}
 
 export const createClient: PluginHandler = ({ plugin }) => {
   const clientModule = clientFolderAbsolutePath(getTypedConfig(plugin));
@@ -43,7 +66,10 @@ export const createClient: PluginHandler = ({ plugin }) => {
   const { runtimeConfigPath } = plugin.config;
   const symbolCreateClientConfig = runtimeConfigPath
     ? plugin.symbol('createClientConfig', {
-        external: runtimeConfigPath,
+        external: resolveRuntimeConfigPath({
+          outputPath: getTypedConfig(plugin).output.path,
+          runtimeConfigPath,
+        }),
       })
     : undefined;
 

packages/openapi-ts/src/plugins/@hey-api/client-core/createClientConfig.ts

@@ -3,7 +3,7 @@ import { clientFolderAbsolutePath } from '../../../generate/client';
 import { $ } from '../../../ts-dsl';
 import type { PluginHandler } from './types';
 
-export const createClientConfigType = ({ plugin }: Parameters<PluginHandler>[0]) => {
+export function createClientConfigType({ plugin }: Parameters<PluginHandler>[0]): void {
   const clientModule = clientFolderAbsolutePath(getTypedConfig(plugin));
   const symbolClientOptions = plugin.referenceSymbol({
     category: 'type',
@@ -47,4 +47,4 @@ export const createClientConfigType = ({ plugin }: Parameters<PluginHandler>[0])
         ),
     );
   plugin.node(typeCreateClientConfig);
-};
+}

packages/openapi-ts/src/plugins/@hey-api/client-core/plugin.ts

@@ -2,7 +2,7 @@ import { createClient } from './client';
 import { createClientConfigType } from './createClientConfig';
 import type { PluginHandler } from './types';
 
-export const clientPluginHandler = ({ plugin }: Parameters<PluginHandler>[0]) => {
+export function clientPluginHandler({ plugin }: Parameters<PluginHandler>[0]): void {
   createClientConfigType({ plugin });
   createClient({ plugin });
-};
+}