Merge pull request #3616 from hey-api/refactor/output-module

fix: add output.module option

Author: mrlubos

.changeset/tangy-cities-carry.md

@@ -0,0 +1,6 @@
+---
+"@hey-api/openapi-ts": patch
+"@hey-api/shared": patch
+---
+
+**output**: add `module` option

docs/openapi-ts/clients/ofetch.md

@@ -144,7 +144,7 @@ Interceptors (middleware) can be used to modify requests before they're sent or
 The `ofetch` client supports two complementary options:
 
 - built-in Hey API interceptors exposed via `client.interceptors`
-- native `ofetch` hooks passed through config (e.g. `onRequest`)
+- native `ofetch` hooks passed through config (e.g., `onRequest`)
 
 ### Example: Request interceptor
 

docs/openapi-ts/configuration/output.md

@@ -36,7 +36,11 @@ export default {
 
 You can learn more about complex use cases in the [Advanced](/openapi-ts/configuration#advanced) section.
 
-## File Name
+## File
+
+Control how files are named and annotated in the generated output.
+
+### File Name
 
 You can customize the naming and casing pattern for files using the `fileName` option.
 
@@ -108,66 +112,95 @@ export default {
 
 :::
 
-## Module Extension
+### File Header
 
-You can customize the extension used for TypeScript modules.
+The generated output includes a notice in every file warning that any modifications will be lost when the files are regenerated. You can customize or disable this notice using the `header` option.
 
 ::: code-group
 
-```js [default]
-export default {
-  input: 'hey-api/backend', // sign up at app.heyapi.dev
-  output: {
-    importFileExtension: undefined, // [!code ++]
-    path: 'src/client',
-  },
-};
+```js [example]
+/* eslint-disable */
+// This file is auto-generated by @hey-api/openapi-ts
+
+/** ... */
 ```
 
-```js [disabled]
+<!-- prettier-ignore-start -->
+```js [config]
 export default {
   input: 'hey-api/backend', // sign up at app.heyapi.dev
   output: {
-    importFileExtension: null, // [!code ++]
+    header: (ctx) => [ // [!code ++]
+      '/* eslint-disable */', // [!code ++]
+      ...ctx.defaultValue, // [!code ++]
+    ], // [!code ++]
     path: 'src/client',
   },
 };
 ```
+<!-- prettier-ignore-end -->
+
+:::
+
+## Module
+
+Control how module specifiers are generated in the output.
+
+### Module Extension
+
+Set `module.extension` to define the file extension used in import specifiers. This is useful when targeting environments that require fully specified imports (e.g., Node ESM or certain bundlers).
+
+::: code-group
+
+```js [example]
+import foo from './foo.js';
+import bar from './bar.js';
+```
 
-```js [js]
+```js [config]
 export default {
   input: 'hey-api/backend', // sign up at app.heyapi.dev
   output: {
-    importFileExtension: '.js', // [!code ++]
+    module: {
+      extension: '.js', // [!code ++]
+    },
     path: 'src/client',
   },
 };
 ```
 
-```js [ts]
+:::
+
+### Module Path
+
+Use `module.resolve` for full control over how module specifiers are generated. This lets you override specific modules or redirect them to custom locations (e.g., CDNs or internal aliases).
+
+::: code-group
+
+```js [example]
+import * as z from 'https://esm.sh/zod';
+```
+
+<!-- prettier-ignore-start -->
+```js [config]
 export default {
   input: 'hey-api/backend', // sign up at app.heyapi.dev
   output: {
-    importFileExtension: '.ts', // [!code ++]
+    module: {
+      resolve(path) { // [!code ++]
+        if (path === 'zod') { // [!code ++]
+          return 'https://esm.sh/zod'; // [!code ++]
+        } // [!code ++]
+      }, // [!code ++]
+    },
     path: 'src/client',
   },
 };
 ```
+<!-- prettier-ignore-end -->
 
 :::
 
-By default, we don't add a file extension and let the runtime resolve it.
-
-```js
-import foo from './foo';
-```
-
-If we detect a [TSConfig file](#tsconfig-path) with `moduleResolution` option set to `nodenext`, we default the extension to `.js`.
-
-```js
-import foo from './foo.js';
-```
-
 ## Source
 
 Source is a copy of the input specification used to generate your output. It can be used to power documentation tools or to persist a stable snapshot alongside your generated files.
@@ -337,36 +370,6 @@ export type ChatCompletion_N2 = number;
 
 :::
 
-## File Header
-
-The generated output includes a notice in every file warning that any modifications will be lost when the files are regenerated. You can customize or disable this notice using the `header` option.
-
-::: code-group
-
-<!-- prettier-ignore-start -->
-```js [config]
-export default {
-  input: 'hey-api/backend', // sign up at app.heyapi.dev
-  output: {
-    header: [
-      '/* eslint-disable */', // [!code ++]
-      '// This file is auto-generated by @hey-api/openapi-ts', // [!code ++]
-    ],
-    path: 'src/client',
-  },
-};
-```
-<!-- prettier-ignore-end -->
-
-```ts [example]
-/* eslint-disable */
-// This file is auto-generated by @hey-api/openapi-ts
-
-/** ... */
-```
-
-:::
-
 ## TSConfig Path
 
 We use the [TSConfig file](https://www.typescriptlang.org/tsconfig/) to generate output matching your project's settings. By default, we attempt to find a TSConfig file starting from the location of the `@hey-api/openapi-ts` configuration file and traversing up.

docs/openapi-ts/migrating.md

@@ -422,7 +422,7 @@ If you need to access individual fields, you can do so using the [`.shape`](http
 
 ### Bundle `@hey-api/client-*` plugins
 
-In previous releases, you had to install a separate client package to generate a fully working output, e.g. `npm install @hey-api/client-fetch`. This created a few challenges: getting started was slower, upgrading was sometimes painful, and bundling too. Beginning with v0.73.0, all Hey API clients are bundled by default and don't require installing any additional dependencies. You can remove any installed client packages and re-run `@hey-api/openapi-ts`.
+In previous releases, you had to install a separate client package to generate a fully working output, e.g., `npm install @hey-api/client-fetch`. This created a few challenges: getting started was slower, upgrading was sometimes painful, and bundling too. Beginning with v0.73.0, all Hey API clients are bundled by default and don't require installing any additional dependencies. You can remove any installed client packages and re-run `@hey-api/openapi-ts`.
 
 ```sh
 npm uninstall @hey-api/client-fetch

docs/openapi-ts/plugins/concepts/resolvers.md

@@ -130,7 +130,7 @@ export const vAmount = v.number();
 
 ### Replace default base
 
-You might want to replace the default base schema, e.g. `v.object()`.
+You might want to replace the default base schema, e.g., `v.object()`.
 
 ```js
 export const vUser = v.object({

docs/openapi-ts/plugins/pinia-colada.md

@@ -60,7 +60,7 @@ The Pinia Colada plugin will generate the following artifacts, depending on the
 
 ## Queries
 
-Queries are generated from [query operations](/openapi-ts/configuration/parser#hooks-query-operations). The generated query functions follow the naming convention of SDK functions and by default append `Query`, e.g. `getPetByIdQuery()`.
+Queries are generated from [query operations](/openapi-ts/configuration/parser#hooks-query-operations). The generated query functions follow the naming convention of SDK functions and by default append `Query`, e.g., `getPetByIdQuery()`.
 
 ::: code-group
 
@@ -191,7 +191,7 @@ export default {
 
 :::
 
-Alternatively, you can access the same query key by calling query key functions. The generated query key functions follow the naming convention of SDK functions and by default append `QueryKey`, e.g. `getPetByIdQueryKey()`.
+Alternatively, you can access the same query key by calling query key functions. The generated query key functions follow the naming convention of SDK functions and by default append `QueryKey`, e.g., `getPetByIdQueryKey()`.
 
 ::: code-group
 
@@ -223,7 +223,7 @@ You can customize the naming and casing pattern for `queryKeys` functions using
 
 ## Mutations
 
-Mutations are generated from [mutation operations](/openapi-ts/configuration/parser#hooks-mutation-operations). The generated mutation functions follow the naming convention of SDK functions and by default append `Mutation`, e.g. `addPetMutation()`.
+Mutations are generated from [mutation operations](/openapi-ts/configuration/parser#hooks-mutation-operations). The generated mutation functions follow the naming convention of SDK functions and by default append `Mutation`, e.g., `addPetMutation()`.
 
 ::: code-group
 

docs/openapi-ts/plugins/tanstack-query.md

@@ -115,7 +115,7 @@ The TanStack Query plugin will generate the following artifacts, depending on th
 
 ## Queries
 
-Queries are generated from [query operations](/openapi-ts/configuration/parser#hooks-query-operations). The generated query functions follow the naming convention of SDK functions and by default append `Options`, e.g. `getPetByIdOptions()`.
+Queries are generated from [query operations](/openapi-ts/configuration/parser#hooks-query-operations). The generated query functions follow the naming convention of SDK functions and by default append `Options`, e.g., `getPetByIdOptions()`.
 
 ::: code-group
 
@@ -281,7 +281,7 @@ export default {
 
 :::
 
-Alternatively, you can access the same query key by calling query key functions. The generated query key functions follow the naming convention of SDK functions and by default append `QueryKey`, e.g. `getPetByIdQueryKey()`.
+Alternatively, you can access the same query key by calling query key functions. The generated query key functions follow the naming convention of SDK functions and by default append `QueryKey`, e.g., `getPetByIdQueryKey()`.
 
 ::: code-group
 
@@ -313,7 +313,7 @@ You can customize the naming and casing pattern for `queryKeys` functions using
 
 ## Infinite Queries
 
-Infinite queries are generated from [query operations](/openapi-ts/configuration/parser#hooks-query-operations) if we detect a [pagination](/openapi-ts/configuration/parser#pagination) parameter. The generated infinite query functions follow the naming convention of SDK functions and by default append `InfiniteOptions`, e.g. `getFooInfiniteOptions()`.
+Infinite queries are generated from [query operations](/openapi-ts/configuration/parser#hooks-query-operations) if we detect a [pagination](/openapi-ts/configuration/parser#pagination) parameter. The generated infinite query functions follow the naming convention of SDK functions and by default append `InfiniteOptions`, e.g., `getFooInfiniteOptions()`.
 
 ::: code-group
 
@@ -483,7 +483,7 @@ export default {
 
 :::
 
-Alternatively, you can access the same query key by calling query key functions. The generated query key functions follow the naming convention of SDK functions and by default append `InfiniteQueryKey`, e.g. `getPetByIdInfiniteQueryKey()`.
+Alternatively, you can access the same query key by calling query key functions. The generated query key functions follow the naming convention of SDK functions and by default append `InfiniteQueryKey`, e.g., `getPetByIdInfiniteQueryKey()`.
 
 ::: code-group
 
@@ -515,7 +515,7 @@ You can customize the naming and casing pattern for `infiniteQueryKeys` function
 
 ## Mutations
 
-Mutations are generated from [mutation operations](/openapi-ts/configuration/parser#hooks-mutation-operations). The generated mutation functions follow the naming convention of SDK functions and by default append `Mutation`, e.g. `addPetMutation()`.
+Mutations are generated from [mutation operations](/openapi-ts/configuration/parser#hooks-mutation-operations). The generated mutation functions follow the naming convention of SDK functions and by default append `Mutation`, e.g., `addPetMutation()`.
 
 ::: code-group
 

docs/openapi-ts/plugins/transformers.md

@@ -21,7 +21,7 @@ Before deciding whether transformers are right for you, let's explain how they w
 
 Transformers handle only the most common scenarios. Some of the known limitations are:
 
-- union types are not transformed (e.g. if you have multiple possible response shapes)
+- union types are not transformed (e.g., if you have multiple possible response shapes)
 - only types defined through `$ref` are transformed
 - error responses are not transformed
 

packages/openapi-python/src/config/output/config.ts

@@ -24,6 +24,7 @@ export function getOutput(userConfig: { output: MaybeArray<string | UserOutput>
         name: '{{name}}',
         suffix: '_gen',
       },
+      module: {},
       path: '',
       postProcess: [],
       preferExportAll: false,
@@ -48,8 +49,8 @@ export function getOutput(userConfig: { output: MaybeArray<string | UserOutput>
     },
     value: userOutput,
   }) as Output;
-  if (output.importFileExtension && !output.importFileExtension.startsWith('.')) {
-    output.importFileExtension = `.${output.importFileExtension}`;
+  if (output.module.extension && !output.module.extension.startsWith('.')) {
+    output.module.extension = `.${output.module.extension}`;
   }
   output.postProcess = normalizePostProcess(userOutput.postProcess);
   output.source = resolveSource(output);

packages/openapi-python/src/config/output/types.ts

@@ -1,20 +1,8 @@
 import type { BaseOutput, BaseUserOutput, UserPostProcessor } from '@hey-api/shared';
-import type { AnyString } from '@hey-api/types';
 
 import type { PostProcessorPreset } from './postprocess';
 
-type ImportFileExtensions = '.py';
-
-export type UserOutput = BaseUserOutput & {
-  /**
-   * If specified, this will be the file extension used when importing
-   * other modules. By default, we don't add a file extension and let the
-   * runtime resolve it. If you're using moduleResolution `nodenext` or
-   * `node16`, we default to `.js`.
-   *
-   * @default undefined
-   */
-  importFileExtension?: ImportFileExtensions | AnyString | null;
+export type UserOutput = BaseUserOutput<'.py'> & {
   /**
    * Post-processing commands to run on the output folder, executed in order.
    *
@@ -35,14 +23,7 @@ export type UserOutput = BaseUserOutput & {
   preferExportAll?: boolean;
 };
 
-export type Output = BaseOutput & {
-  /**
-   * If specified, this will be the file extension used when importing
-   * other modules. By default, we don't add a file extension and let the
-   * runtime resolve it. If you're using moduleResolution `nodenext` or
-   * `node16`, we default to `.js`.
-   */
-  importFileExtension: ImportFileExtensions | AnyString | null | undefined;
+export type Output = BaseOutput<'.py'> & {
   /**
    * Whether `export * from 'module'` should be used when possible
    * instead of named exports.