SDKs

SDKs are located in the sdk.gen.ts file. SDKs are abstractions on top of clients and serve the same purpose. By default, @hey-api/openapi-ts will generate a flat SDK layer. Your choice to use SDKs depends on personal preferences and bundle size considerations.

Flat SDKs

This is the default setting. Flat SDKs support tree-shaking and can lead to reduced bundle size over duplicated client calls. The function names are generated from operation IDs or operation location.

Class SDKs

Class SDKs do not support tree-shaking which will lead to increased bundle sizes, but some people prefer this option for syntax reasons. The class names are generated from operation tags and method names are generated from operation IDs or operation location.

No SDKs

If you prefer to use clients directly or do not need the SDK layer, define plugins manually and omit the @hey-api/sdk plugin. Type support for clients is currently limited due to popularity of other options. If you'd like to use this option and need better types, please open an issue.

Configuration

You can modify the contents of sdk.gen.ts by configuring the @hey-api/sdk plugin. Note that you must specify the default plugins to preserve the default output.

flat

import { defaultPlugins } from '@hey-api/openapi-ts';

export default {
  client: '@hey-api/client-fetch',
  input: 'path/to/openapi.json',
  output: 'src/client',
  plugins: [
    ...defaultPlugins,
    {
      asClass: false, // default
      name: '@hey-api/sdk',
    },
  ],
};

class

import { defaultPlugins } from '@hey-api/openapi-ts';

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

none

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

Output

Below are different outputs depending on your chosen style. No SDKs approach will not generate the sdk.gen.ts file.

flat

import { client, type Options } from '@hey-api/client-fetch';

import type { AddPetData, AddPetError, AddPetResponse } from './types.gen';

export const addPet = (options: Options<AddPetData>) =>
  (options?.client ?? client).post<AddPetResponse, AddPetError>({
    ...options,
    url: '/pet',
  });

class

import { client, type Options } from '@hey-api/client-fetch';

import type { AddPetData, AddPetError, AddPetResponse } from './types.gen';

export class PetService {
  public static addPet(options: Options<AddPetData>) {
    return (options?.client ?? client).post<AddPetResponse, AddPetError>({
      ...options,
      url: '/pet',
    });
  }
}

Usage

This is how you'd make the same request using each approach.

flat

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

addPet({
  body: {
    name: 'Kitty',
  },
});

class

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

PetService.addPet({
  body: {
    name: 'Kitty',
  },
});

none

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

client.post({
  body: {
    name: 'Kitty',
  },
  url: '/pet',
});

Examples

You can view live examples on StackBlitz.

Sponsors

Love Hey API? Become our sponsor.

•