From ff468d2b29b4b9532446db191c2fd48234f8ca43 Mon Sep 17 00:00:00 2001 From: "fern-api[bot]" <115122769+fern-api[bot]@users.noreply.github.com> Date: Fri, 3 Oct 2025 16:46:35 +0000 Subject: [PATCH 1/3] Visual Editor: Update --- fern/products/sdks/capabilities.mdx | 56 +- fern/products/sdks/custom-code.mdx | 14 +- .../overview/typescript/publishing-to-npm.mdx | 498 +++++++++--------- .../sdks/overview/typescript/quickstart.mdx | 89 ++-- 4 files changed, 344 insertions(+), 313 deletions(-) diff --git a/fern/products/sdks/capabilities.mdx b/fern/products/sdks/capabilities.mdx index 1428e30c4..e93261f20 100644 --- a/fern/products/sdks/capabilities.mdx +++ b/fern/products/sdks/capabilities.mdx @@ -42,9 +42,17 @@ layout: overview - + SDKs that handle multipart form data +

+ Learn more + + Arrow right light + + Arrow right light +

+ @@ -122,9 +130,17 @@ layout: overview - + Stream JSON data from your server to your client (i.e. chat completions) +

+ Learn more + + Arrow right light + + Arrow right light +

+ @@ -140,9 +156,17 @@ layout: overview - + No longer depend on manually written code snippets +

+ Learn more + + Arrow right light + + Arrow right light +

+ @@ -158,27 +182,22 @@ layout: overview - + Multiple API Definitions. One SDK.

Learn more - Arrow right light + Arrow right light - Arrow right light + Arrow right light

- + Send and receive messages over WebSockets - - - - Learn how to use the Model Context Protocol (MCP) to integrate AI capabilities with your Fern documentation -

Learn more @@ -187,5 +206,18 @@ layout: overview Arrow right light

+ + + Fern can generate a Model Context Protocol (MCP) server that augments your SDK. + +

+ Learn more + + Arrow right light + + Arrow right light +

