From 6715e2741d76d7f70423f0f52ce91f3625aa17f2 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Tue, 1 Jul 2025 11:45:12 -0400 Subject: [PATCH 01/33] Add options with param formatting from existing readme. --- .../sdks/pages/typescript/configuration.mdx | 175 +++++++++++++++++- 1 file changed, 174 insertions(+), 1 deletion(-) diff --git a/fern/products/sdks/pages/typescript/configuration.mdx b/fern/products/sdks/pages/typescript/configuration.mdx index 0651a7f29..b6ae1845e 100644 --- a/fern/products/sdks/pages/typescript/configuration.mdx +++ b/fern/products/sdks/pages/typescript/configuration.mdx @@ -5,4 +5,177 @@ description: Configuration options for the Fern Typescript SDK. # Typescript Configuration -Discover how to configure the Fern Typescript SDK for your project. \ No newline at end of file +Discover how to configure the Fern Typescript SDK for your project. + + + +You can customize the behavior of generators in `generators.yml`: + +```yml +default-group: local +groups: + local: + generators: + - name: fernapi/fern-typescript-node-sdk + version: 0.7.1 + config: + useBrandedStringAliases: true +``` + +### SDK Configuration + +The SDK generator support the following parameters: + + + + When enabled, string aliases are generated as branded strings. This makes each alias feel like its own type and improves compile-time safety. + + ```yaml + # fern definition + + types: + MyString: string + OtherString: string +``` + +```typescript +// generated code + +export type MyString = string & { __MyString: void }; +export const MyString = (value: string): MyString => value as MyString; + +export type OtherString = string & { __OtherString: void }; +export const OtherString = (value: string): OtherString => value as OtherString; +``` + +```typescript +// consuming the generated type + +function printMyString(s: MyString): void { + console.log("MyString: " + s); +} + +// doesn't compile, "foo" is not assignable to MyString +printMyString("foo"); + +const otherString = OtherString("other-string"); +// doesn't compile, otherString is not assignable to MyString +printMyString(otherString); + +// compiles +const myString = MyString("my-string"); +printMyString(myString); +``` + +When `useBrandedStringAliases` is disabled (the default), string aliases are generated as +normal TypeScript aliases: + +```typescript +// generated code + +export type MyString = string; + +export type OtherString = string; +``` + + + + When enabled, the client doesn't throw errors when a non-200 response is received from the server. Instead, the response is wrapped in an [`ApiResponse`](packages/core-utilities/fetcher/src/APIResponse.ts). + + ```typescript + const response = await client.callEndpoint(...); + if (response.ok) { + console.log(response.body) + } else { + console.error(respons.error) + } + ``` + + + + Customizes the exported namespace and client names. By default, names are based on the organization and API names in the Fern Definition. + + + + By default, the generated TypeScript targets CommonJS. Set to `true` to target `esnext` instead. + + + + When enabled, the generator outputs raw TypeScript files. When disabled (the default), outputs .js and d.ts files. This only applies when dumping code locally. This configuration is ignored when publishing to Github or npm._ When enabled, the generator outputs raw TypeScript files. When disabled (the default), the generator outputs `.js` and `d.ts` files. + + + + When enabled, [`withCredentials`](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest/withCredentials) is set to true when making network requests. + + + + When enabled, the generated client allows the end user to specify a custom fetcher implementation. + + ```typescript +const acme = new AcmeClient({ + fetcher: (args) => { + ... + }, +}); +``` + + + + When enabled, the generated client doesn't allow the user to specify a server URL. When disabled (the default), the generated client includes an option to override the server URL: + + ```typescript + const acme = new AcmeClient({ + environment: "localhost:8080" + }); + ``` + + + + The default timeout for network requests. In the generated client, this can be overridden at the request level. + + + + By default, the client will throw an error if the response from the server +doesn't match the expected type (based on how the response is modeled in the +Fern Definition). + +If `skipResponseValidation` is enabled, the client will never throw if the response is misshapen. Rather, the client +will log the issue using `console.warn` and return the data (casted to the expected response type). + + + + + Specify extra dependencies in the generated package.json. Useful when utilizing .fernignore to supplement the generated client with custom code. Note: Only applies when publishing to Github. + + + + Specify extra dev dependencies in the generated package.json. Note: Only applies when publishing to Github. + + This is useful +when you utilize [`.fernignore`](https://buildwithfern.com/learn/sdks/capabilities/custom-code) to +supplement the generated client with custom code. + +```yaml +# generators.yml +config: + extraDependencies: + lodash: "3.0.2" +``` + + + + When enabled, unknown types from Fern are generated into TypeScript using any instead of the unknown type. + + + + When enabled, no serialization/deserialization code is generated. The client uses JSON.parse() and JSON.stringify() instead of the default serde layer that provides validation and complex type support. + + + + When enabled, optional properties are generated with | undefined instead of optional TypeScript properties (using ?). + + + + When enabled, property names in the generated code will retain their original casing from the API definition instead of being converted to camelCase. + + From cde8cfec41839369fea37eda83a8cf794f4d3ef7 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Tue, 1 Jul 2025 12:46:18 -0400 Subject: [PATCH 02/33] Add all available options, formatted with paramfield --- .../sdks/pages/typescript/configuration.mdx | 322 +++++++++++++----- 1 file changed, 242 insertions(+), 80 deletions(-) diff --git a/fern/products/sdks/pages/typescript/configuration.mdx b/fern/products/sdks/pages/typescript/configuration.mdx index b6ae1845e..7e48d1ead 100644 --- a/fern/products/sdks/pages/typescript/configuration.mdx +++ b/fern/products/sdks/pages/typescript/configuration.mdx @@ -3,15 +3,9 @@ title: Typescript Configuration description: Configuration options for the Fern Typescript SDK. --- -# Typescript Configuration - -Discover how to configure the Fern Typescript SDK for your project. - - - You can customize the behavior of generators in `generators.yml`: -```yml +```yml {7-8} default-group: local groups: local: @@ -22,10 +16,239 @@ groups: useBrandedStringAliases: true ``` -### SDK Configuration +## SDK configuration options + + + + + + By default, the generated TypeScript targets CommonJS. Set to `true` to target `esnext` instead. + + + + When enabled, the generator outputs raw TypeScript files. When disabled (the default), outputs .js and d.ts files. This only applies when dumping code locally. This configuration is ignored when publishing to Github or npm._ When enabled, the generator outputs raw TypeScript files. When disabled (the default), the generator outputs `.js` and `d.ts` files. + + + + When enabled, [`withCredentials`](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest/withCredentials) is set to true when making network requests. + + + + + + + When enabled, the generated client allows the end user to specify a custom fetcher implementation. + + ```typescript +const acme = new AcmeClient({ + fetcher: (args) => { + ... + }, +}); +``` + + + + + + + + + + By default, the client will throw an error if the response from the server +doesn't match the expected type (based on how the response is modeled in the +Fern Definition). + +If `skipResponseValidation` is enabled, the client will never throw if the response is misshapen. Rather, the client +will log the issue using `console.warn` and return the data (casted to the expected response type). + + + + + Specify extra dependencies in the generated package.json. This is useful +when you utilize [`.fernignore`](https://buildwithfern.com/learn/sdks/capabilities/custom-code) to +supplement the generated client with custom code. Note: Only applies when publishing to Github. + + +```yaml +# generators.yml +config: + extraDependencies: + lodash: "3.0.2" +``` + + + + Specify extra dev dependencies in the generated package.json. Note: Only applies when publishing to Github. + + _Note: This only applies when publishing to Github._ + +You can use `extraDevDependencies` to specify extra dev dependencies in the generated package.json. + +```yaml +# generators.yml +config: + extraDevDependencies: + jest: "29.0.7" +``` + + + + + + + + + + In Fern, there's an `unknown` type that represents data that isn't knowable at runtime. When enabled, unknown types from Fern are generated into TypeScript using `any` instead of the unknown type. + + + + By default, Fern's `optional<>` properties will translate to optional TypeScript properties: + + ```yaml + Person: + properties: + name: string + age: optional + ``` + + ```typescript + interface Person { + name: string; + age?: number; + } + ``` + + When `noOptionalProperties` is enabled, the generated properties are never optional. Instead, the type is generated with `| undefined`: + + ```typescript + interface Person { + name: string; + age: number | undefined; + } + ``` + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +### Options relevant to dynamic snippets + + + + + + + + + + + + + + + + Customizes the exported namespace and client names. By default, names are based on the organization and API names in the Fern Definition. + + + + When enabled, no serialization/deserialization code is generated. The client uses `JSON.parse()` and `JSON.stringify()` instead of the default Serde layer. + + By default, the generated client includes a layer for serializing requests and deserializing responses. This has three benefits: + +1. The client validates requests and response at runtime, client-side. + +2. The client can support complex types, like `Date` and `Set`. + +3. The generated types can stray from the wire/JSON representation to be more + idiomatic. For example, when `noSerdeLayer` is disabled, all properties are `camelCase`, + even if the server is expecting `snake_case`. + + + + + + + When enabled, the generated client doesn't allow the user to specify a server URL. When disabled (the default), the generated client includes an option to override the server URL: + + ```typescript + const acme = new AcmeClient({ + environment: "localhost:8080" + }); + ``` + + + + When enabled, property names in the generated code retain their original casing from the API definition instead of being converted to camelCase. + + ```yaml + # generators.yml + config: + retainOriginalCasing: true + ``` -The SDK generator support the following parameters: + **Example with OpenAPI input:** + ```yaml {7, 9} + # OpenAPI schema + components: + schemas: + User: + type: object + properties: + user_id: + type: string + display_name: + type: string + ``` + Generated TypeScript with `retainOriginalCasing: true`: + ```typescript {2-3} + export interface User { + user_id: string; + display_name: string; + } + ``` + + Generated TypeScript with default settings (`retainOriginalCasing: false`): + ```typescript {2-3} + export interface User { + userId: string; + displayName: string; + } + ``` + + + + + When enabled, string aliases are generated as branded strings. This makes each alias feel like its own type and improves compile-time safety. @@ -92,90 +315,29 @@ export type OtherString = string; ``` - - Customizes the exported namespace and client names. By default, names are based on the organization and API names in the Fern Definition. - +### Beta options - - By default, the generated TypeScript targets CommonJS. Set to `true` to target `esnext` instead. + - - When enabled, the generator outputs raw TypeScript files. When disabled (the default), outputs .js and d.ts files. This only applies when dumping code locally. This configuration is ignored when publishing to Github or npm._ When enabled, the generator outputs raw TypeScript files. When disabled (the default), the generator outputs `.js` and `d.ts` files. + - - When enabled, [`withCredentials`](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest/withCredentials) is set to true when making network requests. + - - When enabled, the generated client allows the end user to specify a custom fetcher implementation. - - ```typescript -const acme = new AcmeClient({ - fetcher: (args) => { - ... - }, -}); -``` + - - When enabled, the generated client doesn't allow the user to specify a server URL. When disabled (the default), the generated client includes an option to override the server URL: - - ```typescript - const acme = new AcmeClient({ - environment: "localhost:8080" - }); - ``` + - - The default timeout for network requests. In the generated client, this can be overridden at the request level. - - - - By default, the client will throw an error if the response from the server -doesn't match the expected type (based on how the response is modeled in the -Fern Definition). - -If `skipResponseValidation` is enabled, the client will never throw if the response is misshapen. Rather, the client -will log the issue using `console.warn` and return the data (casted to the expected response type). +### Deprecated Options + +The default timeout for network requests. In the generated client, this can be overridden at the request level. - - Specify extra dependencies in the generated package.json. Useful when utilizing .fernignore to supplement the generated client with custom code. Note: Only applies when publishing to Github. - - - - Specify extra dev dependencies in the generated package.json. Note: Only applies when publishing to Github. - - This is useful -when you utilize [`.fernignore`](https://buildwithfern.com/learn/sdks/capabilities/custom-code) to -supplement the generated client with custom code. - -```yaml -# generators.yml -config: - extraDependencies: - lodash: "3.0.2" -``` - - - - When enabled, unknown types from Fern are generated into TypeScript using any instead of the unknown type. - - - - When enabled, no serialization/deserialization code is generated. The client uses JSON.parse() and JSON.stringify() instead of the default serde layer that provides validation and complex type support. - - - - When enabled, optional properties are generated with | undefined instead of optional TypeScript properties (using ?). - - - - When enabled, property names in the generated code will retain their original casing from the API definition instead of being converted to camelCase. + From 95ed9a0c3f8f2669e63f7ac80960217f0a414fdb Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Tue, 1 Jul 2025 13:25:00 -0400 Subject: [PATCH 03/33] Small edits to formatting and descriptions --- .../sdks/pages/typescript/configuration.mdx | 153 ++++++++++-------- 1 file changed, 86 insertions(+), 67 deletions(-) diff --git a/fern/products/sdks/pages/typescript/configuration.mdx b/fern/products/sdks/pages/typescript/configuration.mdx index 7e48d1ead..8ac6e9ba8 100644 --- a/fern/products/sdks/pages/typescript/configuration.mdx +++ b/fern/products/sdks/pages/typescript/configuration.mdx @@ -22,15 +22,17 @@ groups: - By default, the generated TypeScript targets CommonJS. Set to `true` to target `esnext` instead. + By default, the generated TypeScript targets CommonJS. Setting to `true` targets `esnext` instead. - When enabled, the generator outputs raw TypeScript files. When disabled (the default), outputs .js and d.ts files. This only applies when dumping code locally. This configuration is ignored when publishing to Github or npm._ When enabled, the generator outputs raw TypeScript files. When disabled (the default), the generator outputs `.js` and `d.ts` files. + When enabled, the generator outputs raw TypeScript files. When disabled (the default), outputs `.js` and `d.ts` files. + + This only applies when dumping code locally. This configuration is ignored when publishing to Github or npm._ - When enabled, [`withCredentials`](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest/withCredentials) is set to true when making network requests. + When enabled, [`withCredentials`](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest/withCredentials) is set to `true` when making network requests. @@ -40,12 +42,12 @@ groups: When enabled, the generated client allows the end user to specify a custom fetcher implementation. ```typescript -const acme = new AcmeClient({ - fetcher: (args) => { - ... - }, -}); -``` + const acme = new AcmeClient({ + fetcher: (args) => { + ... + }, + }); + ``` @@ -55,20 +57,18 @@ const acme = new AcmeClient({ - By default, the client will throw an error if the response from the server + By default, the client will throw an error if the response from the server doesn't match the expected type (based on how the response is modeled in the Fern Definition). -If `skipResponseValidation` is enabled, the client will never throw if the response is misshapen. Rather, the client -will log the issue using `console.warn` and return the data (casted to the expected response type). +If `skipResponseValidation` is set to `true`, the client will never throw if the response is misshapen. Instead, the client will log the issue using `console.warn` and return the data (casted to the expected response type). - Specify extra dependencies in the generated package.json. This is useful + Specify extra dependencies in the generated `package.json`. This is useful when you utilize [`.fernignore`](https://buildwithfern.com/learn/sdks/capabilities/custom-code) to -supplement the generated client with custom code. Note: Only applies when publishing to Github. - +supplement the generated client with custom code. ```yaml # generators.yml @@ -76,14 +76,11 @@ config: extraDependencies: lodash: "3.0.2" ``` + - Specify extra dev dependencies in the generated package.json. Note: Only applies when publishing to Github. - - _Note: This only applies when publishing to Github._ - -You can use `extraDevDependencies` to specify extra dev dependencies in the generated package.json. + Specify extra dev dependencies in the generated `package.json`. ```yaml # generators.yml @@ -91,6 +88,8 @@ config: extraDevDependencies: jest: "29.0.7" ``` + +Only applies when publishing to Github. @@ -100,20 +99,20 @@ config: - In Fern, there's an `unknown` type that represents data that isn't knowable at runtime. When enabled, unknown types from Fern are generated into TypeScript using `any` instead of the unknown type. + In Fern, there's an `unknown` type that represents data that isn't knowable at runtime. When `treatUnknownAsAny` is enabled, unknown types from Fern are generated into TypeScript using `any` instead of the `unknown` type. By default, Fern's `optional<>` properties will translate to optional TypeScript properties: - ```yaml + ```yaml {4} Person: properties: name: string age: optional ``` - ```typescript + ```typescript {3} interface Person { name: string; age?: number; @@ -122,7 +121,7 @@ config: When `noOptionalProperties` is enabled, the generated properties are never optional. Instead, the type is generated with `| undefined`: - ```typescript + ```typescript {3} interface Person { name: string; age: number | undefined; @@ -176,21 +175,40 @@ config: - Customizes the exported namespace and client names. By default, names are based on the organization and API names in the Fern Definition. +By default, names are based on the organization and API names in the Fern Definition: + + ```typescript + import { AcmeApi, AcmeApiClient } from "@acme/node"; + ``` + + `namespaceExport` customizes the exported namespace and client names: + + ```yaml + # generators.yml + config: + namespaceExport: Acme + ``` + + ```typescript + import { Acme, AcmeClient } from "@acme/node"; + ``` + - When enabled, no serialization/deserialization code is generated. The client uses `JSON.parse()` and `JSON.stringify()` instead of the default Serde layer. + By default, the generated client includes a layer for serializing requests and deserializing responses. This has three benefits: - By default, the generated client includes a layer for serializing requests and deserializing responses. This has three benefits: + 1. The client validates requests and response at runtime (client-side). -1. The client validates requests and response at runtime, client-side. + 1. The client can support complex types like `Date` and `Set`. -2. The client can support complex types, like `Date` and `Set`. + 1. The generated types can stray from the wire/JSON representation to be more + idiomatic. For example, when `noSerdeLayer` is disabled, all properties are `camelCase`, + even if the server is expecting `snake_case`. -3. The generated types can stray from the wire/JSON representation to be more - idiomatic. For example, when `noSerdeLayer` is disabled, all properties are `camelCase`, - even if the server is expecting `snake_case`. + When `noSerdeLayer` is enabled, no serialization/deserialization code is generated. The client uses `JSON.parse()` and `JSON.stringify()` instead of the default Serde layer. + + @@ -251,55 +269,56 @@ config: - When enabled, string aliases are generated as branded strings. This makes each alias feel like its own type and improves compile-time safety. - ```yaml - # fern definition + When `useBrandedStringAliases` is disabled (the default), string aliases are generated as + normal TypeScript aliases: - types: - MyString: string - OtherString: string -``` + ```typescript + // generated code -```typescript -// generated code + export type MyString = string; -export type MyString = string & { __MyString: void }; -export const MyString = (value: string): MyString => value as MyString; + export type OtherString = string; + ``` + When `useBrandedStringAliases` is enabled, string aliases are generated as branded strings. This makes each alias feel like its own type and improves compile-time safety. -export type OtherString = string & { __OtherString: void }; -export const OtherString = (value: string): OtherString => value as OtherString; -``` + ```yaml + # fern definition -```typescript -// consuming the generated type + types: + MyString: string + OtherString: string + ``` -function printMyString(s: MyString): void { - console.log("MyString: " + s); -} + ```typescript + // generated code -// doesn't compile, "foo" is not assignable to MyString -printMyString("foo"); + export type MyString = string & { __MyString: void }; + export const MyString = (value: string): MyString => value as MyString; -const otherString = OtherString("other-string"); -// doesn't compile, otherString is not assignable to MyString -printMyString(otherString); + export type OtherString = string & { __OtherString: void }; + export const OtherString = (value: string): OtherString => value as OtherString; + ``` -// compiles -const myString = MyString("my-string"); -printMyString(myString); -``` + ```typescript + // consuming the generated type -When `useBrandedStringAliases` is disabled (the default), string aliases are generated as -normal TypeScript aliases: + function printMyString(s: MyString): void { + console.log("MyString: " + s); + } -```typescript -// generated code + // doesn't compile, "foo" is not assignable to MyString + printMyString("foo"); -export type MyString = string; + const otherString = OtherString("other-string"); + // doesn't compile, otherString is not assignable to MyString + printMyString(otherString); + + // compiles + const myString = MyString("my-string"); + printMyString(myString); + ``` -export type OtherString = string; -``` From ef5f81412eff4590077935312b3ee0ee37c7a3a9 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Tue, 1 Jul 2025 13:31:07 -0400 Subject: [PATCH 04/33] Small edit to intro text --- fern/products/sdks/pages/typescript/configuration.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fern/products/sdks/pages/typescript/configuration.mdx b/fern/products/sdks/pages/typescript/configuration.mdx index 8ac6e9ba8..ed29fa0da 100644 --- a/fern/products/sdks/pages/typescript/configuration.mdx +++ b/fern/products/sdks/pages/typescript/configuration.mdx @@ -3,7 +3,7 @@ title: Typescript Configuration description: Configuration options for the Fern Typescript SDK. --- -You can customize the behavior of generators in `generators.yml`: +You can customize the behavior of the TypeScript SDK generator in `generators.yml`: ```yml {7-8} default-group: local From 11480906cb0ee9a7af5bf0ed3f1297d322d14346 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Tue, 1 Jul 2025 13:33:47 -0400 Subject: [PATCH 05/33] Small edit to heading text --- fern/products/sdks/pages/typescript/configuration.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fern/products/sdks/pages/typescript/configuration.mdx b/fern/products/sdks/pages/typescript/configuration.mdx index ed29fa0da..892f0b2c7 100644 --- a/fern/products/sdks/pages/typescript/configuration.mdx +++ b/fern/products/sdks/pages/typescript/configuration.mdx @@ -351,7 +351,7 @@ By default, names are based on the organization and API names in the Fern Defini -### Deprecated Options +### Deprecated options The default timeout for network requests. In the generated client, this can be overridden at the request level. From 5448d5ea336369036cd1fe4695217125e8209a33 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Thu, 3 Jul 2025 11:14:08 -0400 Subject: [PATCH 06/33] delete some irrelevant flags --- .../sdks/pages/typescript/configuration.mdx | 18 +----------------- 1 file changed, 1 insertion(+), 17 deletions(-) diff --git a/fern/products/sdks/pages/typescript/configuration.mdx b/fern/products/sdks/pages/typescript/configuration.mdx index 892f0b2c7..926188d18 100644 --- a/fern/products/sdks/pages/typescript/configuration.mdx +++ b/fern/products/sdks/pages/typescript/configuration.mdx @@ -13,14 +13,11 @@ groups: - name: fernapi/fern-typescript-node-sdk version: 0.7.1 config: - useBrandedStringAliases: true + namespaceExport: Acme ``` ## SDK configuration options - - - By default, the generated TypeScript targets CommonJS. Setting to `true` targets `esnext` instead. @@ -141,9 +138,6 @@ config: - - - @@ -214,16 +208,6 @@ By default, names are based on the organization and API names in the Fern Defini - - When enabled, the generated client doesn't allow the user to specify a server URL. When disabled (the default), the generated client includes an option to override the server URL: - - ```typescript - const acme = new AcmeClient({ - environment: "localhost:8080" - }); - ``` - - When enabled, property names in the generated code retain their original casing from the API definition instead of being converted to camelCase. From c53665a95156d9669b4905d5a624d8b0404c4a71 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Thu, 3 Jul 2025 11:16:55 -0400 Subject: [PATCH 07/33] delete more irrelevant options --- fern/products/sdks/pages/typescript/configuration.mdx | 3 --- 1 file changed, 3 deletions(-) diff --git a/fern/products/sdks/pages/typescript/configuration.mdx b/fern/products/sdks/pages/typescript/configuration.mdx index 926188d18..8980dd2fe 100644 --- a/fern/products/sdks/pages/typescript/configuration.mdx +++ b/fern/products/sdks/pages/typescript/configuration.mdx @@ -205,9 +205,6 @@ By default, names are based on the organization and API names in the Fern Defini - - - When enabled, property names in the generated code retain their original casing from the API definition instead of being converted to camelCase. From 743fcb242b2d9970eed93c1339147202a46a9206 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Thu, 3 Jul 2025 11:18:01 -0400 Subject: [PATCH 08/33] delete more irrelevant options --- fern/products/sdks/pages/typescript/configuration.mdx | 7 ------- 1 file changed, 7 deletions(-) diff --git a/fern/products/sdks/pages/typescript/configuration.mdx b/fern/products/sdks/pages/typescript/configuration.mdx index 8980dd2fe..0bb12fa5e 100644 --- a/fern/products/sdks/pages/typescript/configuration.mdx +++ b/fern/products/sdks/pages/typescript/configuration.mdx @@ -326,18 +326,11 @@ By default, names are based on the organization and API names in the Fern Defini - - - ### Deprecated options - -The default timeout for network requests. In the generated client, this can be overridden at the request level. - - From f6d310d0c3859ee1d64840f2218f12c23198126d Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Thu, 3 Jul 2025 11:18:32 -0400 Subject: [PATCH 09/33] delete deprecated section --- fern/products/sdks/pages/typescript/configuration.mdx | 5 ----- 1 file changed, 5 deletions(-) diff --git a/fern/products/sdks/pages/typescript/configuration.mdx b/fern/products/sdks/pages/typescript/configuration.mdx index 0bb12fa5e..63e02b82c 100644 --- a/fern/products/sdks/pages/typescript/configuration.mdx +++ b/fern/products/sdks/pages/typescript/configuration.mdx @@ -329,8 +329,3 @@ By default, names are based on the organization and API names in the Fern Defini -### Deprecated options - - - - From 3b89c978c4b3c1687d4a17a043c2f16fe5945d7b Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Thu, 3 Jul 2025 11:20:01 -0400 Subject: [PATCH 10/33] delete outputEsm flag --- fern/products/sdks/pages/typescript/configuration.mdx | 4 ---- 1 file changed, 4 deletions(-) diff --git a/fern/products/sdks/pages/typescript/configuration.mdx b/fern/products/sdks/pages/typescript/configuration.mdx index 63e02b82c..10b2280e5 100644 --- a/fern/products/sdks/pages/typescript/configuration.mdx +++ b/fern/products/sdks/pages/typescript/configuration.mdx @@ -18,10 +18,6 @@ groups: ## SDK configuration options - - By default, the generated TypeScript targets CommonJS. Setting to `true` targets `esnext` instead. - - When enabled, the generator outputs raw TypeScript files. When disabled (the default), outputs `.js` and `d.ts` files. From e13608666e2a3e4081acac297eaabb3c568000c0 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Thu, 3 Jul 2025 11:21:51 -0400 Subject: [PATCH 11/33] delete allowCustomFetcher flag --- .../products/sdks/pages/typescript/configuration.mdx | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/fern/products/sdks/pages/typescript/configuration.mdx b/fern/products/sdks/pages/typescript/configuration.mdx index 10b2280e5..c5de86569 100644 --- a/fern/products/sdks/pages/typescript/configuration.mdx +++ b/fern/products/sdks/pages/typescript/configuration.mdx @@ -31,18 +31,6 @@ groups: - - When enabled, the generated client allows the end user to specify a custom fetcher implementation. - - ```typescript - const acme = new AcmeClient({ - fetcher: (args) => { - ... - }, - }); - ``` - - From ec3e8de44c1447c7d50676dfc53087e67ef59718 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Thu, 3 Jul 2025 11:23:45 -0400 Subject: [PATCH 12/33] remove dynamic snippets heading --- fern/products/sdks/pages/typescript/configuration.mdx | 2 -- 1 file changed, 2 deletions(-) diff --git a/fern/products/sdks/pages/typescript/configuration.mdx b/fern/products/sdks/pages/typescript/configuration.mdx index c5de86569..a256ed4ce 100644 --- a/fern/products/sdks/pages/typescript/configuration.mdx +++ b/fern/products/sdks/pages/typescript/configuration.mdx @@ -137,8 +137,6 @@ config: -### Options relevant to dynamic snippets - From 467cd1d223874bf60adaecf15279c156d1e5acf4 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Thu, 3 Jul 2025 11:24:43 -0400 Subject: [PATCH 13/33] add description to shouldGenerateWebsocketClients --- fern/products/sdks/pages/typescript/configuration.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/fern/products/sdks/pages/typescript/configuration.mdx b/fern/products/sdks/pages/typescript/configuration.mdx index a256ed4ce..db4412657 100644 --- a/fern/products/sdks/pages/typescript/configuration.mdx +++ b/fern/products/sdks/pages/typescript/configuration.mdx @@ -32,6 +32,7 @@ groups: + Generate WebSocket clients from your AsyncAPI specs. From cf7b063b93bdf55a45fe80ac26c1a07be95da222 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Thu, 3 Jul 2025 11:32:38 -0400 Subject: [PATCH 14/33] add description for extraPeerDependencies --- fern/products/sdks/pages/typescript/configuration.mdx | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/fern/products/sdks/pages/typescript/configuration.mdx b/fern/products/sdks/pages/typescript/configuration.mdx index db4412657..77988381d 100644 --- a/fern/products/sdks/pages/typescript/configuration.mdx +++ b/fern/products/sdks/pages/typescript/configuration.mdx @@ -75,6 +75,15 @@ config: +Specify extra peer dependencies in the `generated package.json`: + +```yaml +# generators.yml +config: + extraPeerDependencies: + react: ">=16.8.0 <19.0.0" + "react-dom": ">=16.8.0 <19.0.0" +``` From d879fbaf0818087835215f3700fe872df1c2e5b4 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Thu, 3 Jul 2025 11:35:05 -0400 Subject: [PATCH 15/33] add description for extraPeerDependenciesMeta --- fern/products/sdks/pages/typescript/configuration.mdx | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/fern/products/sdks/pages/typescript/configuration.mdx b/fern/products/sdks/pages/typescript/configuration.mdx index 77988381d..79eaf3ce6 100644 --- a/fern/products/sdks/pages/typescript/configuration.mdx +++ b/fern/products/sdks/pages/typescript/configuration.mdx @@ -75,7 +75,7 @@ config: -Specify extra peer dependencies in the `generated package.json`: +Specify extra peer dependencies in the generated `package.json`: ```yaml # generators.yml @@ -87,6 +87,15 @@ config: +Specify extra peer dependencies meta fields in the generated `package.json`: + +```yaml +# generators.yml +config: + extraPeerDependencies: + react: ">=16.8.0 <19.0.0" + "react-dom": ">=16.8.0 <19.0.0" +``` From 21619d77234b68dc862e83e8ff6b00d48b39b618 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Thu, 3 Jul 2025 11:36:43 -0400 Subject: [PATCH 16/33] add description for packagePath --- fern/products/sdks/pages/typescript/configuration.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/fern/products/sdks/pages/typescript/configuration.mdx b/fern/products/sdks/pages/typescript/configuration.mdx index 79eaf3ce6..d79a480d1 100644 --- a/fern/products/sdks/pages/typescript/configuration.mdx +++ b/fern/products/sdks/pages/typescript/configuration.mdx @@ -154,6 +154,7 @@ config: +Specify the path where the source files for the generated SDK should be placed. From ff44678b07d074e1e4c9591f028f69ab8fa0cbda Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Thu, 3 Jul 2025 11:39:51 -0400 Subject: [PATCH 17/33] modify description for noOptionalProperties --- fern/products/sdks/pages/typescript/configuration.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fern/products/sdks/pages/typescript/configuration.mdx b/fern/products/sdks/pages/typescript/configuration.mdx index d79a480d1..eb34842c3 100644 --- a/fern/products/sdks/pages/typescript/configuration.mdx +++ b/fern/products/sdks/pages/typescript/configuration.mdx @@ -119,7 +119,7 @@ config: } ``` - When `noOptionalProperties` is enabled, the generated properties are never optional. Instead, the type is generated with `| undefined`: + When `noOptionalProperties` is enabled, the generated properties are never optional. Instead, the type is generated with `| undefined`. As a result, users must explicitly set the property to a value or `undefined`. ```typescript {3} interface Person { From 6c1e677144247d15ded8cf66a0cfe259b5df0a59 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Thu, 3 Jul 2025 11:41:31 -0400 Subject: [PATCH 18/33] add description for packageJson --- .../sdks/pages/typescript/configuration.mdx | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/fern/products/sdks/pages/typescript/configuration.mdx b/fern/products/sdks/pages/typescript/configuration.mdx index eb34842c3..3e29bce4d 100644 --- a/fern/products/sdks/pages/typescript/configuration.mdx +++ b/fern/products/sdks/pages/typescript/configuration.mdx @@ -133,6 +133,21 @@ config: +When you specify an object in `packageJson`, it will be merged into the `package.json` file. + +```yaml +# generators.yml +config: + packageJson: + description: The SDK for Acme Corp's API. + author: + name: Acme Corp + url: https://developer.acmecorp.com + email: developers@acmecorp.com + bugs: + url: https://developer.acmecorp.com + email: developers@acmecorp.com +``` From 9381ddab00442b76163f977f39659937dfdd6657 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Thu, 3 Jul 2025 11:43:38 -0400 Subject: [PATCH 19/33] add description for publishToJsr --- fern/products/sdks/pages/typescript/configuration.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/fern/products/sdks/pages/typescript/configuration.mdx b/fern/products/sdks/pages/typescript/configuration.mdx index 3e29bce4d..844f651ee 100644 --- a/fern/products/sdks/pages/typescript/configuration.mdx +++ b/fern/products/sdks/pages/typescript/configuration.mdx @@ -151,6 +151,8 @@ config: +Publish your SDK to [JSR](https://jsr.io/). When enabled, the generator will +generate a `jsr.json` as well as a GitHub workflow to publish to JSR. From c443c1ddb892bf6cc72170d941ba6082eec1116d Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Thu, 3 Jul 2025 11:44:38 -0400 Subject: [PATCH 20/33] remove omitUndefined --- fern/products/sdks/pages/typescript/configuration.mdx | 3 --- 1 file changed, 3 deletions(-) diff --git a/fern/products/sdks/pages/typescript/configuration.mdx b/fern/products/sdks/pages/typescript/configuration.mdx index 844f651ee..517d4e950 100644 --- a/fern/products/sdks/pages/typescript/configuration.mdx +++ b/fern/products/sdks/pages/typescript/configuration.mdx @@ -155,9 +155,6 @@ Publish your SDK to [JSR](https://jsr.io/). When enabled, the generator will generate a `jsr.json` as well as a GitHub workflow to publish to JSR. - - - From 06b4dc1df19aa581e88905bbda01278108a1ead8 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Thu, 3 Jul 2025 11:46:44 -0400 Subject: [PATCH 21/33] add description for streamType --- fern/products/sdks/pages/typescript/configuration.mdx | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/fern/products/sdks/pages/typescript/configuration.mdx b/fern/products/sdks/pages/typescript/configuration.mdx index 517d4e950..f6e224c76 100644 --- a/fern/products/sdks/pages/typescript/configuration.mdx +++ b/fern/products/sdks/pages/typescript/configuration.mdx @@ -156,6 +156,12 @@ generate a `jsr.json` as well as a GitHub workflow to publish to JSR. +Change the type of stream that is used in the generated SDK. + +* `wrapper`: The streams use a wrapper with multiple underlying implementations to support versions of Node.js before Node.js 18. +* `web`: The streams use the web standard `ReadableStream`. + +The default is `web`. From 17993e904dcbb2e030aa7840e28475f62a770b3d Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Thu, 3 Jul 2025 11:54:31 -0400 Subject: [PATCH 22/33] add descriptions for fileResponseType, formDataSupport, and fetchSupport --- .../sdks/pages/typescript/configuration.mdx | 20 ++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/fern/products/sdks/pages/typescript/configuration.mdx b/fern/products/sdks/pages/typescript/configuration.mdx index f6e224c76..ade1493c8 100644 --- a/fern/products/sdks/pages/typescript/configuration.mdx +++ b/fern/products/sdks/pages/typescript/configuration.mdx @@ -165,12 +165,30 @@ The default is `web`. +Change the type of response returned to the user for a binary HTTP response: + +* `stream`: Returns a stream. See `streamType`, which controls the type of stream returned. +* `binary-response`: Returns the `BinaryResponse` type, which allows the user to choose how to consume the binary HTTP response. +Here's how your users can interact with the `BinaryResponse`: + +```typescript +const response = await client.getFile(...); +const stream = response.stream(); +// const arrayBuffer = await response.arrayBuffer(); +// const blob = await response.blob(); +// const bytes = await response.bytes(); +const bodyUsed = response.bodyUsed; +``` - +Choose whether you want to support Node.js 16 and above (`Node16`), or Node.js 18 and above (`Node18`). +* `Node16` uses multiple dependencies to support multipart forms, including `form-data`, `formdata-node`, and `form-data-encoder`. +* `Node18` uses the native FormData API, and accepts a wider range of types for file uploads, such as `Buffer`, `File`, `Blob`, `Readable`, `ReadableStream`, `ArrayBuffer`, and `Uint8Array` + +Choose whether you want to include `node-fetch` to support Node.js versions before Node.js 18, or choose `native` to use the native `fetch` API available in Node.js 18 and later. From 02ad8a8ac1f745deefccb71d81c3968e9f78e12c Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Thu, 3 Jul 2025 11:56:15 -0400 Subject: [PATCH 23/33] add description for allowExtraFields --- fern/products/sdks/pages/typescript/configuration.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fern/products/sdks/pages/typescript/configuration.mdx b/fern/products/sdks/pages/typescript/configuration.mdx index ade1493c8..d6d7ec85f 100644 --- a/fern/products/sdks/pages/typescript/configuration.mdx +++ b/fern/products/sdks/pages/typescript/configuration.mdx @@ -196,7 +196,7 @@ Specify the path where the source files for the generated SDK should be placed. - +Allow fields that are not defined in object schemas. This only applies to serde. From 1d518ab1e87059a2d40e8232eb4aa54b613dd996 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Thu, 3 Jul 2025 14:44:03 -0400 Subject: [PATCH 24/33] update enableInlineTypes description --- .../sdks/pages/typescript/configuration.mdx | 55 ++++++++++++++++++- 1 file changed, 54 insertions(+), 1 deletion(-) diff --git a/fern/products/sdks/pages/typescript/configuration.mdx b/fern/products/sdks/pages/typescript/configuration.mdx index d6d7ec85f..a826a8f32 100644 --- a/fern/products/sdks/pages/typescript/configuration.mdx +++ b/fern/products/sdks/pages/typescript/configuration.mdx @@ -199,7 +199,60 @@ Specify the path where the source files for the generated SDK should be placed. Allow fields that are not defined in object schemas. This only applies to serde. - + +When enabled, the inline schemas will be generated as nested types in TypeScript. +This results in cleaner type names and a more intuitive developer experience. + +`enableInlineTypes: false`: + +```typescript +// MyRootType.ts +import * as MySdk from "..."; + +export interface MyRootType { + foo: MySdk.MyRootTypeFoo; +} + +// MyRootTypeFoo.ts +import * as MySdk from "..."; + +export interface MyRootTypeFoo { + bar: MySdk.MyRootTypeFooBar; +} + +// MyRootTypeFooBar.ts +import * as MySdk from "..."; + +export interface MyRootTypeFooBar {} +``` +`enableInlineTypes: true`: + +```typescript +// MyRootType.ts +import * as MySdk from "..."; + +export interface MyRootType { + foo: MyRootType.Foo; +} + +export namespace MyRootType { + export interface Foo { + bar: Foo.Bar; + } + + export namespace Foo { + export interface Bar {} + } +} +``` + +Now users can get the deep nested `Bar` type as follows: + +```typescript +import { MyRootType } from MySdk; + +const bar: MyRootType.Foo.Bar = {}; +``` From 0b6644c905ec5ea9ffde4a93d6cd7413133dc064 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Thu, 3 Jul 2025 14:47:46 -0400 Subject: [PATCH 25/33] update inlineFileProperties description --- .../sdks/pages/typescript/configuration.mdx | 51 ++++++++++++++++++- 1 file changed, 50 insertions(+), 1 deletion(-) diff --git a/fern/products/sdks/pages/typescript/configuration.mdx b/fern/products/sdks/pages/typescript/configuration.mdx index a826a8f32..d7da1bd8f 100644 --- a/fern/products/sdks/pages/typescript/configuration.mdx +++ b/fern/products/sdks/pages/typescript/configuration.mdx @@ -255,7 +255,56 @@ const bar: MyRootType.Foo.Bar = {}; ``` - + +Generate file upload properties as inline request properties (instead of positional parameters). + +`inlineFileProperties: false`: + +```typescript +/** + * @param {File | fs.ReadStream} file + * @param {File[] | fs.ReadStream[]} fileList + * @param {File | fs.ReadStream | undefined} maybeFile + * @param {File[] | fs.ReadStream[] | undefined} maybeFileList + * @param {Acme.MyRequest} request + * @param {Service.RequestOptions} requestOptions - Request-specific configuration. + * + * @example + * await client.service.post(fs.createReadStream("/path/to/your/file"), [fs.createReadStream("/path/to/your/file")], fs.createReadStream("/path/to/your/file"), [fs.createReadStream("/path/to/your/file")], {}) + */ +public async post( + file: File | fs.ReadStream, + fileList: File[] | fs.ReadStream[], + maybeFile: File | fs.ReadStream | undefined, + maybeFileList: File[] | fs.ReadStream[] | undefined, + request: Acme.MyRequest, + requestOptions?: Acme.RequestOptions +): Promise { + ... +} +``` + +`inlineFileProperties: true`: + +```typescript +/** + * @param {Acme.MyRequest} request + * @param {Service.RequestOptions} requestOptions - Request-specific configuration. + * + * @example + * await client.service.post({ + * file: fs.createReadStream("/path/to/your/file"), + * fileList: [fs.createReadStream("/path/to/your/file")] + * }) + */ +public async post( + request: Acme.MyRequest, + requestOptions?: Service.RequestOptions +): Promise { + ... +} +``` + From 0b59d2c8b05c0f96e11f2ddc7cbf7b0082d0362f Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Thu, 3 Jul 2025 14:56:12 -0400 Subject: [PATCH 26/33] update inlinePathParameters and useBigInt --- .../sdks/pages/typescript/configuration.mdx | 65 ++++++++++++++++++- 1 file changed, 63 insertions(+), 2 deletions(-) diff --git a/fern/products/sdks/pages/typescript/configuration.mdx b/fern/products/sdks/pages/typescript/configuration.mdx index d7da1bd8f..cee5af838 100644 --- a/fern/products/sdks/pages/typescript/configuration.mdx +++ b/fern/products/sdks/pages/typescript/configuration.mdx @@ -307,7 +307,20 @@ public async post( - + +Inline path parameters into request types. + +`inlinePathParameters: false`: + +```typescript +await service.getFoo("pathParamValue", { id: "SOME_ID" }); +``` + +`inlinePathParameters: true`: +```typescript +await service.getFoo({ pathParamName: "pathParamValue", id: "SOME_ID" }); +``` + @@ -388,7 +401,55 @@ By default, names are based on the organization and API names in the Fern Defini - + +When `useBigInt` is set to `true`, a customized JSON serializer & deserializer is used that will preserve the precision of `bigint`'s, as opposed to the native `JSON.stringify` and `JSON.parse` function which converts `bigint`'s to number's losing precision. + +When combining `useBigInt` with our serialization layer (`no-serde: false`), both the request and response properties that are marked as `long` and `bigint` in OpenAPI/Fern spec, will consistently be `bigint`'s. +However, when disabling the serialization layer (`no-serde: true`), they will be typed as `number | bigint`. + +Here's an overview of what to expect from the generated types when combining `useBigInt` and `noSerde` with the following Fern definition: + +*Fern definition*: + +```yaml +types: + ObjectWithOptionalField: + properties: + longProp: long + bigIntProp: bigint +``` + +*TypeScript output*: + +```typescript +// useBigInt: true +// noSerde: false +interface ObjectWithLongAndBigInt { + longProp: bigint; + bigIntProp: bigint; +} + +// useBigInt: true +// noSerde: true +interface ObjectWithLongAndBigInt { + longProp: bigint | number; + bigIntProp: bigint | number; +} + +// useBigInt: false +// noSerde: false +interface ObjectWithLongAndBigInt { + longProp: number; + bigIntProp: string; +} + +// useBigInt: false +// noSerde: true +interface ObjectWithLongAndBigInt { + longProp: number; + bigIntProp: string; +} +``` From 97b4817ee1fca3fdf64010920abd06d1c8049183 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Thu, 3 Jul 2025 15:00:02 -0400 Subject: [PATCH 27/33] update noScripts and includeContentHeadersOnFileDownloadResponse --- .../sdks/pages/typescript/configuration.mdx | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/fern/products/sdks/pages/typescript/configuration.mdx b/fern/products/sdks/pages/typescript/configuration.mdx index cee5af838..f1e206430 100644 --- a/fern/products/sdks/pages/typescript/configuration.mdx +++ b/fern/products/sdks/pages/typescript/configuration.mdx @@ -21,7 +21,7 @@ groups: When enabled, the generator outputs raw TypeScript files. When disabled (the default), outputs `.js` and `d.ts` files. - This only applies when dumping code locally. This configuration is ignored when publishing to Github or npm._ + This only applies when dumping code locally. This configuration is ignored when publishing to Github or npm. @@ -521,6 +521,18 @@ interface ObjectWithLongAndBigInt { ### Beta options + +Includes the content type and content length from binary responses. The user will receive an object of the following type: + +```typescript +{ + data: ; + contentLengthInBytes?: number; + contentType?: string; +} +``` + +`` is `core.BinaryResponse` or a stream, depending on `fileResponseType` setting. @@ -530,5 +542,6 @@ interface ObjectWithLongAndBigInt { +Prevent the generator from running any scripts such as `yarn format` or `yarn install`. If any of the scripts cause errors, toggling this option will allow you to receive the generated code. From 0de0892df51575eec14ceb50a4b9d43a8ed3fbfe Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Thu, 3 Jul 2025 15:06:51 -0400 Subject: [PATCH 28/33] update noSerdeLayer --- .../sdks/pages/typescript/configuration.mdx | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/fern/products/sdks/pages/typescript/configuration.mdx b/fern/products/sdks/pages/typescript/configuration.mdx index f1e206430..855599d93 100644 --- a/fern/products/sdks/pages/typescript/configuration.mdx +++ b/fern/products/sdks/pages/typescript/configuration.mdx @@ -18,7 +18,7 @@ groups: ## SDK configuration options - + When enabled, the generator outputs raw TypeScript files. When disabled (the default), outputs `.js` and `d.ts` files. This only applies when dumping code locally. This configuration is ignored when publishing to Github or npm. @@ -344,20 +344,19 @@ By default, names are based on the organization and API names in the Fern Defini - - By default, the generated client includes a layer for serializing requests and deserializing responses. This has three benefits: + + +No serialization/deserialization code is generated by default. The client uses `JSON.parse()` and `JSON.stringify()` instead of the default Serde layer. + + When `noSerdeLayer: false`, the generated client includes a layer for serializing requests and deserializing responses. This has three benefits: 1. The client validates requests and response at runtime (client-side). 1. The client can support complex types like `Date` and `Set`. 1. The generated types can stray from the wire/JSON representation to be more - idiomatic. For example, when `noSerdeLayer` is disabled, all properties are `camelCase`, - even if the server is expecting `snake_case`. - - When `noSerdeLayer` is enabled, no serialization/deserialization code is generated. The client uses `JSON.parse()` and `JSON.stringify()` instead of the default Serde layer. + idiomatic. For example, when the Serde layer is enabled (`noSerdeLayer: false`), all properties are `camelCase`, even if the server is expecting `snake_case`. - From c26aa5ea125e34ed027496c53ba6186bd4a3e381 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Thu, 3 Jul 2025 15:12:00 -0400 Subject: [PATCH 29/33] update tolerateRepublish --- fern/products/sdks/pages/typescript/configuration.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/fern/products/sdks/pages/typescript/configuration.mdx b/fern/products/sdks/pages/typescript/configuration.mdx index 855599d93..18de5d258 100644 --- a/fern/products/sdks/pages/typescript/configuration.mdx +++ b/fern/products/sdks/pages/typescript/configuration.mdx @@ -130,6 +130,7 @@ config: +Allows npm to overwrite an already-published package version, bypassing npm's default protection against republishing the same version number. From 76584a7f619413481316d34d17ae325f2d4255c1 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Thu, 3 Jul 2025 15:15:29 -0400 Subject: [PATCH 30/33] update treatUnknownAsAny --- fern/products/sdks/pages/typescript/configuration.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fern/products/sdks/pages/typescript/configuration.mdx b/fern/products/sdks/pages/typescript/configuration.mdx index 18de5d258..fc152cae0 100644 --- a/fern/products/sdks/pages/typescript/configuration.mdx +++ b/fern/products/sdks/pages/typescript/configuration.mdx @@ -99,7 +99,7 @@ config: - In Fern, there's an `unknown` type that represents data that isn't knowable at runtime. When `treatUnknownAsAny` is enabled, unknown types from Fern are generated into TypeScript using `any` instead of the `unknown` type. + When `treatUnknownAsAny` is enabled, [unknown types from Fern are generated into TypeScript using `any` instead of the `unknown` type](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-0.html#new-unknown-top-type). From 11cacfd27bb3e2f93c1a068991df3fdc58113c5e Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Thu, 3 Jul 2025 15:23:07 -0400 Subject: [PATCH 31/33] added warning callout to skipResponseValidation --- fern/products/sdks/pages/typescript/configuration.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/fern/products/sdks/pages/typescript/configuration.mdx b/fern/products/sdks/pages/typescript/configuration.mdx index fc152cae0..8ef10ff99 100644 --- a/fern/products/sdks/pages/typescript/configuration.mdx +++ b/fern/products/sdks/pages/typescript/configuration.mdx @@ -45,6 +45,8 @@ Fern Definition). If `skipResponseValidation` is set to `true`, the client will never throw if the response is misshapen. Instead, the client will log the issue using `console.warn` and return the data (casted to the expected response type). +Response validation only occurs when the Serde layer is enabled (`noSerdeLayer: false`). The Serde layer is disabled by default (`noSerdeLayer: true`). + From bd08ff3a7808938397839e136448a9e68e00558f Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Thu, 3 Jul 2025 15:27:38 -0400 Subject: [PATCH 32/33] additional updates --- fern/products/sdks/pages/typescript/configuration.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/fern/products/sdks/pages/typescript/configuration.mdx b/fern/products/sdks/pages/typescript/configuration.mdx index 8ef10ff99..9ab5badf6 100644 --- a/fern/products/sdks/pages/typescript/configuration.mdx +++ b/fern/products/sdks/pages/typescript/configuration.mdx @@ -36,6 +36,7 @@ groups: +The default timeout for network requests. In the generated client, this can be overridden at the request level. From 9b25af24f31c2e98ad5f8ef8872852d66bb77de2 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Mon, 7 Jul 2025 16:28:22 -0400 Subject: [PATCH 33/33] remove tolerateRepublish --- fern/products/sdks/overview/typescript/configuration.mdx | 4 ---- 1 file changed, 4 deletions(-) diff --git a/fern/products/sdks/overview/typescript/configuration.mdx b/fern/products/sdks/overview/typescript/configuration.mdx index 9ab5badf6..a1d06b912 100644 --- a/fern/products/sdks/overview/typescript/configuration.mdx +++ b/fern/products/sdks/overview/typescript/configuration.mdx @@ -132,10 +132,6 @@ config: ``` - -Allows npm to overwrite an already-published package version, bypassing npm's default protection against republishing the same version number. - - When you specify an object in `packageJson`, it will be merged into the `package.json` file.