feat: move clients to plugins

Author: mrlubos

.changeset/afraid-eyes-greet.md

@@ -0,0 +1,26 @@
+---
+'@hey-api/openapi-ts': patch
+---
+
+fix: move sdk.throwOnError option to client.throwOnError
+
+### Moved `sdk.throwOnError` option
+
+This SDK configuration option has been moved to the client plugins where applicable. Not every client can be configured to throw on error, so it didn't make sense to expose the option when it didn't have any effect.
+
+```js
+export default {
+  input: 'path/to/openapi.json',
+  output: 'src/client',
+  plugins: [
+    {
+      name: '@hey-api/client-fetch',
+      throwOnError: true, // [!code ++]
+    },
+    {
+      name: '@hey-api/sdk',
+      throwOnError: true, // [!code --]
+    },
+  ],
+};
+```

.changeset/friendly-jars-argue.md

@@ -0,0 +1,14 @@
+---
+'@hey-api/openapi-ts': patch
+---
+
+fix: sdks import client from client.gen.ts instead of defining it inside the file
+
+### Added `client.gen.ts` file
+
+The internal `client` instance previously located in `sdk.gen.ts` is now defined in `client.gen.ts`. If you're importing it in your code, update the import module.
+
+```js
+import { client } from 'client/sdk.gen'; // [!code --]
+import { client } from 'client/client.gen'; // [!code ++]
+```

.changeset/happy-ladybugs-type.md

@@ -0,0 +1,5 @@
+---
+'@hey-api/openapi-ts': patch
+---
+
+fix: throw if inferred plugin not found

.changeset/late-moons-impress.md

@@ -0,0 +1,18 @@
+---
+'@hey-api/openapi-ts': minor
+---
+
+feat: move clients to plugins
+
+### Client plugins
+
+Clients are now plugins generating their own `client.gen.ts` file. There's no migration needed if you're using CLI. If you're using the configuration file, move `client` options to `plugins`.
+
+```js
+export default {
+  client: '@hey-api/client-fetch', // [!code --]
+  input: 'path/to/openapi.json',
+  output: 'src/client',
+  plugins: ['@hey-api/client-fetch'], // [!code ++]
+};
+```

.changeset/tiny-poets-cross.md

@@ -0,0 +1,7 @@
+---
+'@hey-api/client-axios': patch
+'@hey-api/client-fetch': patch
+'@hey-api/client-nuxt': patch
+---
+
+fix: export CreateClientConfig type

.github/workflows/ci.yml

@@ -39,7 +39,7 @@ jobs:
 
       - name: Build examples
         if: matrix.node-version == '22.11.0' && matrix.os == 'ubuntu-latest'
-        run: pnpm --filter './examples/**' run build
+        run: pnpm --filter './examples/**' --filter '!./examples/openapi-ts-sample' run build
 
       - name: Run linter
         run: pnpm lint

.gitignore

@@ -12,6 +12,7 @@ yarn-error.log*
 dist
 coverage
 .env
+.next
 .nuxt
 .output
 .svelte-kit

.prettierignore

@@ -2,6 +2,7 @@
 **/node_modules
 **/templates
 **/dist
+**/.next
 **/.nuxt
 **/.output
 **/.svelte-kit

README.md

@@ -34,7 +34,7 @@
 - supports OpenAPI 2.0, 3.0, and 3.1 specifications
 - supports JSON and YAML input files
 - generates TypeScript interfaces and SDKs
-- Fetch API, Axios, Angular, Node.js, and XHR clients available
+- Fetch API, Axios, Nuxt, Angular, Node.js, and XHR clients available
 - plugin ecosystem to reduce third-party boilerplate
 
 ## Sponsors
