Skip to content

🌿 Fern Scribe: Add a comprehensive list of all extension headers... #270

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 2 commits into from
Closed

🌿 Fern Scribe: Add a comprehensive list of all extension headers... #270

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c642ad4
Update configuration.mdx based on issue #266
kgowru Jul 31, 2025
e943664
Update configuration.mdx based on issue #266
kgowru Jul 31, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions fern/products/sdks/overview/python/configuration.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -127,6 +127,16 @@ groups:
<ParamField path="pyproject_toml" type="string" default="null" required={false} toc={true}>
</ParamField>

<ParamField path="sdk_header_extensions" type="object" default="{}" required={false} toc={true}>
Allows configuring headers at SDK generation time. Set header keys to values that should be included in SDK requests. For example:
```yaml
config:
sdk_header_extensions:
x-fern-sdk-name: my-company-python
x-api-version: v2
```
</ParamField>

<ParamField path="should_generate_websocket_clients" type="bool" default="false" required={false} toc={true}>
Feature flag that enables generation of Python websocket clients.
</ParamField>
Expand Down
152 changes: 30 additions & 122 deletions fern/products/sdks/overview/typescript/configuration.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -130,9 +130,11 @@ 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"
extraPeerDependenciesMeta:
react:
optional: true
"react-dom":
optional: true
```
</ParamField>

Expand Down Expand Up @@ -411,134 +413,40 @@ generate a `jsr.json` as well as a GitHub workflow to publish to JSR.

</ParamField>

<ParamField path="shouldGenerateWebsocketClients" type="boolean" toc={true}>
Generate WebSocket clients from your AsyncAPI specs.
</ParamField>

<ParamField path="skipResponseValidation" type="boolean" default="false" toc={true}>
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).

<Warning>Response validation only occurs when the Serde layer is enabled (`noSerdeLayer: false`). The Serde layer is disabled by default (`noSerdeLayer: true`).</Warning>

</ParamField>

<ParamField path="streamType" type="'wrapper' | 'web'" toc={true}>
Change the type of stream that is used in the generated SDK.
<ParamField path="sdkClientVariable" type="string" toc={true}>
When set on OpenAPI spec, this variable will be injected into paths during request construction. For example:

* `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`.
</ParamField>

<ParamField path="treatUnknownAsAny" type="boolean" default="false" toc={true}>
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).
</ParamField>

<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`.

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
# generators.yml
config:
sdkClientVariable: project_id
```

```yaml
types:
ObjectWithOptionalField:
properties:
longProp: long
bigIntProp: bigint
# OpenAPI spec
x-fern-sdk-variables:
project_id:
type: string
description: The project ID
pattern: "^proj_[a-zA-Z0-9]+$"
```

*TypeScript output*:
This allows injecting variables like project_id from the client constructor instead of requiring it on each request:

```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;
}
const client = new ApiClient({ projectId: "proj_123" });
// project_id automatically injected into path
await client.getResource(...);
```
</ParamField>

<ParamField path="useBrandedStringAliases" type="boolean" default="false" toc={true}>

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);
<ParamField path="shouldGenerateWebsocketClients" type="boolean" toc={true}>
Generate WebSocket clients from your AsyncAPI specs.
</ParamField>

// compiles
const myString = MyString("my-string");
printMyString(myString);
```
<ParamField path="skipResponseValidation" type="boolean" default="false" toc={true}>
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).

</ParamField>
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
Loading