From c5c3acc332fdbcb67c92aec2ba3c2c74f7469813 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Thu, 28 Aug 2025 14:02:28 -0400 Subject: [PATCH] add new page on serde layer --- .../overview/typescript/configuration.mdx | 34 ++++++------ .../sdks/overview/typescript/serde-layer.mdx | 52 +++++++++++++++++++ fern/products/sdks/sdks.yml | 3 ++ 3 files changed, 70 insertions(+), 19 deletions(-) create mode 100644 fern/products/sdks/overview/typescript/serde-layer.mdx diff --git a/fern/products/sdks/overview/typescript/configuration.mdx b/fern/products/sdks/overview/typescript/configuration.mdx index 283f32dd1..87dd16afe 100644 --- a/fern/products/sdks/overview/typescript/configuration.mdx +++ b/fern/products/sdks/overview/typescript/configuration.mdx @@ -5,21 +5,24 @@ description: Configuration options for the Fern TypeScript SDK. You can customize the behavior of the TypeScript SDK generator in `generators.yml`: -```yml {7-8} title="generators.yml" +```yml {7-9} title="generators.yml" default-group: local groups: - local: + ts-sdk: generators: - name: fernapi/fern-typescript-sdk version: config: namespaceExport: Acme + noSerdeLayer: false ``` ## SDK configuration options Allow fields that are not defined in object schemas. This only applies to serde. + +See [TypeScript serde layer](/sdks/generators/typescript/serde-layer) for more information. @@ -323,18 +326,11 @@ Prevent the generator from running any scripts such as `yarn format` or `yarn in +Controls whether the serde layer is enabled for serialization/deserialization. -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 the Serde layer is enabled (`noSerdeLayer: false`), all properties are `camelCase`, even if the server is expecting `snake_case`. +When `noSerdeLayer: false`, the generated client includes custom serialization code that transforms property names to camelCase, validates requests/responses at runtime, and supports complex types. +See [TypeScript serde layer](/sdks/generators/typescript/serde-layer) for detailed guidance on when to enable this option. @@ -444,10 +440,10 @@ The default is `web`. 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`. +When combining `useBigInt` with our serialization layer (`noSerdeLayer: 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 (`noSerdeLayer: true`), they will be typed as `number | bigint`. See [TypeScript serde layer](/sdks/generators/typescript/serde-layer) for more information. -Here's an overview of what to expect from the generated types when combining `useBigInt` and `noSerde` with the following Fern definition: +Here's an overview of what to expect from the generated types when combining `useBigInt` and `noSerdeLayer` with the following Fern definition: *Fern definition*: @@ -463,28 +459,28 @@ types: ```typescript // useBigInt: true -// noSerde: false +// noSerdeLayer: false interface ObjectWithLongAndBigInt { longProp: bigint; bigIntProp: bigint; } // useBigInt: true -// noSerde: true +// noSerdeLayer: true interface ObjectWithLongAndBigInt { longProp: bigint | number; bigIntProp: bigint | number; } // useBigInt: false -// noSerde: false +// noSerdeLayer: false interface ObjectWithLongAndBigInt { longProp: number; bigIntProp: string; } // useBigInt: false -// noSerde: true +// noSerdeLayer: true interface ObjectWithLongAndBigInt { longProp: number; bigIntProp: string; diff --git a/fern/products/sdks/overview/typescript/serde-layer.mdx b/fern/products/sdks/overview/typescript/serde-layer.mdx new file mode 100644 index 000000000..455d86b7a --- /dev/null +++ b/fern/products/sdks/overview/typescript/serde-layer.mdx @@ -0,0 +1,52 @@ +--- +title: TypeScript serde layer +description: Control how your API naming conventions are transformed in the generated TypeScript SDK +--- + +Fern's TypeScript SDK generator includes an optional serde layer that determines whether the generated SDK matches your original API naming conventions (snake_case vs. camelCase, case-sensitive fields) or follows TypeScript conventions. This serde layer is controlled by the `noSerdeLayer` option. + +By default, the serde layer is **disabled** (`noSerdeLayer: true`), meaning field names are preserved exactly as they appear in your API specification. + +## When to enable the serde layer + +```yaml title="generators.yml" {7} +groups: + ts-sdk: + generators: + - name: fernapi/fern-typescript-sdk + version: + config: + noSerdeLayer: false # Enable serde layer +``` + +When you turn on the serde layer, (`noSerdeLayer: false`), the TypeScript SDK generator includes custom serialization code that: +- Transforms all property names from your API to camelCase +- Validates requests and responses at runtime +- Supports complex types like `Date` and `Set`. + +Enable the serde layer when you want idiomatic TypeScript conventions and don't have case-sensitive field conflicts. Keep it disabled when your API has fields that differ only by casing or when you need exact field name preservation. + +## Additional configuration options + +Several configuration options work alongside an enabled serde layer: +- `skipResponseValidation` disables the serde layer's runtime validation while keeping its transformation features +- `allowExtraFields` permits properties not defined in your schema. +- `useBigInt` enables custom JSON handling to preserve large number precision. + +These options only take effect when the serde layer is enabled (`noSerdeLayer: false`), as they require the custom serialization infrastructure. + +```yaml title="generators.yml" {7-10} +groups: + ts-sdk: + generators: + - name: fernapi/fern-typescript-sdk + version: + config: + noSerdeLayer: false # Enable serde layer + skipResponseValidation: true # Disable runtime validation errors + allowExtraFields: true # Allow undefined fields in responses + useBigInt: true # Preserve precision for large numbers +``` + +For the complete list of all TypeScript configuration options, go to [TypeScript configuration](/sdks/generators/typescript/configuration). + diff --git a/fern/products/sdks/sdks.yml b/fern/products/sdks/sdks.yml index 20087f696..8f216bc14 100644 --- a/fern/products/sdks/sdks.yml +++ b/fern/products/sdks/sdks.yml @@ -39,6 +39,9 @@ navigation: - page: Adding custom code path: ./overview/typescript/custom-code.mdx slug: custom-code + - page: Enabling the serde layer + path: ./overview/typescript/serde-layer.mdx + slug: serde-layer - changelog: ./overview/typescript/changelog slug: changelog - link: Customer showcase