---
title: "Nuxt v3 Client"
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."
url: "https://heyapi.dev/docs/openapi/typescript/clients/nuxt"
---

Beta [Leave feedback](https://github.com/hey-api/openapi-ts/issues) · [Contribute](https://heyapi.dev/openapi-ts/community/contributing)

### About

[Section titled “About”](#about)

[Nuxt](https://nuxt.com) is an open source framework that makes web development intuitive and powerful.

The Nuxt client for Hey API generates a type-safe client from your OpenAPI spec, fully compatible with validators, transformers, and all core features.

## Features

[Section titled “Features”](#features)

* Nuxt v3 support
* seamless integration with `@hey-api/openapi-ts` ecosystem
* type-safe response data and errors
* response data validation and transformation
* access to the original request and response
* granular request and response customization options
* minimal learning curve thanks to extending the underlying technology
* support bundling inside the generated output

## Installation

[Section titled “Installation”](#installation)

Start by adding `@hey-api/nuxt` to your dependencies.

* npm

  ```sh
  npm install @hey-api/nuxt
  ```

* pnpm

  ```sh
  pnpm add @hey-api/nuxt
  ```

* yarn

  ```sh
  yarn add @hey-api/nuxt
  ```

* bun

  ```sh
  bun add @hey-api/nuxt
  ```

In your [configuration](https://heyapi.dev/openapi-ts/get-started), add `@hey-api/client-nuxt` to your plugins and you’ll be ready to generate client artifacts. 🎉

* config

  openapi-ts.config.ts

  ```js
  export default {
    input: 'hey-api/backend', // sign up at app.heyapi.dev
    output: 'src/client',
    plugins: ['@hey-api/client-nuxt'],
  };
  ```

* cli

  ```sh
  npx @hey-api/openapi-ts \
    -i hey-api/backend \
    -o src/client \
    -c @hey-api/client-nuxt
  ```

Tip

If you add `@hey-api/nuxt` to your Nuxt modules, this step is not needed.

## Configuration

[Section titled “Configuration”](#configuration)

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.

When we installed the client above, it created a [`client.gen.ts`](https://heyapi.dev/openapi-ts/output#client) file. You will most likely want to configure the exported `client` instance. There are two ways to do that.

### `setConfig()`

[Section titled “setConfig()”](#setconfig)

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-instance) implementation.

src/index.ts

```js
import { client } from 'client/client.gen';


client.setConfig({
  baseURL: 'https://example.com',
});
```

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.

### Runtime API

[Section titled “Runtime API”](#runtime-api)

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.

openapi-ts.config.ts

```js
export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  plugins: [
    {
      name: '@hey-api/client-nuxt',
      runtimeConfigPath: './src/hey-api.ts',
    },
  ],
};
```

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

src/hey-api.ts

```ts
import type { CreateClientConfig } from './client/client.gen';


export const createClientConfig: CreateClientConfig = (config) => ({
  ...config,
  baseURL: 'https://example.com',
});
```

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.

### `createClient()`

[Section titled “createClient()”](#createclient)

You can also create your own client instance. You can use it to manually send requests or point it to a different domain.

src/index.ts

```js
import { createClient } from './client/client';


const myClient = createClient({
  baseURL: 'https://example.com',
});
```

You can also pass this instance to any SDK function through the `client` option. This will override the default instance from `client.gen.ts`.

src/index.ts

```js
const response = await getFoo({
  client: myClient,
});
```

### SDKs

[Section titled “SDKs”](#sdks)

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.

src/index.ts

```js
const response = await getFoo({
  baseURL: 'https://example.com', // <-- override default configuration
});
```

## Interceptors

[Section titled “Interceptors”](#interceptors)

Interceptors (middleware) can be used to modify requests before they’re sent or responses before they’re returned to your application. Nuxt provides interceptors through ofetch, please refer to their documentation on [$fetch](https://nuxt.com/docs/api/utils/dollarfetch).

You can pass any Nuxt/ofetch arguments to the client instance.

Note

If you omit `composable`, `$fetch` is used by default.

src/index.ts

```js
import { client } from 'client/client.gen';


const result = await client.get({
  composable: '$fetch',
  onRequest: (context) => {
    // do something
  },
  url: '/foo',
});
```

## Auth

[Section titled “Auth”](#auth)

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.

src/index.ts

```js
import { client } from 'client/client.gen';


client.setConfig({
  auth: () => '<my_token>',
  baseURL: 'https://example.com',
});
```

If you’re not using SDKs or generating auth, using interceptors is a common approach to configuring auth for each request.

src/index.ts

```js
import { client } from 'client/client.gen';


client.setConfig({
  onRequest: ({ options }) => {
    options.headers.set('Authorization', 'Bearer <my_token>');
  },
});
```

## Build URL

[Section titled “Build URL”](#build-url)

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.

src/index.ts

```ts
type FooData = {
  path: {
    fooId: number;
  };
  query?: {
    bar?: string;
  };
  url: '/foo/{fooId}';
};


const url = client.buildUrl<FooData>({
  path: {
    fooId: 1,
  },
  query: {
    bar: 'baz',
  },
  url: '/foo/{fooId}',
});
console.log(url); // prints '/foo/1?bar=baz'
```

## Custom Instance

[Section titled “Custom Instance”](#custom-instance)

You can provide a custom `$fetch` instance. This is useful if you need to extend the default instance with extra functionality, or replace it altogether.

src/index.ts

```js
import { client } from 'client/client.gen';


client.setConfig({
  $fetch: () => {
    /* custom `$fetch` method */
  },
});
```

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

## API

[Section titled “API”](#api)

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.ts) interface.

## Examples

You can view live examples on [StackBlitz](https://stackblitz.com/orgs/github/hey-api/collections/openapi-ts-examples) or on [GitHub](https://github.com/hey-api/openapi-ts/tree/main/examples).