Skip to content

Commit c6078c0

Browse files
devalogdevalog
committed
Add in AsyncAPI flow, outputSourceFiles option, and --organization flag
1 parent ff36f1a commit c6078c0

File tree

2 files changed

+230
-33
lines changed

2 files changed

+230
-33
lines changed

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

Lines changed: 141 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,145 @@ title: Typescript Configuration
33
description: Configuration options for the Fern Typescript SDK.
44
---
55

6-
# Typescript Configuration
6+
Configure the Fern Typescript SDK for your project.
7+
8+
9+
You can customize the behavior of generators in `generators.yml`:
10+
11+
```yml
12+
default-group: local
13+
groups:
14+
local:
15+
generators:
16+
- name: fernapi/fern-typescript-node-sdk
17+
version: 0.7.1
18+
config:
19+
useBrandedStringAliases: true
20+
```
21+
22+
### SDK Configuration
23+
24+
The SDK generator support the following parameters:
25+
26+
27+
<ParamField path="useBrandedStringAliases" type="boolean" default="false">
28+
When enabled, string aliases are generated as branded strings. This makes each alias feel like its own type and improves compile-time safety.
29+
30+
```yaml
31+
# fern definition
32+
33+
types:
34+
MyString: string
35+
OtherString: string
36+
```
37+
38+
```typescript
39+
// generated code
40+
41+
export type MyString = string & { __MyString: void };
42+
export const MyString = (value: string): MyString => value as MyString;
43+
44+
export type OtherString = string & { __OtherString: void };
45+
export const OtherString = (value: string): OtherString => value as OtherString;
46+
```
47+
48+
```typescript
49+
// consuming the generated type
50+
51+
function printMyString(s: MyString): void {
52+
console.log("MyString: " + s);
53+
}
54+
55+
// doesn't compile, "foo" is not assignable to MyString
56+
printMyString("foo");
57+
58+
const otherString = OtherString("other-string");
59+
// doesn't compile, otherString is not assignable to MyString
60+
printMyString(otherString);
61+
62+
// compiles
63+
const myString = MyString("my-string");
64+
printMyString(myString);
65+
```
66+
67+
When `useBrandedStringAliases` is disabled (the default), string aliases are generated as
68+
normal TypeScript aliases:
69+
70+
```typescript
71+
// generated code
72+
73+
export type MyString = string;
74+
75+
export type OtherString = string;
76+
```
77+
</ParamField>
78+
79+
<ParamField path="neverThrowErrors" type="boolean" default="false">
80+
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).
81+
82+
```typescript
83+
const response = await client.callEndpoint(...);
84+
if (response.ok) {
85+
console.log(response.body)
86+
} else {
87+
console.error(respons.error)
88+
}
89+
```
90+
</ParamField>
91+
92+
<ParamField path="namespaceExport" type="string">
93+
Customizes the exported namespace and client names. By default, names are based on the organization and API names in the Fern Definition.
94+
</ParamField>
95+
96+
<ParamField path="outputEsm" type="boolean" default="false">
97+
By default, the generated TypeScript targets CommonJS. Set to true to target esnext instead.
98+
</ParamField>
99+
100+
<ParamField path="outputSourceFiles" type="boolean" default="false">
101+
When enabled, the generator outputs raw TypeScript files. When disabled (the default), outputs .js and d.ts files. Note: Only applies when dumping code locally.
102+
</ParamField>
103+
104+
<ParamField path="includeCredentialsOnCrossOriginRequests" type="boolean" default="false">
105+
When enabled, withCredentials is set to true when making network requests.
106+
</ParamField>
107+
108+
<ParamField path="allowCustomFetcher" type="boolean" default="false">
109+
When enabled, the generated client allows the end user to specify a custom fetcher implementation.
110+
</ParamField>
111+
112+
<ParamField path="requireDefaultEnvironment" type="boolean" default="false">
113+
When enabled, the generated client doesn't allow the user to specify a server URL.
114+
</ParamField>
115+
116+
<ParamField path="defaultTimeoutInSeconds" type="number" default="60">
117+
The default timeout for network requests. In the generated client, this can be overridden at the request level.
118+
</ParamField>
119+
120+
<ParamField path="skipResponseValidation" type="boolean" default="false">
121+
By default, the client will throw an error if the response from the server doesn't match the expected type. If enabled, the client will log issues using console.warn and return the data casted to the expected response type.
122+
</ParamField>
123+
124+
<ParamField path="extraDependencies" type="object" default="{}">
125+
Specify extra dependencies in the generated package.json. Useful when utilizing .fernignore to supplement the generated client with custom code. Note: Only applies when publishing to Github.
126+
</ParamField>
127+
128+
<ParamField path="extraDevDependencies" type="object" default="{}">
129+
Specify extra dev dependencies in the generated package.json. Note: Only applies when publishing to Github.
130+
</ParamField>
131+
132+
<ParamField path="treatUnknownAsAny" type="boolean" default="false">
133+
When enabled, unknown types from Fern are generated into TypeScript using any instead of the unknown type.
134+
</ParamField>
135+
136+
<ParamField path="noSerdeLayer" type="boolean" default="false">
137+
When enabled, no serialization/deserialization code is generated. The client uses JSON.parse() and JSON.stringify() instead of the default serde layer that provides validation and complex type support.
138+
</ParamField>
139+
140+
<ParamField path="noOptionalProperties" type="boolean" default="false">
141+
When enabled, optional properties are generated with | undefined instead of optional TypeScript properties (using ?).
142+
</ParamField>
143+
144+
<ParamField path="retainOriginalCasing" type="boolean" default="false">
145+
When enabled, property names in the generated code will retain their original casing from the API definition instead of being converted to camelCase.
146+
</ParamField>
7147

