Next.js Client - OpenAPI TypeScript

The Next.js client is optimized for Next.js applications with support for server components, server actions, and Next.js caching features.

Installation

npm install @hey-api/client-next

pnpm add @hey-api/client-next

yarn add @hey-api/client-next

bun add @hey-api/client-next

Basic Usage

Create a client instance

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

export const client = createClient({
  baseUrl: 'https://api.example.com',
});

Use in Server Components

import { client } from '@/lib/api-client';

export default async function UsersPage() {
  const { data } = await client.get({
    url: '/users',
  });

  return (
    <div>
      {data?.map((user) => (
        <div key={user.id}>{user.name}</div>
      ))}
    </div>
  );
}

Use in Client Components

'use client';

import { client } from '@/lib/api-client';
import { useEffect, useState } from 'react';

export default function UsersClient() {
  const [users, setUsers] = useState([]);

  useEffect(() => {
    client.get({ url: '/users' }).then(({ data }) => {
      if (data) setUsers(data);
    });
  }, []);

  return (
    <div>
      {users.map((user) => (
        <div key={user.id}>{user.name}</div>
      ))}
    </div>
  );
}

Configuration

The Next.js client extends the Fetch client with Next.js-specific features:

Client Options

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

const client = createClient({
  // Base URL for all requests
  baseUrl: 'https://api.example.com',

  // Default headers
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'your-api-key',
  },

  // Custom fetch implementation
  fetch: customFetch,

  // Response parsing format
  parseAs: 'json', // 'json' | 'text' | 'blob' | 'arrayBuffer' | 'formData' | 'stream' | 'auto'

  // Error handling
  throwOnError: false,

  // Authentication
  auth: async (auth) => getToken(),

  // Body serialization
  bodySerializer: (body) => JSON.stringify(body),

  // Query serialization
  querySerializer: {
    array: { style: 'form', explode: true },
    object: { style: 'deepObject', explode: true },
  },

  // Request validator
  requestValidator: async (data) => validateRequest(data),

  // Response transformer
  responseTransformer: async (data) => transformResponse(data),

  // Response validator
  responseValidator: async (data) => validateResponse(data),

  // Standard fetch options
  credentials: 'include',
  mode: 'cors',
  cache: 'default',
});

HTTP Methods

GET
POST
PUT
DELETE

const { data, error, response } = await client.get({
  url: '/users',
  query: {
    page: 1,
    limit: 10,
  },
});

const { data, error } = await client.post({
  url: '/users',
  body: {
    name: 'John Doe',
    email: 'john@example.com',
  },
});

const { data } = await client.put({
  url: '/users/{id}',
  path: { id: 123 },
  body: {
    name: 'Jane Doe',
  },
});

const { data } = await client.delete({
  url: '/users/{id}',
  path: { id: 123 },
});

Server Components

Use the client in React Server Components:

import { client } from '@/lib/api-client';

export default async function UserProfile({ params }: { params: { id: string } }) {
  const { data, error } = await client.get({
    url: '/users/{id}',
    path: { id: params.id },
  });

  if (error) {
    return <div>Error loading user</div>;
  }

  return (
    <div>
      <h1>{data.name}</h1>
      <p>{data.email}</p>
    </div>
  );
}

Server Actions

Use the client in Server Actions:

'use server';

import { client } from '@/lib/api-client';
import { revalidatePath } from 'next/cache';

export async function createUser(formData: FormData) {
  const { data, error } = await client.post({
    url: '/users',
    body: {
      name: formData.get('name'),
      email: formData.get('email'),
    },
  });

  if (error) {
    return { error: 'Failed to create user' };
  }

  revalidatePath('/users');
  return { success: true, user: data };
}

Route Handlers

Use in Next.js API routes:

import { client } from '@/lib/api-client';
import { NextResponse } from 'next/server';

export async function GET(request: Request) {
  const { searchParams } = new URL(request.url);
  const page = searchParams.get('page') || '1';

  const { data, error } = await client.get({
    url: '/users',
    query: { page },
  });

  if (error) {
    return NextResponse.json({ error: 'Failed to fetch users' }, { status: 500 });
  }

  return NextResponse.json(data);
}

Authentication

Server-Side Authentication

import { createClient } from '@hey-api/client-next';
import { cookies } from 'next/headers';

export const client = createClient({
  baseUrl: 'https://api.example.com',
  auth: async (auth) => {
    if (auth.scheme === 'bearer') {
      const cookieStore = await cookies();
      return cookieStore.get('access_token')?.value;
    }
  },
});

Client-Side Authentication

'use client';

import { createClient } from '@hey-api/client-next';
import { useSession } from 'next-auth/react';

export function useApiClient() {
  const { data: session } = useSession();

  const client = createClient({
    baseUrl: 'https://api.example.com',
    auth: async (auth) => {
      if (auth.scheme === 'bearer') {
        return session?.accessToken;
      }
    },
  });

  return client;
}

Caching Strategies

Leverage Next.js caching with the fetch options:

Force Cache (Default)

const { data } = await client.get({
  url: '/users',
  cache: 'force-cache', // Cache indefinitely
});

No Store (Dynamic)

const { data } = await client.get({
  url: '/users',
  cache: 'no-store', // Never cache, always fetch fresh
});

Revalidate

const { data } = await client.get({
  url: '/users',
  next: { revalidate: 60 }, // Revalidate every 60 seconds
});

On-Demand Revalidation

import { revalidateTag, revalidatePath } from 'next/cache';

