You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/openapi-ts/clients/next-js.md
+256-2Lines changed: 256 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,12 +3,266 @@ title: Next.js client
3
3
description: Next.js client for Hey API. Compatible with all our features.
4
4
---
5
5
6
-
# Next.js <spandata-soon>soon</span>
6
+
# Next.js
7
7
8
8
::: warning
9
-
This feature isn't in development yet. Help us prioritize it by voting on [GitHub](https://github.com/hey-api/openapi-ts/issues/1515).
9
+
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).
10
10
:::
11
11
12
12
[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.
Start by adding `@hey-api/client-next` to your dependencies.
21
+
22
+
::: code-group
23
+
24
+
```sh [npm]
25
+
npm install @hey-api/client-next
26
+
```
27
+
28
+
```sh [pnpm]
29
+
pnpm add @hey-api/client-next
30
+
```
31
+
32
+
```sh [yarn]
33
+
yarn add @hey-api/client-next
34
+
```
35
+
36
+
```sh [bun]
37
+
bun add @hey-api/client-next
38
+
```
39
+
40
+
:::
41
+
42
+
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:
43
+
44
+
::: code-group
45
+
46
+
```js [config]
47
+
exportdefault {
48
+
input:'path/to/openapi.json',
49
+
output:'src/client',
50
+
plugins: ['@hey-api/client-next'], // [!code ++]
51
+
};
52
+
```
53
+
54
+
```sh [cli]
55
+
npx @hey-api/openapi-ts \
56
+
-i path/to/openapi.json \
57
+
-o src/client \
58
+
-c @hey-api/client-next # [!code ++]
59
+
```
60
+
61
+
:::
62
+
63
+
## Configuration
64
+
65
+
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.
66
+
67
+
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.
68
+
69
+
### `setConfig()`
70
+
71
+
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.
72
+
73
+
```js
74
+
import { client } from'client/client.gen';
75
+
76
+
client.setConfig({
77
+
baseUrl:'https://example.com',
78
+
});
79
+
```
80
+
81
+
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.
82
+
83
+
### Runtime API
84
+
85
+
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.
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.
116
+
117
+
### `createClient()`
118
+
119
+
You can also create your own client instance. You can use it to manually send requests or point it to a different domain.
You can also pass this instance to any SDK function through the `client` option. This will override the default instance from `client.gen.ts`.
130
+
131
+
```js
132
+
constresponse=awaitgetFoo({
133
+
client: myClient,
134
+
});
135
+
```
136
+
137
+
### SDKs
138
+
139
+
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.
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
To eject, you must provide a reference to the function that was passed to `use()`.
198
+
:::
199
+
200
+
## Auth
201
+
202
+
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.
203
+
204
+
```js
205
+
import { client } from'client/client.gen';
206
+
207
+
client.setConfig({
208
+
auth: () =>'<my_token>', // [!code ++]
209
+
baseUrl:'https://example.com',
210
+
});
211
+
```
212
+
213
+
If you're not using SDKs or generating auth, using interceptors is a common approach to configuring auth for each request.
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.
226
+
227
+
```ts
228
+
typeFooData= {
229
+
path: {
230
+
fooId:number;
231
+
};
232
+
query?: {
233
+
bar?:string;
234
+
};
235
+
url:'/foo/{fooId}';
236
+
};
237
+
238
+
const url =client.buildUrl<FooData>({
239
+
path: {
240
+
fooId: 1,
241
+
},
242
+
query: {
243
+
bar: 'baz',
244
+
},
245
+
url: '/foo/{fooId}',
246
+
});
247
+
console.log(url); // prints '/foo/1?bar=baz'
248
+
```
249
+
250
+
## Bundling
251
+
252
+
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.
0 commit comments