···33description: Next.js client for Hey API. Compatible with all our features.
44---
5566-# Next.js <span data-soon>soon</span>
66+# Next.js
7788::: warning
99-This feature isn't in development yet. Help us prioritize it by voting on [GitHub](https://github.com/hey-api/openapi-ts/issues/1515).
99+Next.js client is currently in beta. The interface might change before it becomes stable. We encourage you to leave feedback on [GitHub](https://github.com/hey-api/openapi-ts/issues).
1010:::
11111212[Next.js](https://nextjs.org/) is the React framework for the web. Used by some of the world's largest companies, Next.js enables you to create high-quality web applications with the power of React components.
13131414+<!-- <button class="buttonLink" @click="(event) => embedProject('hey-api-client-next-example')(event)">
1515+Live demo
1616+</button> -->
1717+1818+## Installation
1919+2020+Start by adding `@hey-api/client-next` to your dependencies.
2121+2222+::: code-group
2323+2424+```sh [npm]
2525+npm install @hey-api/client-next
2626+```
2727+2828+```sh [pnpm]
2929+pnpm add @hey-api/client-next
3030+```
3131+3232+```sh [yarn]
3333+yarn add @hey-api/client-next
3434+```
3535+3636+```sh [bun]
3737+bun add @hey-api/client-next
3838+```
3939+4040+:::
4141+4242+In your [configuration](/openapi-ts/get-started), add `@hey-api/client-next` to your plugins and you'll be ready to generate client artifacts. :tada:
4343+4444+::: code-group
4545+4646+```js [config]
4747+export default {
4848+ input: 'path/to/openapi.json',
4949+ output: 'src/client',
5050+ plugins: ['@hey-api/client-next'], // [!code ++]
5151+};
5252+```
5353+5454+```sh [cli]
5555+npx @hey-api/openapi-ts \
5656+ -i path/to/openapi.json \
5757+ -o src/client \
5858+ -c @hey-api/client-next # [!code ++]
5959+```
6060+6161+:::
6262+6363+## Configuration
6464+6565+The Next.js client is built as a thin wrapper on top of [fetch](https://nextjs.org/docs/app/api-reference/functions/fetch), extending its functionality to work with Hey API. If you're already familiar with Fetch, configuring your client will feel like working directly with Fetch API.
6666+6767+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.
6868+6969+### `setConfig()`
7070+7171+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 Fetch API configuration option to `setConfig()`, and even your own Fetch implementation.
7272+7373+```js
7474+import { client } from 'client/client.gen';
7575+7676+client.setConfig({
7777+ baseUrl: 'https://example.com',
7878+});
7979+```
8080+8181+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.
8282+8383+### Runtime API
8484+8585+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.
8686+8787+```js
8888+export default {
8989+ input: 'path/to/openapi.json',
9090+ output: 'src/client',
9191+ plugins: [
9292+ {
9393+ name: '@hey-api/client-next',
9494+ runtimeConfigPath: './src/hey-api.ts', // [!code ++]
9595+ },
9696+ ],
9797+};
9898+```
9999+100100+In our custom file, we need to export a `createClientConfig()` method. This function is a simple wrapper allowing us to override configuration values.
101101+102102+::: code-group
103103+104104+```ts [hey-api.ts]
105105+import type { CreateClientConfig } from '@hey-api/client-next';
106106+107107+export const createClientConfig: CreateClientConfig = (config) => ({
108108+ ...config,
109109+ baseUrl: 'https://example.com',
110110+});
111111+```
112112+113113+:::
114114+115115+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.
116116+117117+### `createClient()`
118118+119119+You can also create your own client instance. You can use it to manually send requests or point it to a different domain.
120120+121121+```js
122122+import { createClient } from '@hey-api/client-next';
123123+124124+const myClient = createClient({
125125+ baseUrl: 'https://example.com',
126126+});
127127+```
128128+129129+You can also pass this instance to any SDK function through the `client` option. This will override the default instance from `client.gen.ts`.
130130+131131+```js
132132+const response = await getFoo({
133133+ client: myClient,
134134+});
135135+```
136136+137137+### SDKs
138138+139139+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.
140140+141141+```js
142142+const response = await getFoo({
143143+ baseUrl: 'https://example.com', // <-- override default configuration
144144+});
145145+```
146146+147147+## Interceptors
148148+149149+Interceptors (middleware) can be used to modify requests before they're sent or responses before they're returned to your application. They can be added with `use` and removed with `eject`. Fetch API does not have the interceptor functionality, so we implement our own. Below is an example request interceptor
150150+151151+::: code-group
152152+153153+```js [use]
154154+import { client } from 'client/client.gen';
155155+156156+// Supports async functions
157157+client.interceptors.request.use(async (options) => {
158158+ // do something
159159+});
160160+```
161161+162162+```js [eject]
163163+import { client } from 'client/client.gen';
164164+165165+client.interceptors.request.eject((options) => {
166166+ // do something
167167+});
168168+```
169169+170170+:::
171171+172172+and an example response interceptor
173173+174174+::: code-group
175175+176176+```js [use]
177177+import { client } from 'client/client.gen';
178178+179179+client.interceptors.response.use((response) => {
180180+ // do something
181181+ return response;
182182+});
183183+```
184184+185185+```js [eject]
186186+import { client } from 'client/client.gen';
187187+188188+client.interceptors.response.eject((response) => {
189189+ // do something
190190+ return response;
191191+});
192192+```
193193+194194+:::
195195+196196+::: tip
197197+To eject, you must provide a reference to the function that was passed to `use()`.
198198+:::
199199+200200+## Auth
201201+202202+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.
203203+204204+```js
205205+import { client } from 'client/client.gen';
206206+207207+client.setConfig({
208208+ auth: () => '<my_token>', // [!code ++]
209209+ baseUrl: 'https://example.com',
210210+});
211211+```
212212+213213+If you're not using SDKs or generating auth, using interceptors is a common approach to configuring auth for each request.
214214+215215+```js
216216+import { client } from 'client/client.gen';
217217+218218+client.interceptors.request.use((options) => {
219219+ options.headers.set('Authorization', 'Bearer <my_token>'); // [!code ++]
220220+});
221221+```
222222+223223+## Build URL
224224+225225+If you need to access the compiled URL, you can use the `buildUrl()` method. It's loosely typed by default to accept almost any value; in practice, you will want to pass a type hint.
226226+227227+```ts
228228+type FooData = {
229229+ path: {
230230+ fooId: number;
231231+ };
232232+ query?: {
233233+ bar?: string;
234234+ };
235235+ url: '/foo/{fooId}';
236236+};
237237+238238+const url = client.buildUrl<FooData>({
239239+ path: {
240240+ fooId: 1,
241241+ },
242242+ query: {
243243+ bar: 'baz',
244244+ },
245245+ url: '/foo/{fooId}',
246246+});
247247+console.log(url); // prints '/foo/1?bar=baz'
248248+```
249249+250250+## Bundling
251251+252252+Sometimes, you may not want to declare client packages as a dependency. This scenario is common if you're using Hey API to generate output that is repackaged and published for other consumers under your own brand. For such cases, our clients support bundling through the `client.bundle` configuration option.
253253+254254+```js
255255+export default {
256256+ input: 'path/to/openapi.json',
257257+ output: 'src/client',
258258+ plugins: [
259259+ {
260260+ bundle: true, // [!code ++]
261261+ name: '@hey-api/client-next',
262262+ },
263263+ ],
264264+};
265265+```
266266+267267+<!--@include: ../../examples.md-->
14268<!--@include: ../../sponsors.md-->
+4
docs/openapi-ts/clients/nuxt.md
···11111212[Nuxt](https://nuxt.com/) is an open source framework that makes web development intuitive and powerful.
13131414+<!-- <button class="buttonLink" @click="(event) => embedProject('hey-api-client-fetch-example')(event)">
1515+Live demo
1616+</button> -->
1717+1418## Installation
15191620Start by adding `@hey-api/client-nuxt` to your dependencies.
···11// This file is auto-generated by @hey-api/openapi-ts
2233-import { createClient, createConfig } from '@hey-api/client-fetch';
33+import { createClient, createConfig } from '@hey-api/client-next';
4455import { createClientConfig } from '../hey-api';
66
···11// This file is auto-generated by @hey-api/openapi-ts
2233-import type { Options } from '@hey-api/client-fetch';
33+import type { Options } from '@hey-api/client-next';
4455import { client as _heyApiClient } from './client.gen';
66import type {
···11+MIT License
22+33+Copyright (c) Hey API
44+55+Permission is hereby granted, free of charge, to any person obtaining a copy
66+of this software and associated documentation files (the "Software"), to deal
77+in the Software without restriction, including without limitation the rights
88+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
99+copies of the Software, and to permit persons to whom the Software is
1010+furnished to do so, subject to the following conditions:
1111+1212+The above copyright notice and this permission notice shall be included in all
1313+copies or substantial portions of the Software.
1414+1515+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
1616+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
1717+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
1818+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
1919+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
2020+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
2121+SOFTWARE.
+40
packages/client-next/README.md
···11+<div align="center">
22+ <img alt="Hey API logo" height="150" src="https://heyapi.dev/images/logo-300w.png" width="150">
33+ <h1 align="center"><b>Next.js Client</b></h1>
44+ <p align="center">🚀 Next.js client for `@hey-api/openapi-ts` codegen.</p>
55+</div>
66+77+<!-- TODO: Add working Next.js example -->
88+<!-- [Live demo](https://stackblitz.com/edit/hey-api-client-fetch-example?file=openapi-ts.config.ts,src%2Fclient%2Fschemas.gen.ts,src%2Fclient%2Fsdk.gen.ts,src%2Fclient%2Ftypes.gen.ts,src%2FApp.tsx) -->
99+1010+## Features
1111+1212+- seamless integration with `@hey-api/openapi-ts` ecosystem
1313+- type-safe response data and errors
1414+- response data validation and transformation
1515+- access to the original request and response
1616+- granular request and response customization options
1717+- minimal learning curve thanks to extending the underlying technology
1818+- support bundling inside the generated output
1919+2020+## Documentation
2121+2222+Please visit our [website](https://heyapi.dev/) for documentation, guides, migrating, and more.
2323+2424+## Sponsors
2525+2626+Love Hey API? Become our [sponsor](https://github.com/sponsors/hey-api).
2727+2828+<p>
2929+ <a href="https://kutt.it/pkEZyc" target="_blank">
3030+ <img alt="Stainless logo" height="50" src="https://heyapi.dev/images/stainless-logo-wordmark-480w.jpeg" />
3131+ </a>
3232+</p>
3333+3434+## GitHub Integration (coming soon)
3535+3636+Automatically update your code when the APIs it depends on change. [Find out more](https://heyapi.dev/openapi-ts/integrations.html).
3737+3838+## Migration Guides
3939+4040+[OpenAPI Typescript Codegen](https://heyapi.dev/openapi-ts/migrating.html#openapi-typescript-codegen)
···44 <p align="center">🚀 Nuxt client for `@hey-api/openapi-ts` codegen.</p>
55</div>
6677-[Live demo](https://stackblitz.com/edit/hey-api-client-nuxt-example?file=openapi-ts.config.ts,src%2Fclient%2Fschemas.gen.ts,src%2Fclient%2Fsdk.gen.ts,src%2Fclient%2Ftypes.gen.ts,src%2Fcomponents%home.vue)
77+<!-- TODO: add working example once StackBlitz updates their Node version -->
88+<!-- [Live demo](https://stackblitz.com/edit/hey-api-client-nuxt-example?file=openapi-ts.config.ts,src%2Fclient%2Fschemas.gen.ts,src%2Fclient%2Fsdk.gen.ts,src%2Fclient%2Ftypes.gen.ts,src%2Fcomponents%home.vue) -->
89910## Features
1011