Nuxt

WARNING

Nuxt client is currently in beta. The interface might change before it becomes stable. We encourage you to leave feedback on GitHub.

Nuxt is an open source framework that makes web development intuitive and powerful.

Installation

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

npm

npm install @hey-api/client-nuxt

pnpm

pnpm add @hey-api/client-nuxt

yarn

yarn add @hey-api/client-nuxt

bun

bun add @hey-api/client-nuxt

In your configuration, add @hey-api/client-nuxt to your plugins and you'll be ready to generate client artifacts. 🎉

config

export default {
  input: 'path/to/openapi.json',
  output: 'src/client',
  plugins: ['@hey-api/client-nuxt'], 
};

cli

npx @hey-api/openapi-ts \
  -i path/to/openapi.json \
  -o src/client \
  -c @hey-api/client-nuxt

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 file. You will most likely want to configure the exported client instance. There are two ways to do that.

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

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

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.

export default {
  input: 'path/to/openapi.json',
  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.

hey-api.ts

import type { CreateClientConfig } from '@hey-api/client-nuxt';

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()

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

import { createClient } from '@hey-api/client-nuxt';

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.

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

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.

const response = await getFoo({
  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. Nuxt provides interceptors through ofetch, please refer to their documentation on $fetch.

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

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

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

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.

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.

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

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

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.

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'

Bundling

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.

export default {
  input: 'path/to/openapi.json',
  output: 'src/client',
  plugins: [
    {
      bundle: true, 
      name: '@hey-api/client-nuxt',
    },
  ],
};

Examples

You can view live examples on StackBlitz.

Sponsors

Love Hey API? Become our sponsor.

•