@@ -57,9 +57,9 @@ The fastest way to use `@hey-api/openapi-ts` is via npx
 
 ```sh
 npx @hey-api/openapi-ts \
-  -c @hey-api/client-fetch \
   -i path/to/openapi.json \
   -o src/client \
+  -c @hey-api/client-fetch
 ```
 
 Congratulations on creating your first client! 🎉 You can learn more about the generated files on the [Output](https://heyapi.dev/openapi-ts/output) page.
@@ -114,9 +114,9 @@ You can also generate clients programmatically by importing `@hey-api/openapi-ts
 import { createClient } from '@hey-api/openapi-ts';
 
 createClient({
-  client: '@hey-api/client-fetch',
   input: 'path/to/openapi.json',
   output: 'src/client',
+  plugins: ['@hey-api/client-fetch'],
 });
 ```
 
@@ -130,9 +130,9 @@ createClient({
 import { defineConfig } from '@hey-api/openapi-ts';
 
 export default defineConfig({
-  client: '@hey-api/client-fetch',
   input: 'path/to/openapi.json',
   output: 'src/client',
+  plugins: ['@hey-api/client-fetch'],
 });
 ```
 
@@ -141,9 +141,9 @@ export default defineConfig({
 ```js
 /** @type {import('@hey-api/openapi-ts').UserConfig} */
 module.exports = {
-  client: '@hey-api/client-fetch',
   input: 'path/to/openapi.json',
   output: 'src/client',
+  plugins: ['@hey-api/client-fetch'],
 };
 ```
 
@@ -152,9 +152,9 @@ module.exports = {
 ```js
 /** @type {import('@hey-api/openapi-ts').UserConfig} */
 export default {
-  client: '@hey-api/client-fetch',
   input: 'path/to/openapi.json',
   output: 'src/client',
+  plugins: ['@hey-api/client-fetch'],
 };
 ```
 
@@ -174,7 +174,7 @@ Output is the next thing to define. It can be either a string pointing to the de
 
 ### Client
 
-Clients are responsible for sending the actual HTTP requests. The `client` value is not required, but you must define it if you're generating SDKs (enabled by default).
+Clients are responsible for sending the actual HTTP requests. Using clients is not required, but you must add a client to `plugins` if you're generating SDKs (enabled by default).
 
 You can learn more on the [Clients](https://heyapi.dev/openapi-ts/clients) page.
 

docs/index.md

@@ -31,7 +31,7 @@ features:
     linkText: Learn more
   - icon: <svg class="icon-json-schema xmlns="http://www.w3.org/2000/svg" viewBox="0 0 70.423 70.423" height="24" width="24"><g fill="#fff"><path d="M122.994 114.19c-4.329-.94-7.58-3.479-8.712-6.801-.79-2.316-.677-6.072.333-11.15.485-2.439.882-5.349.882-6.467-.001-3.718-1.712-5.736-5.1-6.017l-1.955-.162v-4.785l1.852-.251c2.702-.366 3.744-1.029 4.576-2.91.611-1.38.689-2.068.505-4.472-.119-1.562-.535-4.349-.924-6.192-.99-4.683-.949-8.485.117-10.773 1.568-3.369 5.437-5.855 9.932-6.383l1.933-.227v5.036h-1.3c-1.771 0-4.25 1.262-4.883 2.488-.608 1.176-.654 2.864-.158 5.802.783 4.644 1.047 9.099.676 11.422-.425 2.658-1.975 5.796-3.68 7.448l-1.18 1.144 1.615 1.983c1.99 2.443 2.765 4.148 3.243 7.142.378 2.369.085 7.283-.67 11.214-1.054 5.485.162 7.652 4.661 8.306l1.676.244v2.448c0 2.792.171 2.697-3.439 1.913z" style="stroke-width:.35277775" transform="translate(-104.228 -45.508)"/><path d="M152.23 112.25v-2.43l2.05-.424c2.263-.467 4.054-1.863 4.459-3.475.127-.507-.113-3.164-.534-5.903-1.372-8.93-.611-13.537 2.855-17.297l1.482-1.608-1.11-1.266c-3.98-4.53-4.67-8.552-3.154-18.37.763-4.945.764-4.993.087-6.173-.797-1.388-3.284-2.776-4.975-2.776h-1.16v-2.47c0-2.81-.058-2.773 3.246-2.072 3.965.841 6.805 2.853 8.278 5.865.846 1.728.973 2.4.95 5.01-.016 1.66-.358 4.683-.762 6.72-1.499 7.564-1.365 9.576.765 11.533.99.908 1.64 1.173 3.37 1.368l2.145.243v4.848h-1.676c-2.151.001-3.932.91-4.838 2.47-.952 1.637-.893 5.206.173 10.406.907 4.422 1.053 8.459.389 10.729-.701 2.394-3.82 5.296-6.748 6.277-1.261.423-2.968.871-3.792.996l-1.5.228z" style="stroke-width:.35277778" transform="translate(-104.228 -45.508)"/><path d="M131.742 108.266c-1.021-1.299-.873-3.537.381-5.732.928-1.624 4.809-6.948 7.61-10.44l1.132-1.41-1.802-5.226c-2.022-5.86-2.01-5.974.656-6.372l1.468-.219 1.64 3.35c.903 1.843 1.77 3.351 1.928 3.351.158 0 1.775-1.755 3.594-3.9 3.16-3.727 3.357-3.892 4.426-3.694.645.12 1.218.047 1.354-.173.318-.515 1.23.247 1.23 1.027 0 .32-.453 1.134-1.009 1.81-2.267 2.755-7.104 9.27-7.104 9.57 0 .177.975 2.454 2.167 5.059l2.166 4.736-.658.985c-.362.541-.662 1.126-.667 1.299-.005.173-.278.483-.606.69-.832.525-1.447-.115-3.99-4.153-1.164-1.848-2.231-3.365-2.372-3.37-.313-.01-3.79 5.133-6.48 9.581-2.37 3.924-1.938 3.42-3.265 3.801-.956.274-1.194.199-1.799-.57zM131.986 83.677c-2.152-3.847-6.019-9.428-7.579-10.938-.792-.767-1.44-1.575-1.44-1.796 0-.601 1.616-1.22 3.19-1.22 1.698 0 3.496 1.479 5.1 4.193.582.985 1.156 1.794 1.276 1.798.12.004.809-1.651 1.53-3.678 1.547-4.34 5.624-12.778 7.225-14.951 1.373-1.863 3.43-2.865 5.903-2.876 3.234-.013 3.243.13.205 3.297-4.636 4.832-6.764 8.81-11.252 21.037-1.246 3.396-2.39 6.48-2.542 6.852-.23.566-.498.281-1.616-1.718z" style="stroke-width:.35277775" transform="translate(-104.228 -45.508)"/></g></svg>
     title: Data Fetching
-    details: Type-safe data with our REST clients. Fetch, Axios, Angular, Node, and XHR are available.
+    details: Type-safe data with our REST clients. Fetch, Axios, Nuxt, Angular, and Node are available.
     link: /openapi-ts/clients
     linkText: See all clients
   - icon: <svg width="24" height="24" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 190 190"><g fill="none" fill-rule="evenodd"><path d="M150.276 61.344c3.093-14.981 3.756-26.471 1.757-34.815-1.189-4.962-3.362-9.01-6.668-11.93-3.49-3.084-7.901-4.597-12.858-4.597-8.178 0-16.775 3.725-25.963 10.802-3.747 2.887-7.636 6.366-11.676 10.44a8.743 8.743 0 0 0-1.09-1.163C82.36 19.915 72.746 13.599 64.523 11.164c-4.89-1.448-9.48-1.586-13.66-.181-4.414 1.483-7.93 4.55-10.41 8.845-4.094 7.089-5.174 16.403-3.648 27.904.623 4.688 1.686 9.794 3.189 15.327a8.725 8.725 0 0 0-1.698.38c-14.489 4.797-24.749 9.955-30.96 15.85-3.696 3.506-6.109 7.41-6.981 11.733-.921 4.562-.023 9.137 2.454 13.43 4.087 7.078 11.6 12.66 22.304 17.082 4.298 1.776 9.161 3.384 14.595 4.83a8.735 8.735 0 0 0-.57 1.776c-3.092 14.98-3.756 26.47-1.756 34.814 1.188 4.962 3.362 9.01 6.667 11.93 3.49 3.084 7.902 4.597 12.86 4.597 8.177 0 16.774-3.725 25.962-10.802 3.787-2.917 7.72-6.44 11.805-10.57.42.656.936 1.267 1.546 1.81 11.42 10.166 21.034 16.482 29.257 18.917 4.89 1.448 9.48 1.586 13.66.181 4.414-1.483 7.93-4.55 10.41-8.845 4.094-7.089 5.174-16.403 3.648-27.904-.645-4.857-1.764-10.164-3.354-15.929a8.715 8.715 0 0 0 1.863-.398c14.489-4.797 24.749-9.955 30.96-15.85 3.696-3.506 6.109-7.41 6.981-11.733.921-4.562.023-9.137-2.454-13.43-4.087-7.078-11.6-12.66-22.304-17.082-4.427-1.828-9.452-3.48-15.082-4.959.2-.49.36-1.006.47-1.543Z" fill="#002C4B" fill-rule="nonzero"/><path d="M80.397 64h29.211a5 5 0 0 1 4.337 2.512l14.632 25.5a5 5 0 0 1 0 4.976l-14.632 25.5a5 5 0 0 1-4.337 2.512H80.397a5 5 0 0 1-4.337-2.512l-14.632-25.5a5 5 0 0 1 0-4.976l14.632-25.5A5 5 0 0 1 80.397 64Zm25.59 6.277a5 5 0 0 1 4.339 2.513l11.017 19.224a5 5 0 0 1 0 4.972l-11.017 19.224a5 5 0 0 1-4.338 2.513h-21.97a5 5 0 0 1-4.339-2.513L68.662 96.986a5 5 0 0 1 0-4.972L79.679 72.79a5 5 0 0 1 4.338-2.513h21.97Zm-3.906 6.864H87.924a5 5 0 0 0-4.335 2.51l-7.1 12.358a5 5 0 0 0 0 4.982l7.1 12.358a5 5 0 0 0 4.335 2.51h14.157a5 5 0 0 0 4.335-2.51l7.1-12.358a5 5 0 0 0 0-4.982l-7.1-12.358a5 5 0 0 0-4.335-2.51Zm-3.762 6.571a5 5 0 0 1 4.334 2.506l3.33 5.788a5 5 0 0 1 0 4.988l-3.33 5.788a5 5 0 0 1-4.334 2.506h-6.633a5 5 0 0 1-4.334-2.506l-3.33-5.788a5 5 0 0 1 0-4.988l3.33-5.788a5 5 0 0 1 4.334-2.506h6.633Zm-3.315 6.473a4.313 4.313 0 1 0-.003 8.63 4.313 4.313 0 1 0 .003-8.63ZM60 94.5h7.768" fill="#FFD94C"/><path d="M54.86 108.358a2.713 2.713 0 0 1 3.718 1.041l.475.845a269.421 269.421 0 0 0 11.888 19.191c4.867 7.15 10.34 14.39 16.421 21.716a2.776 2.776 0 0 1-.296 3.847l-.612.537c-20.107 17.568-33.176 21.078-39.206 10.527-5.898-10.32-3.764-29.08 6.403-56.28a2.748 2.748 0 0 1 1.21-1.424Zm85.674 20.684a2.708 2.708 0 0 1 3.126 2.152l.153.792c4.97 26.01 1.47 39.014-10.497 39.014-11.706 0-26.607-11.091-44.703-33.273a2.725 2.725 0 0 1-.613-1.745 2.712 2.712 0 0 1 2.73-2.694l.955.007c7.62.041 15.03-.223 22.226-.794 8.498-.673 17.373-1.826 26.623-3.46Zm6.875-55.23c.523-1.41 2.1-2.149 3.546-1.663l.788.266c25.84 8.803 35.66 18.477 29.455 29.022-6.068 10.314-23.714 17.823-52.936 22.527a2.852 2.852 0 0 1-1.88-.345 2.726 2.726 0 0 1-.993-3.772l.5-.837c3.988-6.694 7.592-13.356 10.813-19.986 3.803-7.83 7.372-16.233 10.707-25.212Zm-85.67-7.776a2.852 2.852 0 0 1 1.878.345 2.726 2.726 0 0 1 .994 3.772l-.5.837c-3.988 6.694-7.592 13.356-10.813 19.986-3.803 7.83-7.372 16.233-10.707 25.212-.523 1.41-2.1 2.149-3.546 1.663l-.788-.266c-25.84-8.803-35.66-18.477-29.455-29.022C14.87 78.25 32.516 70.74 61.738 66.036Zm41.807-31.57c20.107-17.57 33.176-21.079 39.206-10.528 5.898 10.32 3.764 29.08-6.403 56.28a2.748 2.748 0 0 1-1.21 1.424 2.713 2.713 0 0 1-3.717-1.041l-.475-.845a269.421 269.421 0 0 0-11.888-19.191c-4.867-7.15-10.34-14.39-16.421-21.716a2.776 2.776 0 0 1 .296-3.847ZM57.684 18c11.706 0 26.607 11.091 44.703 33.273.402.492.618 1.11.613 1.745a2.712 2.712 0 0 1-2.73 2.694l-.955-.007c-7.62-.041-15.03.223-22.226.794-8.498.673-17.373 1.826-26.623 3.46a2.708 2.708 0 0 1-3.126-2.153l-.153-.792C42.217 31.004 45.717 18 57.684 18Z" fill="#FF4154"/></g></svg>

docs/openapi-ts/clients/axios.md

@@ -43,85 +43,84 @@ bun add @hey-api/client-axios
 
 :::
 
-In your [configuration](/openapi-ts/get-started), set `client` to `@hey-api/client-axios` and you'll be ready to use the Axios client. :tada:
+In your [configuration](/openapi-ts/get-started), add `@hey-api/client-axios` to your plugins and you'll be ready to generate client artifacts. :tada:
 
 ::: code-group
 
 ```js [config]
 export default {
-  client: '@hey-api/client-axios', // [!code ++]
   input: 'path/to/openapi.json',
   output: 'src/client',
+  plugins: ['@hey-api/client-axios'], // [!code ++]
 };
 ```
 
 ```sh [cli]
 npx @hey-api/openapi-ts \
-  -c @hey-api/client-axios \  # [!code ++]
   -i path/to/openapi.json \
-  -o src/client
+  -o src/client \
+  -c @hey-api/client-axios # [!code ++]
 ```
 
 :::
 
 ## Configuration
 
-If you're using SDKs, you will want to configure the internal client instance. You can do that with the `setConfig()` method. Call it at the beginning of your application.
+The Axios client is built as a thin wrapper on top of Axios, extending its functionality to work with Hey API. If you're already familiar with Axios, configuring your client will feel like working directly with Axios.
 
-```js
-import { client } from 'client/sdk.gen';
+When we installed the client above, it created a [`client.gen.ts`](/openapi-ts/output#client) file. You will most likely want to configure the exported `client` instance. There are two ways to do that.
 
-client.setConfig({
-  baseURL: 'https://example.com',
-});
-```
+### `setConfig()`
 
-If you aren't using SDKs, you can create your own client instance.
+This is the simpler approach. You can call the `setConfig()` method at the beginning of your application or anytime you need to update the client configuration. You can pass any Axios configuration option to `setConfig()` (except for `auth`), and even your own Axios implementation.
 
 ```js
-import { createClient } from '@hey-api/client-axios';
+import { client } from 'client/client.gen';
 
-const client = createClient({
+client.setConfig({
   baseURL: 'https://example.com',
 });
 ```
 
-## Interceptors
+The disadvantage of this approach is that your code may call the `client` instance before it's configured for the first time. Depending on your use case, you might need to use the second approach.
 
-Interceptors (middleware) can be used to modify requests before they're sent or responses before they're returned to your application. Axios provides interceptors, please refer to their documentation on [interceptors](https://axios-http.com/docs/interceptors).
+### Runtime API
 
-We expose the Axios instance through the `instance` field.
+Since `client.gen.ts` is a generated file, we can't directly modify it. Instead, we can tell our configuration to use a custom file implementing the Runtime API. We do that by specifying the `runtimeConfigPath` option.
 
 ```js
-import { client } from 'client/sdk.gen';
-
-client.instance.interceptors.request.use((config) => {
-  // do something
-  return config;
-});
+export default {
+  input: 'path/to/openapi.json',
+  output: 'src/client',
+  plugins: [
+    {
+      name: '@hey-api/client-axios',
+      runtimeConfigPath: './src/hey-api.ts', // [!code ++]
+    },
+  ],
+};
 ```
 
-## Customization
-
-The Axios client is built as a thin wrapper on top of Axios, extending its functionality to work with Hey API. If you're already familiar with Axios, customizing your client will feel like working directly with Axios. You can customize requests in three ways – through SDKs, per client, or per request.
-
-### SDKs
+In our custom file, we need to export a `createClientConfig()` method. This function is a simple wrapper allowing us to override configuration values.
 
-This is the most common requirement. The generated SDKs consume an internal client instance, so you will want to configure that.
+::: code-group
 
-```js
-import { client } from 'client/sdk.gen';
+```ts [hey-api.ts]
+import type { CreateClientConfig } from '@hey-api/client-axios';
 
-client.setConfig({
+export const createClientConfig: CreateClientConfig = (config) => ({
+  ...config,
   baseURL: 'https://example.com',
 });
 ```
 
-You can pass any Axios configuration option to `setConfig()` (except for `auth`), and even your own Axios implementation.
+:::
+
+With this approach, `client.gen.ts` will call `createClientConfig()` before initializing the `client` instance. If needed, you can still use `setConfig()` to update the client configuration later.
 
-### Client
+### `createClient()`
 
-If you need to create a client pointing to a different domain, you can create your own client instance.
+You can also create your own client instance. You can use it to manually send requests or point it to a different domain.
 
 ```js
 import { createClient } from '@hey-api/client-axios';
@@ -131,21 +130,36 @@ const myClient = createClient({
 });
 ```
 
-You can then pass this instance to any SDK function through the `client` option. This will override the internal instance.
+You can also pass this instance to any SDK function through the `client` option. This will override the default instance from `client.gen.ts`.
 
 ```js
 const response = await getFoo({
   client: myClient,
 });
 ```
 
-### Request
+### SDKs
 
-Alternatively, you can pass the Axios configuration options to each SDK function. This is useful if you don't want to create a client instance for one-off use cases.
+Alternatively, you can pass the client configuration options to each SDK function. This is useful if you don't want to create a client instance for one-off use cases.
 
 ```js
 const response = await getFoo({
-  baseURL: 'https://example.com', // <-- override internal configuration
+  baseURL: 'https://example.com', // <-- override default configuration
+});
+```
+
+## Interceptors
+
+Interceptors (middleware) can be used to modify requests before they're sent or responses before they're returned to your application. Axios provides interceptors, please refer to their documentation on [interceptors](https://axios-http.com/docs/interceptors).
+
+We expose the Axios instance through the `instance` field.
+
+```js
+import { client } from 'client/client.gen';
+
+client.instance.interceptors.request.use((config) => {
+  // do something
+  return config;
 });
 ```
 
@@ -154,7 +168,7 @@ const response = await getFoo({
 The SDKs include auth mechanisms for every endpoint. You will want to configure the `auth` field to pass the right token for each request. The `auth` field can be a string or a function returning a string representing the token. The returned value will be attached only to requests that require auth.
 
 ```js
-import { client } from 'client/sdk.gen';
+import { client } from 'client/client.gen';
 
 client.setConfig({
   auth: () => '<my_token>', // [!code ++]
@@ -165,7 +179,7 @@ client.setConfig({
 If you're not using SDKs or generating auth, using interceptors is a common approach to configuring auth for each request.
 
 ```js
-import { client } from 'client/sdk.gen';
+import { client } from 'client/client.gen';
 
 client.instance.interceptors.request.use((config) => {
   config.headers.set('Authorization', 'Bearer <my_token>'); // [!code ++]
@@ -206,12 +220,14 @@ Sometimes, you may not want to declare client packages as a dependency. This sce
 
 ```js
 export default {
-  client: {
-    bundle: true, // [!code ++]
-    name: '@hey-api/client-axios',
-  },
   input: 'path/to/openapi.json',
   output: 'src/client',
+  plugins: [
+    {
+      bundle: true, // [!code ++]
+      name: '@hey-api/client-axios',
+    },
+  ],
 };
 ```