Add TypeScript configuration options

fern/products/sdks/pages/typescript/configuration.mdx

@@ -3,6 +3,360 @@ title: Typescript Configuration
 description: Configuration options for the Fern Typescript SDK.
 ---
 
-# Typescript Configuration
+You can customize the behavior of the TypeScript SDK generator in `generators.yml`:
+
+```yml {7-8}
+default-group: local
+groups:
+  local:
+    generators:
+      - name: fernapi/fern-typescript-node-sdk
+        version: 0.7.1
+        config:
+          useBrandedStringAliases: true
+```
+
+## SDK configuration options
+
+<ParamField path="neverThrowErrors" type="boolean">
+</ParamField>
+
+<ParamField path="outputEsm" type="boolean" default="false">
+  By default, the generated TypeScript targets CommonJS. Setting to `true` targets `esnext` instead.
+</ParamField>
+
+<ParamField path="outputSourceFiles" type="boolean" default="false">
+  When enabled, the generator outputs raw TypeScript files. When disabled (the default), outputs `.js` and `d.ts` files. 
+
+  <Note>This only applies when dumping code locally. This configuration is ignored when publishing to Github or npm._ </Note>
+</ParamField>
+
+<ParamField path="includeCredentialsOnCrossOriginRequests" type="boolean" default="false">
+  When enabled, [`withCredentials`](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest/withCredentials) is set to `true` when making network requests.
+</ParamField>
+
+<ParamField path="bundle" type="boolean">
+</ParamField>
+
+<ParamField path="allowCustomFetcher" type="boolean" default="false">
+  When enabled, the generated client allows the end user to specify a custom fetcher implementation.
+
+  ```typescript
+	const acme = new AcmeClient({
+	  fetcher: (args) => {
+	    ...
+	  },
+	});
+	```
+</ParamField>
+
+<ParamField path="shouldGenerateWebsocketClients" type="boolean">
+</ParamField>
+
+<ParamField path="defaultTimeoutInSeconds" type="number | 'infinity'">
+</ParamField>
+
+<ParamField path="skipResponseValidation" type="boolean" default="false">
+ 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 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).
+
+</ParamField>
+
+<ParamField path="extraDependencies" type="object" default="{}">
+  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. 
+
+```yaml
+# generators.yml
+config:
+  extraDependencies:
+    lodash: "3.0.2"
+```
+
+</ParamField>
+
+<ParamField path="extraDevDependencies" type="object" default="{}">
+  Specify extra dev dependencies in the generated `package.json`. 
+
+```yaml
+# generators.yml
+config:
+  extraDevDependencies:
+    jest: "29.0.7"
+```
+
+<Note>Only applies when publishing to Github.</Note>
+</ParamField>
+
+<ParamField path="extraPeerDependencies" type="object">
+</ParamField>
+
+<ParamField path="extraPeerDependenciesMeta" type="object">
+</ParamField>
+
+<ParamField path="treatUnknownAsAny" type="boolean" default="false">
+  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.
+</ParamField>
+
+<ParamField path="noOptionalProperties" type="boolean" default="false">
+  By default, Fern's `optional<>` properties will translate to optional TypeScript properties:
+
+	```yaml {4}
+	Person:
+	  properties:
+	    name: string
+	    age: optional<integer>
+	```
+
+	```typescript {3}
+	interface Person {
+	  name: string;
+	  age?: number;
+	}
+	```
+
+	When `noOptionalProperties` is enabled, the generated properties are never optional. Instead, the type is generated with `| undefined`:
+
+	```typescript {3}
+	interface Person {
+	  name: string;
+	  age: number | undefined;
+	}
+	```
+</ParamField>
+
+<ParamField path="tolerateRepublish" type="boolean">
+</ParamField>
+
+<ParamField path="packageJson" type="object">
+</ParamField>
+
+<ParamField path="publishToJsr" type="boolean">
+</ParamField>
+
+<ParamField path="omitUndefined" type="boolean">
+</ParamField>
+
+<ParamField path="useLegacyExports" type="boolean">
+</ParamField>
+
+<ParamField path="streamType" type="'wrapper' | 'web'">
+</ParamField>
+
+<ParamField path="fileResponseType" type="'stream' | 'binary-response'">
+</ParamField>
+
+<ParamField path="formDataSupport" type="'Node16' | 'Node18'">
+</ParamField>
+
+<ParamField path="fetchSupport" type="'node-fetch' | 'native'">
+</ParamField>
+
+<ParamField path="packagePath" type="string">
+</ParamField>
+
+### Options relevant to dynamic snippets
+
+<ParamField path="allowExtraFields" type="boolean">
+
+</ParamField>
+
+<ParamField path="enableInlineTypes" type="boolean">
+</ParamField>
+
+<ParamField path="inlineFileProperties" type="boolean">
+</ParamField>
+
+<ParamField path="inlinePathParameters" type="boolean">
+</ParamField>
+
+<ParamField path="namespaceExport" type="string">
+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";
+	```
+
+</ParamField>
+
+<ParamField path="noSerdeLayer" type="boolean" default="false">
+ 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 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. 
+
+
+</ParamField>
+
+<ParamField path="private" type="boolean">
+</ParamField>
+
+<ParamField path="requireDefaultEnvironment" type="boolean" default="false">
+  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"
+	});
+	```
+</ParamField>
+
+<ParamField path="retainOriginalCasing" type="boolean" default="false">
+  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
+	```
+
+	**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;
+	}
+	```
+
+</ParamField>
+
+<ParamField path="useBigInt" type="boolean">
+</ParamField>
+
+<ParamField path="useBrandedStringAliases" type="boolean" default="false">
+
+	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 `useBrandedStringAliases` is 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);
+	```
+
+</ParamField>
+
+<ParamField path="neverThrowErrors" type="boolean" default="false">
+  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)
+  }
+  ```
+</ParamField>
+
+### Beta options
+
+<ParamField path="includeContentHeadersOnFileDownloadResponse" type="boolean">
+</ParamField>
+
+<ParamField path="includeUtilsOnUnionMembers" type="boolean">
+</ParamField>
+
+<ParamField path="includeOtherInUnionTypes" type="boolean">
+</ParamField>
+
+<ParamField path="generateWireTests" type="boolean">
+</ParamField>
+
+<ParamField path="noScripts" type="boolean">
+</ParamField>
+
+### Deprecated options
+
+<ParamField path="timeoutInSeconds" type="number | 'infinity'" deprecated={true}>
+The default timeout for network requests. In the generated client, this can be overridden at the request level.
+</ParamField>
+
+<ParamField path="includeApiReference" type="boolean" deprecated={true}>
+</ParamField>
 
-Discover how to configure the Fern Typescript SDK for your project.