8-
Discover how to configure the Fern Typescript SDK for your project.

‎fern/products/sdks/pages/typescript/quickstart.mdx‎

Lines changed: 89 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -22,35 +22,35 @@ Generate a TypeScript SDK by following the instructions on this page.
2222

2323
### Initialize the Fern Folder
2424

25-
You can use either the OpenAPI definition or Fern Definition to generate your SDK.
25+
You can use either the OpenAPI definition, AsyncAPI definition, or Fern Definition to generate your SDK.
2626

2727
<AccordionGroup>
28-
<Accordion title="Option 1: OpenAPI">
29-
Initialize the Fern folder using your OpenAPI Specification. Run one of the following commands based on your spec's location:
28+
<Accordion title="Option 1: OpenAPI">
29+
Initialize the Fern folder using your OpenAPI Specification. Run one of the following commands based on your spec's location.
3030

3131
<Tip>
3232
Fern can handle both JSON and YML formats for OpenAPI specifications, and the --openapi flag accepts either format, so you can use whichever format your API spec is available in.
3333
</Tip>
3434

35+
<Info>
36+
`--organization <YourOrganization>` configures your organization name in `fern.config.json`. This is required in order to successfully generate your SDK.
37+
</Info>
38+
3539
<CodeBlocks>
3640

3741
<CodeBlock title="Local file">
3842
```bash
39-
fern init --openapi path/to/openapi.yml
43+
fern init --openapi path/to/openapi.yml --organization <YourOrganization>
4044
```
4145
</CodeBlock>
4246

4347
<CodeBlock title="Web-hosted file">
4448
```bash
45-
fern init --openapi https://api.example.com/openapi.yml
49+
fern init --openapi https://api.example.com/openapi.yml --organization <YourOrganization>
4650
```
4751
</CodeBlock>
4852

49-
</CodeBlocks>
50-
51-
<Info>
52-
Enter your organization name when prompted. The organization name must be configured in `fern.config.json` in order to successfully generate your SDK.
53-
</Info>
53+
</CodeBlocks>
5454

5555
This creates a `fern` folder in your current directory with the OpenAPI Specification. The exact folder structure might look different depending on your initial input files.
5656

