Skip to content

Commit 1497aaf

Browse files
RihanArfanRihanArfan
committed
docs: improve nuxt docs
1 parent 1358ac5 commit 1497aaf

File tree

1 file changed

+144
-36
lines changed

1 file changed

+144
-36
lines changed

‎docs/openapi-ts/clients/nuxt.md‎

Lines changed: 144 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
2-
title: Nuxt v3 Client
3-
description: Generate a type-safe Nuxt v3 client from OpenAPI with the Nuxt client for openapi-ts. Fully compatible with validators, transformers, and all core features.
2+
title: Nuxt Client
3+
description: Generate a type-safe Nuxt client from OpenAPI with the Nuxt client for openapi-ts. Fully compatible with validators, transformers, and all core features.
44
---
55

66
<script setup lang="ts">
@@ -9,8 +9,7 @@ import VersionLabel from '@components/VersionLabel.vue';
99
</script>
1010

1111
<Heading>
12-
<h1>Nuxt<span class="sr-only"> v3</span></h1>
13-
<VersionLabel value="v3" />
12+
<h1>Nuxt</h1>
1413
</Heading>
1514

1615
::: warning
@@ -25,7 +24,6 @@ The Nuxt client for Hey API generates a type-safe client from your OpenAPI spec,
2524

2625
## Features
2726

28-
- Nuxt v3 support
2927
- seamless integration with `@hey-api/openapi-ts` ecosystem
3028
- type-safe response data and errors
3129
- response data validation and transformation
@@ -36,7 +34,33 @@ The Nuxt client for Hey API generates a type-safe client from your OpenAPI spec,
3634

3735
## Installation
3836

39-
Start by adding `@hey-api/nuxt` to your dependencies.
37+
### Automatic installation
38+
39+
Start by installing the `@hey-api/nuxt` Nuxt module.
40+
41+
::: code-group
42+
43+
```sh [npm]
44+
npx nuxi module add @hey-api/nuxt
45+
```
46+
47+
```sh [pnpm]
48+
pnpx nuxi module add @hey-api/nuxt
49+
```
50+
51+
```sh [yarn]
52+
yarn dlx nuxi module @hey-api/nuxt
53+
```
54+
55+
```sh [bun]
56+
bunx nuxi module add @hey-api/nuxt
57+
```
58+
59+
:::
60+
61+
### Manual installation
62+
63+
Add `@hey-api/nuxt` to your dependencies.
4064

4165
::: code-group
4266

@@ -58,76 +82,135 @@ bun add @hey-api/nuxt
5882

5983
:::
6084

61-
In your [configuration](/openapi-ts/get-started), add `@hey-api/client-nuxt` to your plugins and you'll be ready to generate client artifacts. :tada:
62-
63-
::: code-group
85+
Then, add it to the `modules` in your `nuxt.config.ts`:
6486

65-
```js [config]
66-
export default {
67-
input: 'hey-api/backend', // sign up at app.heyapi.dev
68-
output: 'src/client',
69-
plugins: ['@hey-api/client-nuxt'], // [!code ++]
70-
};
87+
```ts
88+
export default defineNuxtConfig({
89+
modules: [
90+
'@hey-api/nuxt', // [!code ++]
91+
],
92+
});
7193
```
7294

73-
```sh [cli]
74-
npx @hey-api/openapi-ts \
75-
-i hey-api/backend \
76-
-o src/client \
77-
-c @hey-api/client-nuxt # [!code ++]
95+
## Getting started
96+
97+
Set an [input](/openapi-ts/configuration/input) within `nuxt.config.ts`, then start the Nuxt dev server.
98+
99+
```ts
100+
export default defineNuxtConfig({
101+
heyApi: {
102+
config: {
103+
input: './path/to/openapi.json', // [!code ++]
104+
},
105+
},
106+
});
78107
```
79108

80-
:::
109+
The generated client can be accessed from `#hey-api/`.
110+
111+
```ts
112+
import { client } from '#hey-api/client.gen';
113+
```
81114

82115
::: tip
83116

84-
If you add `@hey-api/nuxt` to your Nuxt modules, this step is not needed.
117+
The `@hey-api/client-nuxt` plugin is automatically added.
85118

86119
:::
87120