// Tag the request
const { data } = await client.get({
  url: '/users',
  next: { tags: ['users'] },
});

// Revalidate by tag
revalidateTag('users');

// Or revalidate by path
revalidatePath('/users');

Interceptors

Request Interceptor

client.interceptors.request.use((request, options) => {
  // Add request ID
  request.headers.set('X-Request-ID', crypto.randomUUID());
  return request;
});

Response Interceptor

client.interceptors.response.use((response, request, options) => {
  // Log response time
  console.log('Response time:', response.headers.get('X-Response-Time'));
  return response;
});

Error Interceptor

client.interceptors.error.use((error, response, request, options) => {
  // Transform 401 errors
  if (response?.status === 401) {
    return { message: 'Unauthorized', code: 'AUTH_ERROR' };
  }
  return error;
});

Server-Sent Events

Stream real-time data in client components:

'use client';

import { client } from '@/lib/api-client';
import { useEffect, useState } from 'react';

export default function EventStream() {
  const [events, setEvents] = useState<any[]>([]);

  useEffect(() => {
    let stream: any;

    async function startStream() {
      stream = await client.sse.get({
        url: '/events',
        onSseEvent: (event) => {
          setEvents((prev) => [...prev, event.data]);
        },
      });
    }

    startStream();

    return () => {
      stream?.close();
    };
  }, []);

  return (
    <div>
      {events.map((event, i) => (
        <div key={i}>{JSON.stringify(event)}</div>
      ))}
    </div>
  );
}

Advanced Examples

Dynamic Client Configuration

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

export async function getApiClient() {
  const headersList = await headers();
  const userAgent = headersList.get('user-agent') || '';

  return createClient({
    baseUrl: 'https://api.example.com',
    headers: {
      'User-Agent': userAgent,
    },
  });
}

// Use in server components
export default async function Page() {
  const client = await getApiClient();
  const { data } = await client.get({ url: '/users' });
  // ...
}

Parallel Data Fetching

import { client } from '@/lib/api-client';

export default async function Dashboard() {
  const [usersResult, postsResult, statsResult] = await Promise.all([
    client.get({ url: '/users' }),
    client.get({ url: '/posts' }),
    client.get({ url: '/stats' }),
  ]);

  return (
    <div>
      <UsersList users={usersResult.data} />
      <PostsList posts={postsResult.data} />
      <StatsWidget stats={statsResult.data} />
    </div>
  );
}

Request Deduplication

Next.js automatically deduplicates identical fetch requests:

// These will only make one network request
export default async function Page() {
  const user1 = await client.get({ url: '/users/1' });
  const user2 = await client.get({ url: '/users/1' }); // Deduped!

  // ...
}

TypeScript Types

import type {
  Client,
  Config,
  RequestOptions,
  RequestResult,
} from '@hey-api/client-next';

// Type-safe client wrapper
function createApiClient(config: Config): Client {
  return createClient({
    ...config,
    baseUrl: process.env.NEXT_PUBLIC_API_URL,
  });
}

Best Practices

Create a centralized client instance

Create a single client instance in a shared module to ensure consistent configuration:

// lib/api-client.ts
import { createClient } from '@hey-api/client-next';

export const client = createClient({
  baseUrl: process.env.NEXT_PUBLIC_API_URL,
});

Use Server Components for data fetching

Prefer Server Components for initial data loading to reduce client bundle size:

// app/users/page.tsx (Server Component)
export default async function UsersPage() {
  const { data } = await client.get({ url: '/users' });
  return <UsersList users={data} />;
}

Handle errors gracefully

Always check for errors and provide fallbacks:

const { data, error } = await client.get({ url: '/users' });

if (error) {
  return <ErrorMessage error={error} />;
}

return <UsersList users={data} />;

Leverage caching strategically

Use appropriate caching strategies based on data freshness requirements:

// Static data - cache indefinitely
const { data: countries } = await client.get({
  url: '/countries',
  cache: 'force-cache',
});

// Dynamic data - always fresh
const { data: notifications } = await client.get({
  url: '/notifications',
  cache: 'no-store',
});

// Revalidate periodically
const { data: posts } = await client.get({
  url: '/posts',
  next: { revalidate: 300 }, // 5 minutes
});

Next Steps

Fetch Client

Learn about the underlying Fetch client

Server Components

Use in React Server Components

Caching

Configure caching strategies

Authentication

Set up API authentication

​Installation

​Basic Usage

​Configuration

​Client Options

​HTTP Methods

​Server Components

​Server Actions

​Route Handlers

​Authentication

​Server-Side Authentication

​Client-Side Authentication

​Caching Strategies

​Force Cache (Default)

​No Store (Dynamic)

​Revalidate

​On-Demand Revalidation

​Interceptors

​Request Interceptor

​Response Interceptor

​Error Interceptor

​Server-Sent Events

​Advanced Examples

​Dynamic Client Configuration

​Parallel Data Fetching

​Request Deduplication

​TypeScript Types

​Best Practices

​Next Steps

Fetch Client

Server Components

Caching

Authentication

Installation

Basic Usage

Configuration

Client Options

HTTP Methods

Server Components

Server Actions

Route Handlers

Authentication

Server-Side Authentication

Client-Side Authentication

Caching Strategies

Force Cache (Default)

No Store (Dynamic)

Revalidate

On-Demand Revalidation

Interceptors

Request Interceptor

Response Interceptor

Error Interceptor

Server-Sent Events

Advanced Examples

Dynamic Client Configuration

Parallel Data Fetching

Request Deduplication

TypeScript Types

Best Practices

Next Steps