@@ -63,33 +63,91 @@ Generate a TypeScript SDK by following the instructions on this page.
6363
├─ openapi.yml # API-level configuration
6464
```
6565
</Accordion>
66-
<Accordion title="Option 2: Fern Definition">
66+
<Accordion title="Option 2: AsyncAPI">
67+
Initialize the Fern folder using your AsyncAPI Specification. Run one of the following commands based on your spec's location.
6768

68-
Initialize the Fern folder using the Fern Definition by running the following command:
69+
<Tip>
70+
Fern can handle both JSON and YML formats for AsyncAPI specifications, and the --openapi flag accepts either format, so you can use whichever format your API spec is available in.
71+
</Tip>
6972

70-
```bash
71-
fern init
72-
```
7373
<Info>
74-
Enter your organization name when prompted. The organization name must be configured in `fern.config.json` in order to sucessfully generate your SDK.
74+
`--organization <YourOrganization>` configures your organization name in `fern.config.json`. This is required in order to successfully generate your SDK.
7575
</Info>
7676

77-
This creates a `fern` folder in your current directory with the Fern Definition.
77+
<CodeBlocks>
78+
79+
<CodeBlock title="Local file">
80+
```bash
81+
fern init --asyncapi path/to/asyncapi.yml --organization <YourOrganization>
82+
```
83+
</CodeBlock>
84+
85+
<CodeBlock title="Web-hosted file">
86+
```bash
87+
fern init --asyncapi https://api.example.com/asyncapi.yml --organization <YourOrganization>
88+
```
89+
</CodeBlock>
90+
91+
</CodeBlocks>
92+
93+
This creates a `fern` folder in your current directory with the AsyncAPI Specification. The exact folder structure might look different depending on your initial input files.
7894

7995
```bash
8096
fern/
8197
├─ fern.config.json # root-level configuration
82-
├─ generators.yml # generators you're using
83-
└─ definition/
84-
├─ api.yml # API-level configuration
85-
└─ imdb.yml # endpoints, types, and errors
98+
└─ api/ # your API
99+
├─ generators.yml # generators you're using
100+
└─ openapi/
101+
├─ openapi.yml # API-level configuration
86102
```
103+
</Accordion>
104+
<Accordion title="Option 3: Fern Definition">
105+
106+
1. Initialize the Fern folder using the Fern Definition by running the following command:
107+
108+
```bash
109+
fern init --organization <YourOrganization>
110+
```
111+
112+
<Info>
113+
`--organization <YourOrganization>` configures your organization name in `fern.config.json`. This is required in order to successfully generate your SDK.
114+
</Info>
115+
116+
This creates a `fern` folder in your current directory with the Fern Definition.
117+
118+
```bash
119+
fern/
120+
├─ fern.config.json # root-level configuration
121+
├─ generators.yml # generators you're using
122+
└─ definition/
123+
├─ api.yml # API-level configuration
124+
└─ imdb.yml # endpoints, types, and errors
125+
```
126+
127+
<Note>
128+
`imdb.yml` contains an example movies API. If you’re just generating an SDK for test purposes, you can leave this file as it is. To generate an SDK for your own API instead of the example movies API, replace `imdb.yml` with your own endpoints, types, and errors before proceeding with the rest of this page.
129+
</Note>
130+
131+
{/* TODO: show want generators.yml looks like, link out to configuration.md */}
132+
133+
1. Add the config option `outputSourceFiles: true` to `generators.yml`. This ensures your SDK contains `.ts` files instead of compiled output.
134+
135+
```yaml {11-12}
136+
# yaml-language-server: $schema=https://schema.buildwithfern.dev/generators-yml.json
137+
default-group: local
138+
groups:
139+
local:
140+
generators:
141+
- name: fernapi/fern-typescript-node-sdk
142+
output:
143+
location: local-file-system
144+
path: ../sdks/typescript
145+
version: 1.10.1
146+
config:
147+
outputSourceFiles: true
148+
```
87149
88-
<Note>
89-
`imdb.yml` contains an example movies API. If you’re just generating an SDK for test purposes, you can leave this file as it is. To generate an SDK for your own API instead of the example movies API, replace `imdb.yml` with your own endpoints, types, and errors before proceeding with the rest of this page.
90-
</Note>
91150
92-
{/* TODO: show want generators.yml looks like, link out to configuration.md */}
93151
94152
95153
</Accordion>
@@ -117,12 +175,12 @@ Generate a TypeScript SDK by following the instructions on this page.
117175

118176
```yaml
119177
sdk:
120-
generators:
121-
- name: fernapi/fern-typescript-node-sdk
122-
version: 1.10.1
123-
output:
124-
location: local-file-system
125-
path: ../sdks/typescript
178+
generators:
179+
- name: fernapi/fern-typescript-node-sdk
180+
version: 1.10.1
181+
output:
182+
location: local-file-system
183+
path: ../sdks/typescript
126184
```
127185
### Generate the SDK
128186

0 commit comments

Comments
 (0)