121+
### Options
122+
123+
### `alias`
124+
125+
Configure an [alias](https://nuxt.com/docs/api/nuxt-config#alias) to access the Hey API client.
126+
127+
Defaults to `#hey-api`
128+
129+
### `autoImports`
130+
131+
Adds the generated SDK items to auto imports. Defaults to `true`.
132+
133+
#### `config`
134+
135+
Configuration to pass to `@hey-api/openapi-ts`.
136+
137+
- [input](/openapi-ts/configuration/input)
138+
- [output](/openapi-ts/configuration/output)
139+
- Defaults to `.nuxt/client`
140+
- [parser](/openapi-ts/configuration/parser)
141+
- [plugins](/openapi-ts/transformers)
142+
88143
## Configuration
89144

90-
The Nuxt client is built as a thin wrapper on top of Nuxt, extending its functionality to work with Hey API. If you're already familiar with Nuxt, configuring your client will feel like working directly with Nuxt.
145+
When we configured the Nuxt module 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.
91146

92-
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.
147+
The Nuxt client is built as a thin wrapper on top of Nuxt, extending its functionality to work with Hey API. If you're already familiar with Nuxt, configuring your client will feel like working directly with Nuxt.
93148

94149
### `setConfig()`
95150

96151
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 Nuxt configuration option to `setConfig()`, and even your own [`$fetch`](#custom-fetch) implementation.
97152

98-
```js
99-
import { client } from 'client/client.gen';
153+
::: code-group
100154

101-
client.setConfig({
102-
baseURL: 'https://example.com',
155+
```vue [app.vue]
156+
<script setup lang="ts">
157+
import { client } from '#hey-api/client.gen';
158+
159+
await callOnce(async () => {
160+
client.setConfig({
161+
baseURL: 'https://example.com',
162+
});
103163
});
164+
</script>
104165
```
105166

167+
:::
168+
106169
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.
107170

108171
### Runtime API
109172

110173
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.
111174

112-
```js
175+
::: code-group
176+
177+
```ts [nuxt]
178+
export default defineNuxtConfig({
179+
heyApi: {
180+
config: {
181+
input: 'hey-api/backend', // sign up at app.heyapi.dev
182+
plugins: [
183+
{
184+
name: '@hey-api/client-nuxt',
185+
runtimeConfigPath: './shared/lib/hey-api.ts', // [!code ++]
186+
},
187+
],
188+
},
189+
},
190+
});
191+
```
192+
193+
```js [standalone]
113194
export default {
114195
input: 'hey-api/backend', // sign up at app.heyapi.dev
115196
output: 'src/client',
116197
plugins: [
117198
{
118199
name: '@hey-api/client-nuxt',
119-
runtimeConfigPath: './src/hey-api.ts', // [!code ++]
200+
runtimeConfigPath: './shared/lib/hey-api.ts', // [!code ++]
120201
},
121202
],
122203
};
123204
```
124205

206+
:::
207+
125208
In our custom file, we need to export a `createClientConfig()` method. This function is a simple wrapper allowing us to override configuration values.
126209

127210
::: code-group
128211

129212
```ts [hey-api.ts]
130-
import type { CreateClientConfig } from './client/client.gen';
213+
import type { CreateClientConfig } from '#hey-api/client.gen';
131214

132215
export const createClientConfig: CreateClientConfig = (config) => ({
133216
...config,
@@ -144,7 +227,7 @@ With this approach, `client.gen.ts` will call `createClientConfig()` before init
144227
You can also create your own client instance. You can use it to manually send requests or point it to a different domain.
145228

146229
```js
147-
import { createClient } from './client/client';
230+
import { createClient } from '#hey-api/client';
148231

149232
const myClient = createClient({
150233
baseURL: 'https://example.com',
@@ -180,7 +263,7 @@ If you omit `composable`, `$fetch` is used by default.
180263
:::
181264

182265
```js
183-
import { client } from 'client/client.gen';
266+
import { client } from '#hey-api/client.gen';
184267

185268
const result = await client.get({
186269
composable: '$fetch',
@@ -196,7 +279,7 @@ const result = await client.get({
196279
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.
197280

198281
```js
199-
import { client } from 'client/client.gen';
282+
import { client } from '#hey-api/client.gen';
200283

201284
client.setConfig({
202285
auth: () => '<my_token>', // [!code ++]
@@ -207,7 +290,7 @@ client.setConfig({
207290
If you're not using SDKs or generating auth, using interceptors is a common approach to configuring auth for each request.
208291

209292
```js
210-
import { client } from 'client/client.gen';
293+
import { client } from '#hey-api/client.gen';
211294

212295
client.setConfig({
213296
onRequest: ({ options }) => {
@@ -248,7 +331,7 @@ console.log(url); // prints '/foo/1?bar=baz'
248331
You can implement your own `$fetch` method. This is useful if you need to extend the default `$fetch` method with extra functionality, or replace it altogether.
249332

250333
```js
251-
import { client } from 'client/client.gen';
334+
import { client } from '#hey-api/client.gen';
252335

253336
client.setConfig({
254337
$fetch: () => {
@@ -259,6 +342,31 @@ client.setConfig({
259342

260343
You can use any of the approaches mentioned in [Configuration](#configuration), depending on how granular you want your custom method to be.
261344

345+
## Standalone usage
346+
347+
You can generate the Hey API Nuxt client via the CLI instead of the Nuxt module.
348+
349+
In your [configuration](/openapi-ts/get-started), add `@hey-api/client-nuxt` to your plugins and you'll be ready to generate client artifacts. :tada:
350+
351+
::: code-group
352+
353+
```js [config]
354+
export default {
355+
input: 'hey-api/backend', // sign up at app.heyapi.dev
356+
output: 'src/client',
357+
plugins: ['@hey-api/client-nuxt'], // [!code ++]
358+
};
359+
```
360+
361+
```sh [cli]
362+
npx @hey-api/openapi-ts \
363+
-i hey-api/backend \
364+
-o src/client \
365+
-c @hey-api/client-nuxt # [!code ++]
366+
```
367+
368+
:::
369+
262370
## API
263371

264372
You can view the complete list of options in the [UserConfig](https://github.com/hey-api/openapi-ts/blob/main/packages/openapi-ts/src/plugins/@hey-api/client-nuxt/types.d.ts) interface.

0 commit comments

Comments
 (0)