+ + diff --git a/fern/products/sdks/custom-code.mdx b/fern/products/sdks/custom-code.mdx index 9625717f0..97cc12ee9 100644 --- a/fern/products/sdks/custom-code.mdx +++ b/fern/products/sdks/custom-code.mdx @@ -27,11 +27,14 @@ LICENSE # Custom code src/CustomClient.ts ``` + For another example, see Cohere's [`.fernignore` file for their TypeScript SDK](https://github.com/cohere-ai/cohere-typescript/blob/ad583e3003bd51e80a82317f9e16beec85881b86/.fernignore). +For another example, see Cohere's [`.fernignore` file for their TypeScript SDK](https://github.com/cohere-ai/cohere-typescript/blob/ad583e3003bd51e80a82317f9e16beec85881b86/.fernignore). + You'll have a separate `.fernignore` file for each of your SDKs: -```text {9, 13} +``` ├─ company-repo # Top-level repo for all SDKs ├─ fern/ ├─ apis/ @@ -47,12 +50,11 @@ You'll have a separate `.fernignore` file for each of your SDKs: └── .fernignore ``` +## Augmenting your SDK with custom code - ## Augmenting your SDK with custom code - - Get started adding custom code to a specific SDK: +Get started adding custom code to a specific SDK: - + } href="/sdks/generators/typescript/custom-code"> } href="/sdks/generators/python/custom-code"> @@ -70,4 +72,4 @@ You'll have a separate `.fernignore` file for each of your SDKs: }> Coming soon - \ No newline at end of file + diff --git a/fern/products/sdks/overview/typescript/publishing-to-npm.mdx b/fern/products/sdks/overview/typescript/publishing-to-npm.mdx index 1b0bd0464..0fd7711d2 100644 --- a/fern/products/sdks/overview/typescript/publishing-to-npm.mdx +++ b/fern/products/sdks/overview/typescript/publishing-to-npm.mdx @@ -12,328 +12,324 @@ you'll have a versioned package published on npm. - This page assumes that you have: + This page assumes that you have: - * An initialized `fern` folder. See [Set up the `fern` - folder](/sdks/overview/quickstart). - * A GitHub repository for your TypeScript SDK. See [Project structure](/sdks/overview/project-structure). - * A TypeScript generator group in `generators.yml`. See [TypeScript - Quickstart](quickstart#add-the-sdk-generator). + - An initialized `fern` folder. See [Set up the ](/sdks/overview/quickstart)`fern`[ folder](/sdks/overview/quickstart). + + - A GitHub repository for your TypeScript SDK. See [Project structure](/sdks/overview/project-structure). + + - A TypeScript generator group in `generators.yml`. See [TypeScript Quickstart](quickstart#add-the-sdk-generator). + - ## Configure SDK package settings You'll need to update your `generators.yml` file to configure the package name, output location, and client naming for npm publishing. Your `generators.yml` [should live in your source repository](/sdks/overview/project-structure) (or on your local machine), not the repository that contains your TypeScript SDK code. - - - In the `group` for your TypeScript SDK, change the output location from `local-file-system` (the default) to `npm` to indicate that Fern should publish your package directly to the npm registry: - - ```yaml {6-7} title="generators.yml" - groups: - ts-sdk: # Group name for your TypeScript SDK - generators: - - name: fernapi/fern-typescript-sdk - version: - output: - location: npm - ``` - - - - - - Your package name must be unique in the npm repository, otherwise publishing your SDK to npm will fail. - - ```yaml {8} title="generators.yml" - groups: - ts-sdk: - generators: - - name: fernapi/fern-typescript-sdk - version: - output: - location: npm - package-name: your-package-name - ``` - - - - - - The `namespaceExport` option controls the name of the generated client. This is the name customers use to import your SDK (`import { your-client-name } from 'your-package-name';`). - - ```yaml {9-10} title="generators.yml" - groups: - ts-sdk: - generators: - - name: fernapi/fern-typescript-sdk - version: - output: - location: npm - package-name: your-package-name - config: - namespaceExport: YourClientName # must be PascalCase - ``` - - + + In the `group` for your TypeScript SDK, change the output location from `local-file-system` (the default) to `npm` to indicate that Fern should publish your package directly to the npm registry: + + ```yaml + groups: + ts-sdk: # Group name for your TypeScript SDK + generators: + - name: fernapi/fern-typescript-sdk + version: + output: + location: npm + ``` + + + + + Your package name must be unique in the npm repository, otherwise publishing your SDK to npm will fail. + + ```yaml + groups: + ts-sdk: + generators: + - name: fernapi/fern-typescript-sdk + version: + output: + location: npm + package-name: your-package-name + ``` + + + + + The `namespaceExport` option controls the name of the generated client. This is the name customers use to import your SDK (`import { your-client-name } from 'your-package-name';`). + + ```yaml + groups: + ts-sdk: + generators: + - name: fernapi/fern-typescript-sdk + version: + output: + location: npm + package-name: your-package-name + config: + namespaceExport: YourClientName # must be PascalCase + ``` + + - ## Generate an npm token + + Log into [npm](https://www.npmjs.com/) or create a new account. - + - Log into [npm](https://www.npmjs.com/) or create a new account. + + 1. Click on your profile picture. - + 2. Select **Edit Profile**. - + 3. Select **Access Tokens**. - 1. Click on your profile picture. - 1. Select **Edit Profile**. - 1. Select **Access Tokens**. + - + + Click on **Generate New Token**, then choose the appropriate token type. - + For more information on access tokens and which type to choose, see npm's [About access tokens](https://docs.npmjs.com/about-access-tokens) documentation. - Click on **Generate New Token**, then choose the appropriate token type. - - For more information on access tokens and which type to choose, see npm's [About access tokens](https://docs.npmjs.com/about-access-tokens) documentation. + + + 1. Select **Classic Token** - - + 2. Name your token and select **Automation** as the token type. - 1. Select **Classic Token** - 1. Name your token and select **Automation** as the token type. - 1. Click **Generate Token**. + 3. Click **Generate Token**. - Save your new token – it won't be displayed after you leave the page. + Save your new token – it won't be displayed after you leave the page. - - Creating NPM Automation Token - + + Creating NPM Automation Token + - - - 1. Select **Granular Access Token**. - 1. Name your token. - 1. Set an expiration. - 1. Configure your token's access to packages and scopes. - 1. Configure your token's access to organizations. In order to fill this out, you must have at least one organization already configured in npm. See [Creating an organization](https://docs.npmjs.com/creating-an-organization) for more information. - 1. Optionally fill out additional permissions according to your organization's requirements. - 1. Click **Generate Token**. - - Save your new token – it won't be displayed after you leave the page. - - - Creating Granular Access Token - - - - - - + + + + 1. Select **Granular Access Token**. + + 2. Name your token. + + 3. Set an expiration. + + 4. Configure your token's access to packages and scopes. + + 5. Configure your token's access to organizations. In order to fill this out, you must have at least one organization already configured in npm. See [Creating an organization](https://docs.npmjs.com/creating-an-organization) for more information. + + 6. Optionally fill out additional permissions according to your organization's requirements. + + 7. Click **Generate Token**. + + Save your new token – it won't be displayed after you leave the page. + + Creating Granular Access Token + + + + + ## Configure npm publication - - - Add the path to the GitHub repository containing your TypeScript SDK: - - ```yaml {11-12} title="generators.yml" - groups: - ts-sdk: - generators: - - name: fernapi/fern-typescript-sdk - version: - output: - location: npm - package-name: your-package-name - config: - namespaceExport: YourClientName - github: - repository: your-org/company-typescript - ``` - - - - -Add `token: ${NPM_TOKEN}` to `generators.yml` to tell Fern to use the `NPM_TOKEN` environment variable for authentication when publishing to the npm registry. - -```yaml title="generators.yml" {9} -groups: - ts-sdk: - generators: - - name: fernapi/fern-typescript-sdk - version: - output: - location: npm - package-name: name-of-your-package - token: ${NPM_TOKEN} - config: - namespaceExport: YourClientName - github: - repository: your-org/your-repository -``` - - - - - -```yaml title="generators.yml" {14} -groups: - ts-sdk: - generators: - - name: fernapi/fern-typescript-sdk - version: - output: - location: npm - package-name: name-of-your-package - token: ${NPM_TOKEN} - config: - namespaceExport: YourClientName - github: - repository: your-org/your-repository - mode: push - branch: your-branch-name # Required for mode: push -``` - - + + Add the path to the GitHub repository containing your TypeScript SDK: + + ```yaml + groups: + ts-sdk: + generators: + - name: fernapi/fern-typescript-sdk + version: + output: + location: npm + package-name: your-package-name + config: + namespaceExport: YourClientName + github: + repository: your-org/company-typescript + ``` + + + + + Add `token: ${NPM_TOKEN}` to `generators.yml` to tell Fern to use the `NPM_TOKEN` environment variable for authentication when publishing to the npm registry. + + ```yaml + groups: + ts-sdk: + generators: + - name: fernapi/fern-typescript-sdk + version: + output: + location: npm + package-name: name-of-your-package + token: ${NPM_TOKEN} + config: + namespaceExport: YourClientName + github: + repository: your-org/your-repository + ``` + + + + + + + ```yaml + groups: + ts-sdk: + generators: + - name: fernapi/fern-typescript-sdk + version: + output: + location: npm + package-name: name-of-your-package + token: ${NPM_TOKEN} + config: + namespaceExport: YourClientName + github: + repository: your-org/your-repository + mode: push + branch: your-branch-name # Required for mode: push + ``` + + ## Publish your SDK Decide how you want to publish your SDK to npm. You can use GitHub workflows for automated releases or publish directly via the CLI. + + Set up a release workflow via [GitHub Actions](https://docs.github.com/en/actions/get-started/quickstart) so you can trigger new SDK releases directly from your source repository. - - -Set up a release workflow via [GitHub Actions](https://docs.github.com/en/actions/get-started/quickstart) so you can trigger new SDK releases directly from your source repository. + + + Open your source repository in GitHub. Click on the **Settings** tab. Then, under the **Security** section, open **Secrets and variables** > **Actions**. - - - - Open your source repository in GitHub. Click on the **Settings** tab. Then, under the **Security** section, open **Secrets and variables** > **Actions**. + + Adding GitHub Repository Secret + - - Adding GitHub Repository Secret - + You can also use the url `https://github.com//settings/secrets/actions`. - You can also use the url `https://github.com//settings/secrets/actions`. + - - + + 1. Select **New repository secret**. - 1. Select **New repository secret**. - 1. Name your secret `NPM_TOKEN`. - 1. Add the corresponding token you generated above. - 1. Click **Add secret**. + 2. Name your secret `NPM_TOKEN`. - - NPM_TOKEN secret - + 3. Add the corresponding token you generated above. - - + 4. Click **Add secret**. - 1. Select **New repository secret**. - 1. Name your secret `FERN_TOKEN`. - 1. Add your Fern token. If you don't already have one, generate one by - running `fern token`. By default, the `fern_token` is generated for the - organization listed in `fern.config.json`. - 1. Click **Add secret**. + + NPM_TOKEN secret + - - + - Set up a CI workflow that you can manually trigger from the GitHub UI. In your repository, navigate to **Actions**. Select **New workflow**, then **Set up workflow yourself**. Add a workflow that's similar to this: + + 1. Select **New repository secret**. - ```yaml title=".github/workflows/publish.yml" maxLines=0 - name: Publish TypeScript SDK + 2. Name your secret `FERN_TOKEN`. - on: - workflow_dispatch: - inputs: - version: - description: "The version of the TypeScript SDK that you would like to release" - required: true - type: string + 3. Add your Fern token. If you don't already have one, generate one by running `fern token`. By default, the `fern_token` is generated for the organization listed in `fern.config.json`. - jobs: - release: - runs-on: ubuntu-latest - steps: - - name: Checkout repo - uses: actions/checkout@v4 + 4. Click **Add secret**. + - - name: Install Fern CLI - run: npm install -g fern-api + + Set up a CI workflow that you can manually trigger from the GitHub UI. In your repository, navigate to **Actions**. Select **New workflow**, then **Set up workflow yourself**. Add a workflow that's similar to this: - - name: Release TypeScript SDK - env: - FERN_TOKEN: ${{ secrets.FERN_TOKEN }} - NPM_TOKEN: ${{ secrets.NPM_TOKEN }} - run: | - fern generate --group ts-sdk --version ${{ inputs.version }} --log-level debug - ``` - - You can alternatively configure your workflow to execute `on: [push]`. See Vapi's [npm publishing GitHub Action](https://github.com/VapiAI/server-sdk-typescript/blob/main/.github/workflows/ci.yml) for an example. - - + ```yaml + name: Publish TypeScript SDK - + on: + workflow_dispatch: + inputs: + version: + description: "The version of the TypeScript SDK that you would like to release" + required: true + type: string - Navigate to the **Actions** tab, select the workflow you just created, specify a version number, and click **Run workflow**. This regenerates your SDK. + jobs: + release: + runs-on: ubuntu-latest + steps: + - name: Checkout repo + uses: actions/checkout@v4 - - Running TS publish workflow - + - name: Install Fern CLI + run: npm install -g fern-api - + - name: Release TypeScript SDK + env: + FERN_TOKEN: ${{ secrets.FERN_TOKEN }} + NPM_TOKEN: ${{ secrets.NPM_TOKEN }} + run: | + fern generate --group ts-sdk --version ${{ inputs.version }} --log-level debug + ``` - Once the workflow completes, you can view your new release by logging into npm and navigating to **Packages**. - - + + You can alternatively configure your workflow to execute `on: [push]`. See Vapi's [npm publishing GitHub Action](https://github.com/VapiAI/server-sdk-typescript/blob/main/.github/workflows/ci.yml) for an example. + - + - + + Navigate to the **Actions** tab, select the workflow you just created, specify a version number, and click **Run workflow**. This regenerates your SDK. - - + + Running TS publish workflow + - + -Set the `NPM_TOKEN` environment variable on your local machine: + Once the workflow completes, you can view your new release by logging into npm and navigating to **Packages**. -```bash -export NPM_TOKEN=your-actual-npm-token -``` + + + - - + + + + Set the `NPM_TOKEN` environment variable on your local machine: -Regenerate your SDK, specifying the version: + ```bash + export NPM_TOKEN=your-actual-npm-token + ``` + -```bash -fern generate --group ts-sdk --version -``` + + Regenerate your SDK, specifying the version: - + ```bash + fern generate --group ts-sdk --version + ``` -Once the workflow completes, you can view your new release by logging into npm and navigating to **Packages**. + - + Once the workflow completes, you can view your new release by logging into npm and navigating to **Packages**. + + - - + + diff --git a/fern/products/sdks/overview/typescript/quickstart.mdx b/fern/products/sdks/overview/typescript/quickstart.mdx index f241a19e3..58e083548 100644 --- a/fern/products/sdks/overview/typescript/quickstart.mdx +++ b/fern/products/sdks/overview/typescript/quickstart.mdx @@ -8,62 +8,63 @@ Generate a TypeScript SDK by following the instructions on this page. + - + ## Add the SDK generator -## Add the SDK generator + Run the following command to add the TypeScript SDK generator to `generators.yml`: -Run the following command to add the TypeScript SDK generator to `generators.yml`: - -```bash -fern add fern-typescript-sdk --group ts-sdk -``` + ```bash + fern add fern-typescript-sdk --group ts-sdk + ``` - - `ts-sdk` is the name of the `generators.yml` group that configures your TypeScript + + `ts-sdk` is the name of the `generators.yml` group that configures your TypeScript SDK's output location and other metadata. You can customize this group name to differentiate between multiple SDKs across different languages (e.g., `ruby-sdk`, etc) in your organization. - -This command adds the following `group` to `generators.yml`: + + + This command adds the following `group` to `generators.yml`: + + ```yaml title="generators.yml" + ts-sdk: # group name + generators: + - name: fernapi/fern-typescript-sdk + version: + output: + location: local-file-system + path: ../sdks/typescript + ``` -```yaml title="generators.yml" - ts-sdk: # group name - generators: - - name: fernapi/fern-typescript-sdk - version: - output: - location: local-file-system - path: ../sdks/typescript -``` -## Generate the SDK + ## Generate the SDK -Run the following command to generate your SDK: + Run the following command to generate your SDK: -```bash -fern generate --group ts-sdk -``` + ```bash + fern generate --group ts-sdk + ``` + + + If you have multiple APIs, use the `--api`[ flag](/cli-api-reference/cli-reference/commands#api) to specify the API you want to generate: - - If you have multiple APIs, use the [`--api` flag](/cli-api-reference/cli-reference/commands#api) to specify the API you want to generate: + ```bash + fern generate --group ts-sdk --api your-api-name + ``` + + + ```bash - fern generate --group ts-sdk --api your-api-name - ``` - - - - -```bash -fern/ # created by fern init -sdks/ # created by fern generate --group ts-sdk -├─ typescript - ├─ Client.ts - ├─ index.ts - ├─ errors/ - ├─ core/ - └─ api/ -``` - + fern/ # created by fern init + sdks/ # created by fern generate --group ts-sdk + ├─ typescript + ├─ Client.ts + ├─ index.ts + ├─ errors/ + ├─ core/ + └─ api/ + ``` + From 3289f963be1b8e57c4556ee58a24f894ab5d11e4 Mon Sep 17 00:00:00 2001 From: "fern-api[bot]" <115122769+fern-api[bot]@users.noreply.github.com> Date: Fri, 3 Oct 2025 16:54:13 +0000 Subject: [PATCH 2/3] Visual Editor: Update --- fern/products/sdks/capabilities.mdx | 28 ++++++++++++++++++---------- 1 file changed, 18 insertions(+), 10 deletions(-) diff --git a/fern/products/sdks/capabilities.mdx b/fern/products/sdks/capabilities.mdx index e93261f20..749baabb4 100644 --- a/fern/products/sdks/capabilities.mdx +++ b/fern/products/sdks/capabilities.mdx @@ -27,6 +27,18 @@ layout: overview Fail fast if payloads diverge from your schema +

