hey-api · mrlubos · Dec 11, 2025 · Nov 16, 2025 · Nov 23, 2025 · Nov 23, 2025
diff --git a/.changeset/clean-apes-divide.md b/.changeset/clean-apes-divide.md
@@ -0,0 +1,29 @@
+---
+'@hey-api/openapi-ts': patch
+---
+
+**output**: add `nameConflictResolver` option
+
+## Name Conflicts
+
+As your project grows, the chances of name conflicts increase. We use a simple conflict resolver that appends numeric suffixes to duplicate identifiers. If you prefer a different strategy, you can provide your own `nameConflictResolver` function.
+
+```js
+export default {
+  input: 'hey-api/backend', // sign up at app.heyapi.dev
+  output: {
+    nameConflictResolver({ attempt, baseName }) {
+      return attempt === 0 ? baseName : `${baseName}_N${attempt + 1}`;
+    },
+    path: 'src/client',
+  },
+};
+```
+
+Example output:
+
+```ts
+export type ChatCompletion = string;
+
+export type ChatCompletion_N2 = number;
+```
diff --git a/.changeset/eight-rabbits-unite.md b/.changeset/eight-rabbits-unite.md
@@ -0,0 +1,21 @@
+---
+'@hey-api/openapi-ts': minor
+---
+
+**output**: add `preferExportAll` option
+
+### Prefer named exports
+
+This release changes the default for `index.ts` to prefer named exports. Named exports may lead to better IDE and bundler performance compared to asterisk (`*`) as your tooling doesn't have to inspect the underlying module to discover exports.
+
+While this change is merely cosmetic, you can set `output.preferExportAll` to `true` if you prefer to use the asterisk.
+
+```js
+export default {
+  input: 'hey-api/backend', // sign up at app.heyapi.dev
+  output: {
+    path: 'src/client',
+    preferExportAll: true,
+  },
+};
+```
diff --git a/.changeset/gentle-spoons-kneel.md b/.changeset/gentle-spoons-kneel.md
@@ -0,0 +1,5 @@
+---
+'@hey-api/codegen-core': minor
+---
+
+**symbols**: remove `placeholder` property
diff --git a/.changeset/plenty-walls-repeat.md b/.changeset/plenty-walls-repeat.md
@@ -0,0 +1,9 @@
+---
+'@hey-api/openapi-ts': minor
+---
+
+**parser**: removed `symbol:setValue:*` events
+
+### Removed `symbol:setValue:*` events
+
+These events have been removed in favor of `node:set:*` events.
diff --git a/.vscode/launch.json b/.vscode/launch.json
@@ -15,8 +15,7 @@
       "skipFiles": ["<node_internals>/**"],
       "cwd": "${workspaceFolder}/dev",
       "runtimeExecutable": "node",
-      "runtimeArgs": ["-r", "ts-node/register/transpile-only"],
-      "program": "${workspaceFolder}/packages/openapi-ts/src/run.ts",
+      "program": "${workspaceFolder}/packages/openapi-ts/dist/run.mjs",
       "env": {
         "DEBUG": "false"
       }

diff --git a/dev/openapi-ts.config.ts b/dev/openapi-ts.config.ts
@@ -5,13 +5,16 @@ import path from 'node:path';
 // @ts-ignore
 import { customClientPlugin } from '@hey-api/custom-client/plugin';
 // @ts-ignore
-import { defineConfig, utils } from '@hey-api/openapi-ts';
+import { defineConfig, reserved, utils } from '@hey-api/openapi-ts';
 
 // @ts-ignore
 import { myClientPlugin } from '../packages/openapi-ts-tests/main/test/custom/client/plugin';
 // @ts-ignore
 import { getSpecsPath } from '../packages/openapi-ts-tests/utils';
 
