Skip to content

Commit c614aa7

Browse files
committed
Update configuration.mdx based on issue #266
1 parent d3ab793 commit c614aa7

File tree

1 file changed

+34
-122
lines changed

1 file changed

+34
-122
lines changed

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

Lines changed: 34 additions & 122 deletions
Original file line numberDiff line numberDiff line change
@@ -130,9 +130,11 @@ Specify extra peer dependencies meta fields in the generated `package.json`:
130130
```yaml
131131
# generators.yml
132132
config:
133-
extraPeerDependencies:
134-
react: ">=16.8.0 <19.0.0"
135-
"react-dom": ">=16.8.0 <19.0.0"
133+
extraPeerDependenciesMeta:
134+
react:
135+
optional: true
136+
"react-dom":
137+
optional: true
136138
```
137139
</ParamField>
138140

@@ -411,134 +413,44 @@ generate a `jsr.json` as well as a GitHub workflow to publish to JSR.
411413

412414
</ParamField>
413415

414-
<ParamField path="shouldGenerateWebsocketClients" type="boolean" toc={true}>
415-
Generate WebSocket clients from your AsyncAPI specs.
416-
</ParamField>
417-
418-
<ParamField path="skipResponseValidation" type="boolean" default="false" toc={true}>
419-
By default, the client will throw an error if the response from the server
420-
doesn't match the expected type (based on how the response is modeled in the
421-
Fern Definition).
422-
423-
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).
424-
425-
<Warning>Response validation only occurs when the Serde layer is enabled (`noSerdeLayer: false`). The Serde layer is disabled by default (`noSerdeLayer: true`).</Warning>
426-
427-
</ParamField>
428-
429-
<ParamField path="streamType" type="'wrapper' | 'web'" toc={true}>
430-
Change the type of stream that is used in the generated SDK.
431-
432-
* `wrapper`: The streams use a wrapper with multiple underlying implementations to support versions of Node.js before Node.js 18.
433-
* `web`: The streams use the web standard `ReadableStream`.
434-
435-
The default is `web`.
436-
</ParamField>
437-
438-
<ParamField path="treatUnknownAsAny" type="boolean" default="false" toc={true}>
439-
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).
440-
</ParamField>
441-
442-
<ParamField path="useBigInt" type="boolean" default="false" toc={true}>
443-
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.
444-
445-
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.
446-
However, when disabling the serialization layer (`no-serde: true`), they will be typed as `number | bigint`.
416+
<ParamField path="sdkVariables" type="Record<string, boolean>" toc={true}>
417+
Configures SDK variables that can be set at client initialization time and will be injected into endpoints when needed. Each variable name maps to a boolean indicating whether it is required.
447418

448-
Here's an overview of what to expect from the generated types when combining `useBigInt` and `noSerde` with the following Fern definition:
419+
```yaml
420+
# generators.yml
421+
config:
422+
sdkVariables:
423+
project_id: true # Required variable
424+
tenant_id: false # Optional variable
425+
```
449426

450-
*Fern definition*:
427+
The variables will be injected into endpoints based on their declaration in your OpenAPI or Fern definition (via `x-fern-sdk-variables`). For example:
451428

452429
```yaml
453-
types:
454-
ObjectWithOptionalField:
455-
properties:
456-
longProp: long
457-
bigIntProp: bigint
430+
# OpenAPI
431+
x-fern-sdk-variables:
432+
project_id:
433+
type: string
434+
description: "The project ID to use"
435+
pattern: "^proj_[a-zA-Z0-9]+$"
458436
```
459437

460-
*TypeScript output*:
438+
Generated client:
461439

462440
```typescript
463-
// useBigInt: true
464-
// noSerde: false
465-
interface ObjectWithLongAndBigInt {
466-
longProp: bigint;
467-
bigIntProp: bigint;
468-
}
469-
470-
// useBigInt: true
471-
// noSerde: true
472-
interface ObjectWithLongAndBigInt {
473-
longProp: bigint | number;
474-
bigIntProp: bigint | number;
475-
}
476-
477-
// useBigInt: false
478-
// noSerde: false
479-
interface ObjectWithLongAndBigInt {
480-
longProp: number;
481-
bigIntProp: string;
482-
}
483-
484-
// useBigInt: false
485-
// noSerde: true
486-
interface ObjectWithLongAndBigInt {
487-
longProp: number;
488-
bigIntProp: string;
489-
}
441+
const client = new Client({
442+
// Required variable
443+
project_id: "proj_123",
444+
// Optional variable
445+
tenant_id: "tenant_456"
446+
});
490447
```
491448
</ParamField>
492449

493-
<ParamField path="useBrandedStringAliases" type="boolean" default="false" toc={true}>
494-
495-
When `useBrandedStringAliases` is disabled (the default), string aliases are generated as
496-
normal TypeScript aliases:
497-
498-
```typescript
499-
// generated code
500-
501-
export type MyString = string;
502-
503-
export type OtherString = string;
504-
```
505-
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.
506-
507-
```yaml
508-
# fern definition
509-
510-
types:
511-
MyString: string
512-
OtherString: string
513-
```
514-
515-
```typescript
516-
// generated code
517-
518-
export type MyString = string & { __MyString: void };
519-
export const MyString = (value: string): MyString => value as MyString;
520-
521-
export type OtherString = string & { __OtherString: void };
522-
export const OtherString = (value: string): OtherString => value as OtherString;
523-
```
524-
525-
```typescript
526-
// consuming the generated type
527-
528-
function printMyString(s: MyString): void {
529-
console.log("MyString: " + s);
530-
}
531-
532-
// doesn't compile, "foo" is not assignable to MyString
533-
printMyString("foo");
534-
535-
const otherString = OtherString("other-string");
536-
// doesn't compile, otherString is not assignable to MyString
537-
printMyString(otherString);
538-
539-
// compiles
540-
const myString = MyString("my-string");
541-
printMyString(myString);
542-
```
450+
<ParamField path="shouldGenerateWebsocketClients" type="boolean" toc={true}>
451+
Generate WebSocket clients from your AsyncAPI specs.
452+
</ParamField>
543453

544-
</ParamField>
454+
<ParamField path="skipResponseValidation" type="boolean" default="false" toc={true}>
455+
By default, the client will throw an error if the response from the server
456+
doesn't match the expected type (based on how

0 commit comments

Comments
 (0)