add new page on serde layer

Author: devalog

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: <Markdown src="/snippets/version-number-ts.mdx"/>
         config:
           namespaceExport: Acme
+		  noSerdeLayer: false
 ```
 
 ## SDK configuration options
 
 <ParamField path="allowExtraFields" type="boolean" toc={true}>
 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.
 </ParamField>
 
 <ParamField path="bundle" type="boolean" toc={true}>
@@ -323,18 +326,11 @@ Prevent the generator from running any scripts such as `yarn format` or `yarn in
 </ParamField>
 
 <ParamField path="noSerdeLayer" type="boolean" default="true" toc={true}>
+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.
 </ParamField>
 
 <ParamField path="outputSourceFiles" type="boolean" default="true" toc={true}>
@@ -444,10 +440,10 @@ The default is `web`.
 <ParamField path="useBigInt" type="boolean" default="false" toc={true}>
 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;

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: <Markdown src="/snippets/version-number-ts.mdx"/>
+      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: <Markdown src="/snippets/version-number-ts.mdx"/>
+      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).
+

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