From 45d9e59eb43949dc3f24dbccaf2ca91c07935883 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Mon, 30 Jun 2025 13:59:35 -0400 Subject: [PATCH 1/6] Add revamped Typescript Quickstart page --- fern/.DS_Store | Bin 10244 -> 10244 bytes fern/products/.DS_Store | Bin 6148 -> 6148 bytes .../sdks/pages/typescript/quickstart.mdx | 134 +++++++++++++++++- 3 files changed, 132 insertions(+), 2 deletions(-) diff --git a/fern/.DS_Store b/fern/.DS_Store index 65df61554b66ef517366f577c4b8c49c2c1ded69..7e6fab691ba7e8594cc0870746d0f5181004364f 100644 GIT binary patch delta 97 zcmZn(XbG6$&&abeU^hP_&t@Kh1MDKK3_F#mPze`8kY}7fOgszAJu% U6E3oOp@b3pW_E?6cr^$B0J_K?MgRZ+ delta 40 ucmZn(XbG6$&&ahgU^hP_*Jd7p1MHI@i@)6bQbLY>VuQ(Mc7>xL0Sf>vf)4%w diff --git a/fern/products/.DS_Store b/fern/products/.DS_Store index 1e68400848f83ebc7e7f678596e804938a48bb8e..16e7044e450fadd8957014bdc8634ac9264b2f3c 100644 GIT binary patch delta 80 zcmZoMXfc=|#>B`mu~2NHo+2a5!~p9_j154#Cqs~hp_n0sA)BE%Eu}a)DL+4FCJ*u~2NHo+2aj!~knX=E*#a8Jjy9>)0kQV4S*{or9kPsABU(#_!CN T`9%yF87ABCNN + Generating SDKs often requires understanding the state of your OpenAPI Specification as well as + your specific requirements. For the ideal experience, we **strongly recommend** scheduling a + [demo](https://buildwithfern.com/contact) or [emailing us](mailto:support@buildwithfern.com) to get started. + -Follow these steps to quickly get up and running with the Fern Typescript SDK. \ No newline at end of file +Generate a Typescript SDK by following the instructions on this page. + + + ### Install the Fern CLI + + Run the following command to install the CLI tool or update it to the latest version: + + ```bash + npm install -g fern-api + ``` + + ### Initialize the Fern Folder + + You can use either the Open API definition or Fern Definition to generate your SDK. + + + + Initialize the Fern folder using your OpenAPI Specification. Run one of the following commands based on your spec's location: + + + 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. + + + + + + ```bash + fern init --openapi path/to/openapi.yml + ``` + + + + ```bash + fern init --openapi https://api.example.com/openapi.yml + ``` + + + + + + Enter your organization name when prompted. The organization name must be configured in `fern.config.json` in order to sucessfully generate your SDK. + + + 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. + + ```bash + fern/ + ├─ fern.config.json # root-level configuration + └─ api/ # your API + ├─ generators.yml # generators you're using + └─ openapi/ + ├─ openapi.yml # API-level configuration + ``` + + + + Initialize the Fern folder using the Fern Definition by running the following command: + + ```bash + fern init + ``` + + Enter your organization name when prompted. The organization name must be configured in `fern.config.json` in order to sucessfully generate your SDK. + + + This creates a `fern` folder in your current directory with the Fern Definition. + + ```bash + fern/ + ├─ fern.config.json # root-level configuration + ├─ generators.yml # generators you're using + └─ definition/ + ├─ api.yml # API-level configuration + └─ imdb.yml # endpoints, types, and errors + ``` + + + `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. + + + + + + ### Pass `fern check` + + Run `fern check` to ensure that your API Definition is valid. If there are any errors, + fix them before proceeding. + + + If you're using an OpenAPI Specification, check out all of our + [supported extensions](/learn/api-definition/openapi/extensions). + + + ### Generate the SDK + + Add the Typescript SDK using the following command: + + ```bash + fern add fern-typescript-node-sdk --group sdk + ``` + + Then, generate the SDK: + + ```bash + fern generate --group sdk + ``` + + This creates a `sdks` folder in your current directory. The resulting folder structure looks like this: + + + ```bash + fern/ # created in step 1 + sdks/ # created by fern generate --group sdk + ├─ typescript + ├─ cjs/ + ├─ api/ + ├─ core/ + └─ errors/ + └─ esm/ + ├─ api/ + ├─ core/ + └─ errors/ + ``` + + Now that you have + + From cf85ae04b1e210f0e4ffcd1f0721effa41a79384 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Mon, 30 Jun 2025 14:11:26 -0400 Subject: [PATCH 2/6] Fix typos on quickstart page --- fern/products/sdks/pages/typescript/quickstart.mdx | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/fern/products/sdks/pages/typescript/quickstart.mdx b/fern/products/sdks/pages/typescript/quickstart.mdx index 39cce6b60..be2a44243 100644 --- a/fern/products/sdks/pages/typescript/quickstart.mdx +++ b/fern/products/sdks/pages/typescript/quickstart.mdx @@ -1,5 +1,5 @@ --- -title: Typescript Quickstart +title: TypeScript Quickstart description: Get started quickly with the Fern Typescript SDK. --- @@ -9,7 +9,7 @@ description: Get started quickly with the Fern Typescript SDK. [demo](https://buildwithfern.com/contact) or [emailing us](mailto:support@buildwithfern.com) to get started. -Generate a Typescript SDK by following the instructions on this page. +Generate a TypeScript SDK by following the instructions on this page. ### Install the Fern CLI @@ -49,7 +49,7 @@ Generate a Typescript SDK by following the instructions on this page. - Enter your organization name when prompted. The organization name must be configured in `fern.config.json` in order to sucessfully generate your SDK. + Enter your organization name when prompted. The organization name must be configured in `fern.config.json` in order to successfully generate your SDK. 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. @@ -104,7 +104,7 @@ Generate a Typescript SDK by following the instructions on this page. ### Generate the SDK - Add the Typescript SDK using the following command: + Add the TypeScript SDK using the following command: ```bash fern add fern-typescript-node-sdk --group sdk @@ -132,7 +132,5 @@ Generate a Typescript SDK by following the instructions on this page. ├─ core/ └─ errors/ ``` - - Now that you have From ff36f1a2625b392ceedfd6353ecdf04e33aa8e06 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Mon, 30 Jun 2025 16:05:14 -0400 Subject: [PATCH 3/6] Fix OpenAPI nit, add todo for generators.yml, show generators.yml file after fern add command --- .../sdks/pages/typescript/quickstart.mdx | 28 +++++++++++++++---- 1 file changed, 22 insertions(+), 6 deletions(-) diff --git a/fern/products/sdks/pages/typescript/quickstart.mdx b/fern/products/sdks/pages/typescript/quickstart.mdx index be2a44243..a94a97327 100644 --- a/fern/products/sdks/pages/typescript/quickstart.mdx +++ b/fern/products/sdks/pages/typescript/quickstart.mdx @@ -22,7 +22,7 @@ Generate a TypeScript SDK by following the instructions on this page. ### Initialize the Fern Folder - You can use either the Open API definition or Fern Definition to generate your SDK. + You can use either the OpenAPI definition or Fern Definition to generate your SDK. @@ -34,13 +34,13 @@ Generate a TypeScript SDK by following the instructions on this page. - + ```bash fern init --openapi path/to/openapi.yml ``` - + ```bash fern init --openapi https://api.example.com/openapi.yml ``` @@ -89,6 +89,9 @@ Generate a TypeScript SDK by following the instructions on this page. `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. + {/* TODO: show want generators.yml looks like, link out to configuration.md */} + + @@ -102,15 +105,28 @@ Generate a TypeScript SDK by following the instructions on this page. [supported extensions](/learn/api-definition/openapi/extensions). - ### Generate the SDK + ### Add the SDK generator - Add the TypeScript SDK using the following command: + Add the TypeScript SDK generator: ```bash fern add fern-typescript-node-sdk --group sdk ``` - Then, generate the SDK: + This command adds the following to `generators.yml`: + + ```yaml + sdk: + generators: + - name: fernapi/fern-typescript-node-sdk + version: 1.10.1 + output: + location: local-file-system + path: ../sdks/typescript + ``` + ### Generate the SDK + + Generate the SDK: ```bash fern generate --group sdk From c6078c0f933098d8513dd1c33df10755cefbe032 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Mon, 30 Jun 2025 17:25:34 -0400 Subject: [PATCH 4/6] Add in AsyncAPI flow, outputSourceFiles option, and --organization flag --- .../sdks/pages/typescript/configuration.mdx | 143 +++++++++++++++++- .../sdks/pages/typescript/quickstart.mdx | 120 +++++++++++---- 2 files changed, 230 insertions(+), 33 deletions(-) diff --git a/fern/products/sdks/pages/typescript/configuration.mdx b/fern/products/sdks/pages/typescript/configuration.mdx index 0651a7f29..039a82a34 100644 --- a/fern/products/sdks/pages/typescript/configuration.mdx +++ b/fern/products/sdks/pages/typescript/configuration.mdx @@ -3,6 +3,145 @@ title: Typescript Configuration description: Configuration options for the Fern Typescript SDK. --- -# Typescript Configuration +Configure the Fern Typescript SDK for your project. + + +You can customize the behavior of generators in `generators.yml`: + +```yml +default-group: local +groups: + local: + generators: + - name: fernapi/fern-typescript-node-sdk + version: 0.7.1 + config: + useBrandedStringAliases: true +``` + +### SDK Configuration + +The SDK generator support the following parameters: + + + + When 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); +``` + +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 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) + } + ``` + + + + Customizes the exported namespace and client names. By default, names are based on the organization and API names in the Fern Definition. + + + + By default, the generated TypeScript targets CommonJS. Set to true to target esnext instead. + + + + 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. + + + + When enabled, withCredentials is set to true when making network requests. + + + + When enabled, the generated client allows the end user to specify a custom fetcher implementation. + + + + When enabled, the generated client doesn't allow the user to specify a server URL. + + + + The default timeout for network requests. In the generated client, this can be overridden at the request level. + + + + 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. + + + + 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. + + + + Specify extra dev dependencies in the generated package.json. Note: Only applies when publishing to Github. + + + + When enabled, unknown types from Fern are generated into TypeScript using any instead of the unknown type. + + + + 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. + + + + When enabled, optional properties are generated with | undefined instead of optional TypeScript properties (using ?). + + + + When enabled, property names in the generated code will retain their original casing from the API definition instead of being converted to camelCase. + -Discover how to configure the Fern Typescript SDK for your project. \ No newline at end of file diff --git a/fern/products/sdks/pages/typescript/quickstart.mdx b/fern/products/sdks/pages/typescript/quickstart.mdx index a94a97327..cb4da654c 100644 --- a/fern/products/sdks/pages/typescript/quickstart.mdx +++ b/fern/products/sdks/pages/typescript/quickstart.mdx @@ -22,35 +22,35 @@ Generate a TypeScript SDK by following the instructions on this page. ### Initialize the Fern Folder - You can use either the OpenAPI definition or Fern Definition to generate your SDK. + You can use either the OpenAPI definition, AsyncAPI definition, or Fern Definition to generate your SDK. - - Initialize the Fern folder using your OpenAPI Specification. Run one of the following commands based on your spec's location: + + Initialize the Fern folder using your OpenAPI Specification. Run one of the following commands based on your spec's location. 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. + + `--organization ` configures your organization name in `fern.config.json`. This is required in order to successfully generate your SDK. + + ```bash - fern init --openapi path/to/openapi.yml + fern init --openapi path/to/openapi.yml --organization ``` ```bash - fern init --openapi https://api.example.com/openapi.yml + fern init --openapi https://api.example.com/openapi.yml --organization ``` - - - - Enter your organization name when prompted. The organization name must be configured in `fern.config.json` in order to successfully generate your SDK. - + 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. @@ -63,33 +63,91 @@ Generate a TypeScript SDK by following the instructions on this page. ├─ openapi.yml # API-level configuration ``` - + + Initialize the Fern folder using your AsyncAPI Specification. Run one of the following commands based on your spec's location. - Initialize the Fern folder using the Fern Definition by running the following command: + + 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. + - ```bash - fern init - ``` - Enter your organization name when prompted. The organization name must be configured in `fern.config.json` in order to sucessfully generate your SDK. + `--organization ` configures your organization name in `fern.config.json`. This is required in order to successfully generate your SDK. - This creates a `fern` folder in your current directory with the Fern Definition. + + + + ```bash + fern init --asyncapi path/to/asyncapi.yml --organization + ``` + + + + ```bash + fern init --asyncapi https://api.example.com/asyncapi.yml --organization + ``` + + + + + 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. ```bash fern/ ├─ fern.config.json # root-level configuration - ├─ generators.yml # generators you're using - └─ definition/ - ├─ api.yml # API-level configuration - └─ imdb.yml # endpoints, types, and errors + └─ api/ # your API + ├─ generators.yml # generators you're using + └─ openapi/ + ├─ openapi.yml # API-level configuration ``` + + + + 1. Initialize the Fern folder using the Fern Definition by running the following command: + + ```bash + fern init --organization + ``` + + + `--organization ` configures your organization name in `fern.config.json`. This is required in order to successfully generate your SDK. + + + This creates a `fern` folder in your current directory with the Fern Definition. + + ```bash + fern/ + ├─ fern.config.json # root-level configuration + ├─ generators.yml # generators you're using + └─ definition/ + ├─ api.yml # API-level configuration + └─ imdb.yml # endpoints, types, and errors + ``` + + + `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. + + + {/* TODO: show want generators.yml looks like, link out to configuration.md */} + + 1. Add the config option `outputSourceFiles: true` to `generators.yml`. This ensures your SDK contains `.ts` files instead of compiled output. + + ```yaml {11-12} + # yaml-language-server: $schema=https://schema.buildwithfern.dev/generators-yml.json + default-group: local + groups: + local: + generators: + - name: fernapi/fern-typescript-node-sdk + output: + location: local-file-system + path: ../sdks/typescript + version: 1.10.1 + config: + outputSourceFiles: true + ``` - - `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. - - {/* TODO: show want generators.yml looks like, link out to configuration.md */} @@ -117,12 +175,12 @@ Generate a TypeScript SDK by following the instructions on this page. ```yaml sdk: - generators: - - name: fernapi/fern-typescript-node-sdk - version: 1.10.1 - output: - location: local-file-system - path: ../sdks/typescript + generators: + - name: fernapi/fern-typescript-node-sdk + version: 1.10.1 + output: + location: local-file-system + path: ../sdks/typescript ``` ### Generate the SDK From cdbd4c8763fbb430928d28c347cce09db3b5570b Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Tue, 1 Jul 2025 11:38:06 -0400 Subject: [PATCH 5/6] Remove config page from this PR, will add in a different one. --- .../sdks/pages/typescript/configuration.mdx | 143 +----------------- 1 file changed, 2 insertions(+), 141 deletions(-) diff --git a/fern/products/sdks/pages/typescript/configuration.mdx b/fern/products/sdks/pages/typescript/configuration.mdx index 039a82a34..0651a7f29 100644 --- a/fern/products/sdks/pages/typescript/configuration.mdx +++ b/fern/products/sdks/pages/typescript/configuration.mdx @@ -3,145 +3,6 @@ title: Typescript Configuration description: Configuration options for the Fern Typescript SDK. --- -Configure the Fern Typescript SDK for your project. - - -You can customize the behavior of generators in `generators.yml`: - -```yml -default-group: local -groups: - local: - generators: - - name: fernapi/fern-typescript-node-sdk - version: 0.7.1 - config: - useBrandedStringAliases: true -``` - -### SDK Configuration - -The SDK generator support the following parameters: - - - - When 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); -``` - -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 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) - } - ``` - - - - Customizes the exported namespace and client names. By default, names are based on the organization and API names in the Fern Definition. - - - - By default, the generated TypeScript targets CommonJS. Set to true to target esnext instead. - - - - 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. - - - - When enabled, withCredentials is set to true when making network requests. - - - - When enabled, the generated client allows the end user to specify a custom fetcher implementation. - - - - When enabled, the generated client doesn't allow the user to specify a server URL. - - - - The default timeout for network requests. In the generated client, this can be overridden at the request level. - - - - 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. - - - - 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. - - - - Specify extra dev dependencies in the generated package.json. Note: Only applies when publishing to Github. - - - - When enabled, unknown types from Fern are generated into TypeScript using any instead of the unknown type. - - - - 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. - - - - When enabled, optional properties are generated with | undefined instead of optional TypeScript properties (using ?). - - - - When enabled, property names in the generated code will retain their original casing from the API definition instead of being converted to camelCase. - +# Typescript Configuration +Discover how to configure the Fern Typescript SDK for your project. \ No newline at end of file From 5e107802bf4d5d4c635a6eeb34f9d1d37496601e Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Thu, 3 Jul 2025 10:59:05 -0400 Subject: [PATCH 6/6] Add reusable version number snippet and reference in quickstart --- fern/products/sdks/overview/typescript/quickstart.mdx | 4 ++-- fern/snippets/version-number.mdx | 1 + 2 files changed, 3 insertions(+), 2 deletions(-) create mode 100644 fern/snippets/version-number.mdx diff --git a/fern/products/sdks/overview/typescript/quickstart.mdx b/fern/products/sdks/overview/typescript/quickstart.mdx index cb4da654c..9fdf98762 100644 --- a/fern/products/sdks/overview/typescript/quickstart.mdx +++ b/fern/products/sdks/overview/typescript/quickstart.mdx @@ -142,7 +142,7 @@ Generate a TypeScript SDK by following the instructions on this page. output: location: local-file-system path: ../sdks/typescript - version: 1.10.1 + version: config: outputSourceFiles: true ``` @@ -177,7 +177,7 @@ Generate a TypeScript SDK by following the instructions on this page. sdk: generators: - name: fernapi/fern-typescript-node-sdk - version: 1.10.1 + version: output: location: local-file-system path: ../sdks/typescript diff --git a/fern/snippets/version-number.mdx b/fern/snippets/version-number.mdx new file mode 100644 index 000000000..a6094be4d --- /dev/null +++ b/fern/snippets/version-number.mdx @@ -0,0 +1 @@ +4.23.2 \ No newline at end of file