+reserved.runtime.set((list) => [...list, 'Agent']);
+reserved.type.set((list) => [...list, 'Agent']);
+
 // @ts-ignore
 export default defineConfig(() => {
   // ...
@@ -39,15 +42,19 @@ export default defineConfig(() => {
             '3.1.x',
             // 'circular.yaml',
             // 'dutchie.json',
+            // 'enum-names-values.yaml',
             // 'invalid',
             // 'full.yaml',
+            // 'sdk-method-class-conflict.yaml',
             // 'object-property-names.yaml',
-            // 'openai.yaml',
-            'opencode.yaml',
+            'openai.yaml',
+            // 'opencode.yaml',
             // 'pagination-ref.yaml',
             // 'sdk-instance.yaml',
+            // 'sdk-nested-classes.yaml',
             // 'string-with-format.yaml',
             // 'transformers.json',
+            // 'transformers-recursive.json',
             // 'type-format.yaml',
             // 'validators.yaml',
             // 'validators-circular-ref.json',
@@ -96,10 +103,21 @@ export default defineConfig(() => {
           //   suffix: '.meh',
           // },
           // format: 'prettier',
-          importFileExtension: '.ts',
+          // importFileExtension: '.js',
           // indexFile: false,
           // lint: 'eslint',
+          nameConflictResolver({ attempt, baseName }) {
+            // console.log('resolving conflict for:', { attempt, baseName });
+            return attempt === 0 ? baseName : `${baseName}_N${attempt + 1}`;
+          },
           path: path.resolve(__dirname, '.gen'),
+          // preferExportAll: true,
+          resolveModuleName: (moduleName) => {
+            if (moduleName === 'valibot') {
+              return 'valibot';
+            }
+            return;
+          },
           // tsConfigPath: path.resolve(
           //   __dirname,
           //   'tsconfig',
@@ -128,6 +146,14 @@ export default defineConfig(() => {
         },
         hooks: {
           events: {
+            // 'node:set:after': ({ node, plugin }) => {
+            //   if (node) {
+            //     console.log(`(${plugin.name}) set node:`, node.symbol);
+            //   }
+            // },
+            // 'node:set:before': ({ node, plugin }) => {
+            //   console.log(`(${plugin.name}) setting node:`, node?.symbol?.id);
+            // },
             // 'plugin:handler:after': ({ plugin }) => {
             //   console.log(`(${plugin.name}): handler finished`);
             // },
@@ -153,12 +179,6 @@ export default defineConfig(() => {
               //   );
               // }
             },
-            // 'symbol:setValue:after': ({ plugin, symbol }) => {
-            //   console.log(`(${plugin.name}) set value:`, symbol.id);
-            // },
-            // 'symbol:setValue:before': ({ plugin, symbol }) => {
-            //   console.log(`(${plugin.name}) setting value:`, symbol.id);
-            // },
           },
           operations: {
             getKind() {
@@ -236,6 +256,7 @@ export default defineConfig(() => {
           //   error: '他們_error_{{name}}',
           //   name: '你們_errors_{{name}}',
           // },
+          // exportFromIndex: false,
           name: '@hey-api/typescript',
           // requests: '我們_data_{{name}}',
           // responses: {
@@ -261,10 +282,10 @@ export default defineConfig(() => {
           //   fields.unwrap('path')
           // },
           // include...
-          // instance: true,
+          instance: true,
           name: '@hey-api/sdk',
           // operationId: false,
-          paramsStructure: 'flat',
+          // paramsStructure: 'flat',
           // responseStyle: 'data',
           // signature: 'auto',
           // signature: 'client',
@@ -305,16 +326,18 @@ export default defineConfig(() => {
           // case: 'SCREAMING_SNAKE_CASE',
           // comments: false,
           exportFromIndex: true,
-          // infiniteQueryKeys: {
-          //   name: '{{name}}IQK',
-          // },
+          infiniteQueryKeys: {
+            // name: '{{name}}IQK',
+            // name: 'options',
+          },
           infiniteQueryOptions: {
             meta() {
               return {
                 custom: 'value',
               };
             },
             // name: '{{name}}IQO',
+            // name: 'options',
           },
           mutationOptions: {
             meta() {
@@ -323,10 +346,12 @@ export default defineConfig(() => {
               };
             },
             // name: '{{name}}MO',
+            // name: 'options',
           },
           name: '@tanstack/react-query',
           queryKeys: {
             // name: '{{name}}QK',
+            // name: 'options',
             tags: true,
           },
           // queryOptions: false,
@@ -336,7 +361,8 @@ export default defineConfig(() => {
             //     custom: 'value',
             //   }
             // },
-            name: '{{name}}QO',
+            // name: '{{name}}QO',
+            // name: 'options',
           },
           useQuery: true,
           '~hooks': {
@@ -365,18 +391,18 @@ export default defineConfig(() => {
         {
           // case: 'SCREAMING_SNAKE_CASE',
           // comments: false,
-          // definitions: 'z{{name}}Definition',
+          definitions: 'z{{name}}',
           exportFromIndex: true,
           // metadata: true,
           // name: 'valibot',
           // requests: {
           //   case: 'PascalCase',
           //   name: '{{name}}Data',
           // },
-          // responses: {
-          //   // case: 'snake_case',
-          //   name: 'z{{name}}TestResponse',
-          // },
+          responses: {
+            // case: 'snake_case',
+            name: 'z{{name}}TestResponse',
+          },
           // webhooks: {
           //   name: 'q{{name}}CoolWebhook',
           // },
@@ -416,17 +442,23 @@ export default defineConfig(() => {
                 // 'date-time': ({ $, pipes }) => pipes.push($('v').attr('isoDateTime').call()),
               },
             },
-            validator({ $, schema, v }) {
-              return [
-                $.const('parsed').assign(
-                  $(v.placeholder)
-                    .attr('safeParseAsync')
-                    .call(schema.placeholder, 'data')
-                    .await(),
-                ),
-                $('parsed').return(),
-              ];
-            },
+            // validator({ $, plugin, schema, v }) {
+            //   const vShadow = plugin.symbol('v');
+            //   const test = plugin.symbol('test');
+            //   const e = plugin.symbol('err');
+            //   return [
+            //     $.const(vShadow).assign($.literal('hi')),
+            //     $('console').attr('log').call(vShadow),
+            //     $.try(
+            //       $.const(test).assign($.literal('test')),
+            //       $('console').attr('log').call($.literal('hi'), test),
+            //     ).catchArg(e),
+            //     $.const('parsed').assign(
+            //       $(v).attr('safeParseAsync').call(schema, 'data').await(),
+            //     ),
+            //     $('parsed').return(),
+            //   ];
+            // },
           },
         },
         {
@@ -443,7 +475,7 @@ export default defineConfig(() => {
             //     infer: 'D{{name}}ZodType',
             //   },
           },
-          // exportFromIndex: true,
+          exportFromIndex: true,
           metadata: true,
           // name: 'zod',
           // requests: {
@@ -496,17 +528,14 @@ export default defineConfig(() => {
                 // 'date-time': ({ $ }) => $('z').attr('date').call(),
               },
             },
-            validator({ $, schema }) {
-              return [
-                $.const('parsed').assign(
-                  $(schema.placeholder)
-                    .attr('safeParseAsync')
-                    .call('data')
-                    .await(),
-                ),
-                $('parsed').return(),
-              ];
-            },
+            // validator({ $, schema }) {
+            //   return [
+            //     $.const('parsed').assign(
+            //       $(schema).attr('safeParseAsync').call('data').await(),
+            //     ),
+            //     $('parsed').return(),
+            //   ];
+            // },
           },
         },
         {
@@ -527,7 +556,7 @@ export default defineConfig(() => {
         {
           exportFromIndex: true,
           // mutationOptions: '{{name}}Mutationssss',
-          // name: '@pinia/colada',
+          name: '@pinia/colada',
           // queryOptions: {
           //   name: '{{name}}Queryyyyy',
           // },
@@ -546,7 +575,6 @@ export default defineConfig(() => {
           },
         },
       ],
-      // useOptions: false,
       // watch: 3_000,
     },
     // {

diff --git a/docs/index.md b/docs/index.md
@@ -15,8 +15,8 @@ hero:
       text: Roadmap
       theme: alt
   image:
-    alt: Two people looking at the blueprint
-    src: /images/blueprint-640w.png
+    alt: Two people looking at the TypeScript logo
+    src: /images/hero-920w.png
 
 features:
   - icon: <svg class="icon-openapi" width="24" height="24" fill="none" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 30 32"><path d="M8.96 18.397H.515l.005.123.014.238.007.102.022.275.006.061.033.304.003.03.043.327c.098.677.243 1.343.437 1.999l.003.008.1.326.006.018.093.276.025.07.087.24.04.107.078.2.06.149.065.154.086.188.05.114.105.225.035.072.126.256.02.039.154.293.033.057 7.235-4.366a5.754 5.754 0 0 1-.528-1.885ZM.914 22.27l.002.007.273-.085-.275.078ZM11.034 22.275l-5.97 5.967.092.085.255.227.203.172.055.045.232.187.03.024.255.196a.066.066 0 0 1 .01.007l1.113.752.04.024.219.13.134.076.128.072.232.126.032.017.658.32 3.213-7.805a5.719 5.719 0 0 1-.934-.623l.003.001ZM10.415 21.683l-.186-.219-.154-.199-.165-.233-.154-.241-7.22 4.349.371.584.03.044.002.003.388.547.009.011.008.011.176.229.21.261.045.055.173.203.076.087.15.171.084.092.039.042.114.12.046.047.2.204 5.956-5.956-.195-.209-.003-.003ZM18.31 22.272l-.2.154.016.025 4.342 7.209.594-.41c.42-.31.827-.645 1.22-1.007l-5.949-5.947-.023-.024ZM21.92 30.003l.01-.006-.01.006Zm-.005.003ZM21.929 29.994l.057-.028-.001-.002-.056.033v-.003Zm-.01.009-.002.001.002-.001ZM21.916 30.006l-.011-.018.01.018Zm.004-.003.01-.005-.01.005Z" fill="#fff"></path><path d="m21.837 29.719-4.2-6.97-.25.139-.256.128a5.756 5.756 0 0 1-4.106.319l-.27-.095-.27-.095-3.207 7.788.024.009.024.009.007.003.615.235a14.262 14.262 0 0 0 3.007.708l.349.038.056.005.28.023.095.006.245.014.15.006.195.007.348.004c.788 0 1.575-.066 2.352-.196l.04-.006.246-.045.143-.027.145-.03.24-.053.044-.01a14.241 14.241 0 0 0 3.398-1.267l.209-.115.424-.238-.007-.02.01.018.014-.008.056-.034-.15-.25Zm-10.8-16.335.2-.155-.015-.024-4.343-7.206-.595.41c-.42.31-.827.645-1.218 1.006l5.948 5.945.024.024ZM4.654 7.808l-.395.413c-.44.476-.841.971-1.203 1.491l-.052.075-.121.178-.123.188-.045.068a14.135 14.135 0 0 0-2.2 7.035l-.007.286-.005.285h8.424l.013-.285.016-.286a5.716 5.716 0 0 1 1.27-3.068c.058-.073.128-.142.192-.212.065-.07.124-.144.192-.212L4.654 7.808Zm17.38-2.09L22 5.695l-.224-.132-.13-.075-.132-.073-.228-.123-.036-.019a14.74 14.74 0 0 0-1.52-.686l-.04-.015-.342-.124a14.216 14.216 0 0 0-2.839-.673l-.118-.016-.119-.013-.228-.025-.064-.006-.273-.023-.342-.02-.124-.006v8.444c.433.045.862.138 1.279.279l6.216-6.211a13.96 13.96 0 0 0-.703-.461h.002ZM7.363 5.692l.147.244-.147-.244Zm0 0L7.36 5.69l.004.002Z" fill="#fff"></path><path d="m14.388 3.664-.285.005a14.24 14.24 0 0 0-1.78.184l-.04.007-.247.044-.143.027-.145.03-.24.053-.043.01a14.252 14.252 0 0 0-3.4 1.268l-.705.398v.001l4.349 7.219.25-.14a5.727 5.727 0 0 1 2.141-.657l.285-.022s.19-.01.286-.01V3.658c-.095 0-.19.003-.285.005h.002ZM28.827 17.131l-.014-.227-.007-.113-.022-.267-.006-.07-.032-.297-.002-.024-.002-.012-.043-.32-.001-.01a14.164 14.164 0 0 0-.436-1.992l-.003-.013-.094-.304-.013-.04-.091-.272-.026-.074-.086-.235-.043-.111-.075-.194-.063-.153-.063-.15-.083-.191-.049-.108-.107-.228-.033-.069-.128-.259-.018-.035-.149-.286c-.002-.003-.003-.007-.006-.01a14.217 14.217 0 0 0-.806-1.308l-6.217 6.218c.14.415.233.844.278 1.279h8.444l-.004-.125ZM20.42 17.828l-.013.285-.016.286a5.709 5.709 0 0 1-1.27 3.068c-.057.073-.128.142-.192.212s-.123.144-.191.212l5.956 5.956c.067-.068.13-.138.197-.206l.197-.207c.44-.477.843-.977 1.206-1.496l.043-.06.13-.193.113-.173.057-.084a14.13 14.13 0 0 0 2.196-7.03l.007-.285.005-.286H20.42Z" fill="#fff"></path></svg>