Merge pull request #1899 from hey-api/fix/client-fetch-to-next

fix: set next field to never and recommend next.js client

Author: mrlubos

.changeset/gentle-bobcats-sniff.md

@@ -0,0 +1,5 @@
+---
+'@hey-api/client-fetch': minor
+---
+
+fix: set next field to never and recommend switching to the Next.js client

docs/openapi-ts/clients/next-js.md

@@ -68,20 +68,6 @@ The Next.js client is built as a thin wrapper on top of [fetch](https://nextjs.o
 
 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.
 
-### `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 Fetch API configuration option to `setConfig()`, and even your own Fetch implementation.
-
-```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
 
 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.
@@ -114,7 +100,21 @@ export const createClientConfig: CreateClientConfig = (config) => ({
 
 :::
 
-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.
+With this approach, `client.gen.ts` will call `createClientConfig()` before initializing the `client` instance. This is the recommended approach because it guarantees the client will be initialized in both server and client environment. If needed, you can still use `setConfig()` to update the client configuration later.
+
+### `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 Fetch API configuration option to `setConfig()`, and even your own Fetch implementation.
+
+```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, this might be an acceptable trade-off. However, our Next.js users usually want to use the first approach.
 
 ### `createClient()`
 

examples/openapi-ts-next/src/client/client.gen.ts

@@ -24,5 +24,9 @@ export type CreateClientConfig<T extends DefaultClientOptions = ClientOptions> =
   ) => Config<Required<DefaultClientOptions> & T>;
 
 export const client = createClient(
-  createClientConfig(createConfig<ClientOptions>()),
+  createClientConfig(
+    createConfig<ClientOptions>({
+      baseUrl: 'https://petstore3.swagger.io/api/v3',
+    }),
+  ),
 );

examples/openapi-ts-next/src/client/sdk.gen.ts

@@ -37,6 +37,7 @@ import type {
   UpdatePetData,
   UpdatePetResponse,
   UpdatePetWithFormData,
+  UpdatePetWithFormResponse,
   UpdateUserData,
   UploadFileData,
   UploadFileResponse,
@@ -60,8 +61,8 @@ export type Options<
 };
 
 /**
- * Add a new pet to the store
- * Add a new pet to the store
+ * Add a new pet to the store.
+ * Add a new pet to the store.
  */
 export const addPet = <ThrowOnError extends boolean = false>(
   options: Options<AddPetData, ThrowOnError>,
@@ -84,8 +85,8 @@ export const addPet = <ThrowOnError extends boolean = false>(
   );
 
 /**
- * Update an existing pet
- * Update an existing pet by Id
+ * Update an existing pet.
+ * Update an existing pet by Id.
  */
 export const updatePet = <ThrowOnError extends boolean = false>(
   options: Options<UpdatePetData, ThrowOnError>,
@@ -110,8 +111,8 @@ export const updatePet = <ThrowOnError extends boolean = false>(
   });
 
 /**
- * Finds Pets by status
- * Multiple status values can be provided with comma separated strings
+ * Finds Pets by status.
+ * Multiple status values can be provided with comma separated strings.
  */
 export const findPetsByStatus = <ThrowOnError extends boolean = false>(
   options?: Options<FindPetsByStatusData, ThrowOnError>,
@@ -132,7 +133,7 @@ export const findPetsByStatus = <ThrowOnError extends boolean = false>(
   });
 
 /**
- * Finds Pets by tags
+ * Finds Pets by tags.
  * Multiple tags can be provided with comma separated strings. Use tag1, tag2, tag3 for testing.
  */
 export const findPetsByTags = <ThrowOnError extends boolean = false>(
@@ -154,7 +155,8 @@ export const findPetsByTags = <ThrowOnError extends boolean = false>(
   });
 
 /**
- * Deletes a pet
+ * Deletes a pet.
+ * Delete a pet.
  */
 export const deletePet = <ThrowOnError extends boolean = false>(
   options: Options<DeletePetData, ThrowOnError>,
@@ -171,8 +173,8 @@ export const deletePet = <ThrowOnError extends boolean = false>(
   });
 
 /**
- * Find pet by ID
- * Returns a single pet
+ * Find pet by ID.
+ * Returns a single pet.
  */
 export const getPetById = <ThrowOnError extends boolean = false>(
   options: Options<GetPetByIdData, ThrowOnError>,
@@ -197,12 +199,17 @@ export const getPetById = <ThrowOnError extends boolean = false>(
   });
 
 /**
- * Updates a pet in the store with form data
+ * Updates a pet in the store with form data.
+ * Updates a pet resource based on the form data.
  */
 export const updatePetWithForm = <ThrowOnError extends boolean = false>(
   options: Options<UpdatePetWithFormData, ThrowOnError>,
 ) =>
-  (options.client ?? _heyApiClient).post<unknown, unknown, ThrowOnError>({
+  (options.client ?? _heyApiClient).post<
+    UpdatePetWithFormResponse,
+    unknown,
+    ThrowOnError
+  >({
     security: [
       {
         scheme: 'bearer',
@@ -214,7 +221,8 @@ export const updatePetWithForm = <ThrowOnError extends boolean = false>(
   });
 
 /**
- * uploads an image
+ * Uploads an image.
+ * Upload image of the pet.
  */
 export const uploadFile = <ThrowOnError extends boolean = false>(
   options: Options<UploadFileData, ThrowOnError>,
@@ -239,8 +247,8 @@ export const uploadFile = <ThrowOnError extends boolean = false>(
   });
 
 /**
- * Returns pet inventories by status
- * Returns a map of status codes to quantities
+ * Returns pet inventories by status.
+ * Returns a map of status codes to quantities.
  */
 export const getInventory = <ThrowOnError extends boolean = false>(
   options?: Options<GetInventoryData, ThrowOnError>,
@@ -261,8 +269,8 @@ export const getInventory = <ThrowOnError extends boolean = false>(
   });
 
 /**
- * Place an order for a pet
- * Place a new order in the store
+ * Place an order for a pet.
+ * Place a new order in the store.
  */
 export const placeOrder = <ThrowOnError extends boolean = false>(
   options?: Options<PlaceOrderData, ThrowOnError>,
@@ -281,8 +289,8 @@ export const placeOrder = <ThrowOnError extends boolean = false>(
   });
 
 /**
- * Delete purchase order by ID
- * For valid response try integer IDs with value < 1000. Anything above 1000 or nonintegers will generate API errors
+ * Delete purchase order by identifier.
+ * For valid response try integer IDs with value < 1000. Anything above 1000 or non-integers will generate API errors.
  */
 export const deleteOrder = <ThrowOnError extends boolean = false>(
   options: Options<DeleteOrderData, ThrowOnError>,
@@ -293,7 +301,7 @@ export const deleteOrder = <ThrowOnError extends boolean = false>(
   });
 
 /**
- * Find purchase order by ID
+ * Find purchase order by ID.
  * For valid response try integer IDs with value <= 5 or > 10. Other values will generate exceptions.
  */
 export const getOrderById = <ThrowOnError extends boolean = false>(
@@ -309,7 +317,7 @@ export const getOrderById = <ThrowOnError extends boolean = false>(
   });
 
 /**
- * Create user
+ * Create user.
  * This can only be done by the logged in user.
  */
 export const createUser = <ThrowOnError extends boolean = false>(
@@ -329,8 +337,8 @@ export const createUser = <ThrowOnError extends boolean = false>(
   });
 
 /**
- * Creates list of users with given input array
- * Creates list of users with given input array
+ * Creates list of users with given input array.
+ * Creates list of users with given input array.
  */
 export const createUsersWithListInput = <ThrowOnError extends boolean = false>(
   options?: Options<CreateUsersWithListInputData, ThrowOnError>,
@@ -349,7 +357,8 @@ export const createUsersWithListInput = <ThrowOnError extends boolean = false>(
   });
 
 /**
- * Logs user into the system
+ * Logs user into the system.
+ * Log into the system.
  */
 export const loginUser = <ThrowOnError extends boolean = false>(
   options?: Options<LoginUserData, ThrowOnError>,
@@ -364,7 +373,8 @@ export const loginUser = <ThrowOnError extends boolean = false>(
   });
 
 /**
- * Logs out current logged in user session
+ * Logs out current logged in user session.
+ * Log user out of the system.
  */
 export const logoutUser = <ThrowOnError extends boolean = false>(
   options?: Options<LogoutUserData, ThrowOnError>,
@@ -375,7 +385,7 @@ export const logoutUser = <ThrowOnError extends boolean = false>(
   });
 
 /**
- * Delete user
+ * Delete user resource.
  * This can only be done by the logged in user.
  */
 export const deleteUser = <ThrowOnError extends boolean = false>(
@@ -387,7 +397,8 @@ export const deleteUser = <ThrowOnError extends boolean = false>(
   });
 
 /**
- * Get user by user name
+ * Get user by user name.
+ * Get user detail based on username.
  */
 export const getUserByName = <ThrowOnError extends boolean = false>(
   options: Options<GetUserByNameData, ThrowOnError>,
@@ -402,7 +413,7 @@ export const getUserByName = <ThrowOnError extends boolean = false>(
   });
 
 /**
- * Update user
+ * Update user resource.
  * This can only be done by the logged in user.
  */
 export const updateUser = <ThrowOnError extends boolean = false>(