+ Learn more + + Arrow right light + + Arrow right light +

+ + + + Fern SDKs include support for discriminated unions +

Learn more @@ -37,11 +49,6 @@ layout: overview - - Fern SDKs include support for discriminated unions - - - SDKs that handle multipart form data @@ -198,13 +205,14 @@ layout: overview Send and receive messages over WebSockets -

- Learn more +

+ Learn more - Arrow right light + Arrow right light + + Arrow right light +

- Arrow right light -

From 65bb16dd4abfb24a6c74257f1d27c0a38da1a4ae Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Fri, 3 Oct 2025 13:36:53 -0400 Subject: [PATCH 3/3] revert unintentionally changed files --- fern/products/sdks/custom-code.mdx | 14 +- .../overview/typescript/publishing-to-npm.mdx | 498 +++++++++--------- .../sdks/overview/typescript/quickstart.mdx | 89 ++-- 3 files changed, 301 insertions(+), 300 deletions(-) diff --git a/fern/products/sdks/custom-code.mdx b/fern/products/sdks/custom-code.mdx index 97cc12ee9..9625717f0 100644 --- a/fern/products/sdks/custom-code.mdx +++ b/fern/products/sdks/custom-code.mdx @@ -27,14 +27,11 @@ LICENSE # Custom code src/CustomClient.ts ``` - For another example, see Cohere's [`.fernignore` file for their TypeScript SDK](https://github.com/cohere-ai/cohere-typescript/blob/ad583e3003bd51e80a82317f9e16beec85881b86/.fernignore). -For another example, see Cohere's [`.fernignore` file for their TypeScript SDK](https://github.com/cohere-ai/cohere-typescript/blob/ad583e3003bd51e80a82317f9e16beec85881b86/.fernignore). - You'll have a separate `.fernignore` file for each of your SDKs: -``` +```text {9, 13} ├─ company-repo # Top-level repo for all SDKs ├─ fern/ ├─ apis/ @@ -50,11 +47,12 @@ You'll have a separate `.fernignore` file for each of your SDKs: └── .fernignore ``` -## Augmenting your SDK with custom code -Get started adding custom code to a specific SDK: + ## Augmenting your SDK with custom code + + Get started adding custom code to a specific SDK: - + } href="/sdks/generators/typescript/custom-code"> } href="/sdks/generators/python/custom-code"> @@ -72,4 +70,4 @@ Get started adding custom code to a specific SDK: }> Coming soon - + \ No newline at end of file diff --git a/fern/products/sdks/overview/typescript/publishing-to-npm.mdx b/fern/products/sdks/overview/typescript/publishing-to-npm.mdx index 0fd7711d2..1b0bd0464 100644 --- a/fern/products/sdks/overview/typescript/publishing-to-npm.mdx +++ b/fern/products/sdks/overview/typescript/publishing-to-npm.mdx @@ -12,324 +12,328 @@ you'll have a versioned package published on npm. - This page assumes that you have: + This page assumes that you have: - - An initialized `fern` folder. See [Set up the ](/sdks/overview/quickstart)`fern`[ folder](/sdks/overview/quickstart). - - - A GitHub repository for your TypeScript SDK. See [Project structure](/sdks/overview/project-structure). - - - A TypeScript generator group in `generators.yml`. See [TypeScript Quickstart](quickstart#add-the-sdk-generator). - + * An initialized `fern` folder. See [Set up the `fern` + folder](/sdks/overview/quickstart). + * A GitHub repository for your TypeScript SDK. See [Project structure](/sdks/overview/project-structure). + * A TypeScript generator group in `generators.yml`. See [TypeScript + Quickstart](quickstart#add-the-sdk-generator). + ## Configure SDK package settings You'll need to update your `generators.yml` file to configure the package name, output location, and client naming for npm publishing. Your `generators.yml` [should live in your source repository](/sdks/overview/project-structure) (or on your local machine), not the repository that contains your TypeScript SDK code. - - In the `group` for your TypeScript SDK, change the output location from `local-file-system` (the default) to `npm` to indicate that Fern should publish your package directly to the npm registry: - - ```yaml - groups: - ts-sdk: # Group name for your TypeScript SDK - generators: - - name: fernapi/fern-typescript-sdk - version: - output: - location: npm - ``` - - - - - Your package name must be unique in the npm repository, otherwise publishing your SDK to npm will fail. - - ```yaml - groups: - ts-sdk: - generators: - - name: fernapi/fern-typescript-sdk - version: - output: - location: npm - package-name: your-package-name - ``` - - - - - The `namespaceExport` option controls the name of the generated client. This is the name customers use to import your SDK (`import { your-client-name } from 'your-package-name';`). - - ```yaml - groups: - ts-sdk: - generators: - - name: fernapi/fern-typescript-sdk - version: - output: - location: npm - package-name: your-package-name - config: - namespaceExport: YourClientName # must be PascalCase - ``` - - + + + In the `group` for your TypeScript SDK, change the output location from `local-file-system` (the default) to `npm` to indicate that Fern should publish your package directly to the npm registry: + + ```yaml {6-7} title="generators.yml" + groups: + ts-sdk: # Group name for your TypeScript SDK + generators: + - name: fernapi/fern-typescript-sdk + version: + output: + location: npm + ``` + + + + + + Your package name must be unique in the npm repository, otherwise publishing your SDK to npm will fail. + + ```yaml {8} title="generators.yml" + groups: + ts-sdk: + generators: + - name: fernapi/fern-typescript-sdk + version: + output: + location: npm + package-name: your-package-name + ``` + + + + + + The `namespaceExport` option controls the name of the generated client. This is the name customers use to import your SDK (`import { your-client-name } from 'your-package-name';`). + + ```yaml {9-10} title="generators.yml" + groups: + ts-sdk: + generators: + - name: fernapi/fern-typescript-sdk + version: + output: + location: npm + package-name: your-package-name + config: + namespaceExport: YourClientName # must be PascalCase + ``` + + + ## Generate an npm token - - Log into [npm](https://www.npmjs.com/) or create a new account. - - - - - 1. Click on your profile picture. - - 2. Select **Edit Profile**. - 3. Select **Access Tokens**. + - + Log into [npm](https://www.npmjs.com/) or create a new account. - - Click on **Generate New Token**, then choose the appropriate token type. + - For more information on access tokens and which type to choose, see npm's [About access tokens](https://docs.npmjs.com/about-access-tokens) documentation. + - - - 1. Select **Classic Token** + 1. Click on your profile picture. + 1. Select **Edit Profile**. + 1. Select **Access Tokens**. - 2. Name your token and select **Automation** as the token type. + - 3. Click **Generate Token**. + - Save your new token – it won't be displayed after you leave the page. + Click on **Generate New Token**, then choose the appropriate token type. + + For more information on access tokens and which type to choose, see npm's [About access tokens](https://docs.npmjs.com/about-access-tokens) documentation. - - Creating NPM Automation Token - + + - + 1. Select **Classic Token** + 1. Name your token and select **Automation** as the token type. + 1. Click **Generate Token**. - - 1. Select **Granular Access Token**. + Save your new token – it won't be displayed after you leave the page. - 2. Name your token. + + Creating NPM Automation Token + - 3. Set an expiration. - - 4. Configure your token's access to packages and scopes. - - 5. Configure your token's access to organizations. In order to fill this out, you must have at least one organization already configured in npm. See [Creating an organization](https://docs.npmjs.com/creating-an-organization) for more information. - - 6. Optionally fill out additional permissions according to your organization's requirements. - - 7. Click **Generate Token**. - - Save your new token – it won't be displayed after you leave the page. + + + 1. Select **Granular Access Token**. + 1. Name your token. + 1. Set an expiration. + 1. Configure your token's access to packages and scopes. + 1. Configure your token's access to organizations. In order to fill this out, you must have at least one organization already configured in npm. See [Creating an organization](https://docs.npmjs.com/creating-an-organization) for more information. + 1. Optionally fill out additional permissions according to your organization's requirements. + 1. Click **Generate Token**. + + Save your new token – it won't be displayed after you leave the page. + + + Creating Granular Access Token + + + + + + - - Creating Granular Access Token - - - - - ## Configure npm publication - - Add the path to the GitHub repository containing your TypeScript SDK: - - ```yaml - groups: - ts-sdk: - generators: - - name: fernapi/fern-typescript-sdk - version: - output: - location: npm - package-name: your-package-name - config: - namespaceExport: YourClientName - github: - repository: your-org/company-typescript - ``` - - - - - Add `token: ${NPM_TOKEN}` to `generators.yml` to tell Fern to use the `NPM_TOKEN` environment variable for authentication when publishing to the npm registry. - - ```yaml - groups: - ts-sdk: - generators: - - name: fernapi/fern-typescript-sdk - version: - output: - location: npm - package-name: name-of-your-package - token: ${NPM_TOKEN} - config: - namespaceExport: YourClientName - github: - repository: your-org/your-repository - ``` - - - - - - - ```yaml - groups: - ts-sdk: - generators: - - name: fernapi/fern-typescript-sdk - version: - output: - location: npm - package-name: name-of-your-package - token: ${NPM_TOKEN} - config: - namespaceExport: YourClientName - github: - repository: your-org/your-repository - mode: push - branch: your-branch-name # Required for mode: push - ``` - + + + Add the path to the GitHub repository containing your TypeScript SDK: + + ```yaml {11-12} title="generators.yml" + groups: + ts-sdk: + generators: + - name: fernapi/fern-typescript-sdk + version: + output: + location: npm + package-name: your-package-name + config: + namespaceExport: YourClientName + github: + repository: your-org/company-typescript + ``` + + + + +Add `token: ${NPM_TOKEN}` to `generators.yml` to tell Fern to use the `NPM_TOKEN` environment variable for authentication when publishing to the npm registry. + +```yaml title="generators.yml" {9} +groups: + ts-sdk: + generators: + - name: fernapi/fern-typescript-sdk + version: + output: + location: npm + package-name: name-of-your-package + token: ${NPM_TOKEN} + config: + namespaceExport: YourClientName + github: + repository: your-org/your-repository +``` + + + + + +```yaml title="generators.yml" {14} +groups: + ts-sdk: + generators: + - name: fernapi/fern-typescript-sdk + version: + output: + location: npm + package-name: name-of-your-package + token: ${NPM_TOKEN} + config: + namespaceExport: YourClientName + github: + repository: your-org/your-repository + mode: push + branch: your-branch-name # Required for mode: push +``` + + - ## Publish your SDK Decide how you want to publish your SDK to npm. You can use GitHub workflows for automated releases or publish directly via the CLI. - - Set up a release workflow via [GitHub Actions](https://docs.github.com/en/actions/get-started/quickstart) so you can trigger new SDK releases directly from your source repository. - - - Open your source repository in GitHub. Click on the **Settings** tab. Then, under the **Security** section, open **Secrets and variables** > **Actions**. + - - Adding GitHub Repository Secret - +Set up a release workflow via [GitHub Actions](https://docs.github.com/en/actions/get-started/quickstart) so you can trigger new SDK releases directly from your source repository. - You can also use the url `https://github.com//settings/secrets/actions`. + + - + Open your source repository in GitHub. Click on the **Settings** tab. Then, under the **Security** section, open **Secrets and variables** > **Actions**. - - 1. Select **New repository secret**. + + Adding GitHub Repository Secret + - 2. Name your secret `NPM_TOKEN`. + You can also use the url `https://github.com//settings/secrets/actions`. - 3. Add the corresponding token you generated above. + + - 4. Click **Add secret**. + 1. Select **New repository secret**. + 1. Name your secret `NPM_TOKEN`. + 1. Add the corresponding token you generated above. + 1. Click **Add secret**. - - NPM_TOKEN secret - + + NPM_TOKEN secret + - + + - - 1. Select **New repository secret**. + 1. Select **New repository secret**. + 1. Name your secret `FERN_TOKEN`. + 1. Add your Fern token. If you don't already have one, generate one by + running `fern token`. By default, the `fern_token` is generated for the + organization listed in `fern.config.json`. + 1. Click **Add secret**. - 2. Name your secret `FERN_TOKEN`. + + - 3. Add your Fern token. If you don't already have one, generate one by running `fern token`. By default, the `fern_token` is generated for the organization listed in `fern.config.json`. + Set up a CI workflow that you can manually trigger from the GitHub UI. In your repository, navigate to **Actions**. Select **New workflow**, then **Set up workflow yourself**. Add a workflow that's similar to this: - 4. Click **Add secret**. - + ```yaml title=".github/workflows/publish.yml" maxLines=0 + name: Publish TypeScript SDK - - Set up a CI workflow that you can manually trigger from the GitHub UI. In your repository, navigate to **Actions**. Select **New workflow**, then **Set up workflow yourself**. Add a workflow that's similar to this: + on: + workflow_dispatch: + inputs: + version: + description: "The version of the TypeScript SDK that you would like to release" + required: true + type: string - ```yaml - name: Publish TypeScript SDK + jobs: + release: + runs-on: ubuntu-latest + steps: + - name: Checkout repo + uses: actions/checkout@v4 - on: - workflow_dispatch: - inputs: - version: - description: "The version of the TypeScript SDK that you would like to release" - required: true - type: string + - name: Install Fern CLI + run: npm install -g fern-api - jobs: - release: - runs-on: ubuntu-latest - steps: - - name: Checkout repo - uses: actions/checkout@v4 + - name: Release TypeScript SDK + env: + FERN_TOKEN: ${{ secrets.FERN_TOKEN }} + NPM_TOKEN: ${{ secrets.NPM_TOKEN }} + run: | + fern generate --group ts-sdk --version ${{ inputs.version }} --log-level debug + ``` + + You can alternatively configure your workflow to execute `on: [push]`. See Vapi's [npm publishing GitHub Action](https://github.com/VapiAI/server-sdk-typescript/blob/main/.github/workflows/ci.yml) for an example. + + - - name: Install Fern CLI - run: npm install -g fern-api + - - name: Release TypeScript SDK - env: - FERN_TOKEN: ${{ secrets.FERN_TOKEN }} - NPM_TOKEN: ${{ secrets.NPM_TOKEN }} - run: | - fern generate --group ts-sdk --version ${{ inputs.version }} --log-level debug - ``` + Navigate to the **Actions** tab, select the workflow you just created, specify a version number, and click **Run workflow**. This regenerates your SDK. - - You can alternatively configure your workflow to execute `on: [push]`. See Vapi's [npm publishing GitHub Action](https://github.com/VapiAI/server-sdk-typescript/blob/main/.github/workflows/ci.yml) for an example. - + + Running TS publish workflow + - + - - Navigate to the **Actions** tab, select the workflow you just created, specify a version number, and click **Run workflow**. This regenerates your SDK. + Once the workflow completes, you can view your new release by logging into npm and navigating to **Packages**. + + - - Running TS publish workflow - + - + - Once the workflow completes, you can view your new release by logging into npm and navigating to **Packages**. + + - - - + - - - - Set the `NPM_TOKEN` environment variable on your local machine: +Set the `NPM_TOKEN` environment variable on your local machine: - ```bash - export NPM_TOKEN=your-actual-npm-token - ``` - +```bash +export NPM_TOKEN=your-actual-npm-token +``` - - Regenerate your SDK, specifying the version: + + - ```bash - fern generate --group ts-sdk --version - ``` +Regenerate your SDK, specifying the version: - +```bash +fern generate --group ts-sdk --version +``` - Once the workflow completes, you can view your new release by logging into npm and navigating to **Packages**. - - + - - +Once the workflow completes, you can view your new release by logging into npm and navigating to **Packages**. + + + + + diff --git a/fern/products/sdks/overview/typescript/quickstart.mdx b/fern/products/sdks/overview/typescript/quickstart.mdx index 58e083548..f241a19e3 100644 --- a/fern/products/sdks/overview/typescript/quickstart.mdx +++ b/fern/products/sdks/overview/typescript/quickstart.mdx @@ -8,63 +8,62 @@ Generate a TypeScript SDK by following the instructions on this page. - - ## Add the SDK generator + - Run the following command to add the TypeScript SDK generator to `generators.yml`: +## Add the SDK generator - ```bash - fern add fern-typescript-sdk --group ts-sdk - ``` +Run the following command to add the TypeScript SDK generator to `generators.yml`: + +```bash +fern add fern-typescript-sdk --group ts-sdk +``` - - `ts-sdk` is the name of the `generators.yml` group that configures your TypeScript + + `ts-sdk` is the name of the `generators.yml` group that configures your TypeScript SDK's output location and other metadata. You can customize this group name to differentiate between multiple SDKs across different languages (e.g., `ruby-sdk`, etc) in your organization. + - - - This command adds the following `group` to `generators.yml`: - - ```yaml title="generators.yml" - ts-sdk: # group name - generators: - - name: fernapi/fern-typescript-sdk - version: - output: - location: local-file-system - path: ../sdks/typescript - ``` +This command adds the following `group` to `generators.yml`: - ## Generate the SDK +```yaml title="generators.yml" + ts-sdk: # group name + generators: + - name: fernapi/fern-typescript-sdk + version: + output: + location: local-file-system + path: ../sdks/typescript +``` +## Generate the SDK - Run the following command to generate your SDK: +Run the following command to generate your SDK: - ```bash - fern generate --group ts-sdk - ``` - - - If you have multiple APIs, use the `--api`[ flag](/cli-api-reference/cli-reference/commands#api) to specify the API you want to generate: +```bash +fern generate --group ts-sdk +``` - ```bash - fern generate --group ts-sdk --api your-api-name - ``` - - - + + If you have multiple APIs, use the [`--api` flag](/cli-api-reference/cli-reference/commands#api) to specify the API you want to generate: ```bash - fern/ # created by fern init - sdks/ # created by fern generate --group ts-sdk - ├─ typescript - ├─ Client.ts - ├─ index.ts - ├─ errors/ - ├─ core/ - └─ api/ - ``` + fern generate --group ts-sdk --api your-api-name + ``` + + + + +```bash +fern/ # created by fern init +sdks/ # created by fern generate --group ts-sdk +├─ typescript + ├─ Client.ts + ├─ index.ts + ├─ errors/ + ├─ core/ + └─ api/ +``` + -