From a5cd583fe7fe6445218e8b3629cbdbbe73b69a4f Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Fri, 22 Aug 2025 14:46:28 -0400 Subject: [PATCH 1/5] update npm publishing guide --- .../overview/typescript/publishing-to-npm.mdx | 136 +++++++++++------- 1 file changed, 81 insertions(+), 55 deletions(-) diff --git a/fern/products/sdks/overview/typescript/publishing-to-npm.mdx b/fern/products/sdks/overview/typescript/publishing-to-npm.mdx index d99496de..eec1dcda 100644 --- a/fern/products/sdks/overview/typescript/publishing-to-npm.mdx +++ b/fern/products/sdks/overview/typescript/publishing-to-npm.mdx @@ -185,10 +185,10 @@ Set up a release workflow via [GitHub Actions](https://docs.github.com/en/action - 1. Select **New repository secret**. - 1. Name your secret `NPM_TOKEN`. - 1. Add the corresponding token you generated above. - 1. 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 @@ -197,12 +197,12 @@ Set up a release workflow via [GitHub Actions](https://docs.github.com/en/action - 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**. + 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 @@ -211,45 +211,71 @@ Set up a release workflow via [GitHub Actions](https://docs.github.com/en/action - In your repo, navigate to **Actions**. Select **New workflow**, then **Set up workflow yourself**. Set up a workflow dispatch that is similar to this: + In your repo, navigate to **Actions**. Select **New workflow**, then **Set up workflow yourself**. Set up a CI workflow that automatically publishes on tagged pushes: ```yaml title=".github/workflows/publish.yml" maxLines=0 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 + on: [push] jobs: - release: - runs-on: ubuntu-latest - steps: - - name: Checkout repo - uses: actions/checkout@v4 - - - 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 + compile: + runs-on: ubuntu-latest + + steps: + - name: Checkout repo + uses: actions/checkout@v3 + + - name: Set up node + uses: actions/setup-node@v3 + + - name: Compile + run: yarn && yarn build + + test: + runs-on: ubuntu-latest + + steps: + - name: Checkout repo + uses: actions/checkout@v3 + + - name: Set up node + uses: actions/setup-node@v3 + + - name: Compile + run: yarn && yarn test + + publish: + needs: [ compile ] + if: github.event_name == 'push' && contains(github.ref, 'refs/tags/') + runs-on: ubuntu-latest + steps: + - name: Checkout repo + uses: actions/checkout@v3 + - name: Set up node + uses: actions/setup-node@v3 + - name: Install dependencies + run: yarn install + - name: Build + run: yarn build + + - name: Publish to npm + run: | + npm config set //registry.npmjs.org/:_authToken ${NPM_TOKEN} + if [[ ${GITHUB_REF} == *alpha* ]]; then + npm publish --access public --tag alpha + elif [[ ${GITHUB_REF} == *beta* ]]; then + npm publish --access public --tag beta + else + npm publish --access public + fi + env: + NPM_TOKEN: ${{ secrets.NPM_TOKEN }} ``` - + - Navigate to the **Actions** tab, select the workflow you just created, and - click **Run workflow**. - - - Running TS publish workflow - + To trigger a release, create and push a git tag to your repository. The workflow will automatically run and publish your package to npm. Once your workflow completes, log back into npm and navigate to **Packages** to see your new release. @@ -264,21 +290,21 @@ Set up a release workflow via [GitHub Actions](https://docs.github.com/en/action 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 {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 {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 + ``` When you regenerate your release, Fern will automatically create a workflow in your repository called `.github/workflows/ci.yml` that will automatically publish your release to npm. For an example, see Vapi's [npm publishing GitHub Action](https://github.com/VapiAI/server-sdk-typescript/blob/main/.github/workflows/ci.yml) From cfbe55c27f14912ca665064b2653dc9caf5ec503 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Wed, 27 Aug 2025 17:09:05 -0400 Subject: [PATCH 2/5] add example folder, update npm publishing guide --- examples/typescript-sdk/generators.yml | 25 ++ .../typescript-sdk/typescript-publish.yml | 32 +++ fern/products/sdks/github-setup.mdx | 3 +- .../overview/typescript/publishing-to-npm.mdx | 241 +++++++++--------- 4 files changed, 175 insertions(+), 126 deletions(-) create mode 100644 examples/typescript-sdk/generators.yml create mode 100644 examples/typescript-sdk/typescript-publish.yml diff --git a/examples/typescript-sdk/generators.yml b/examples/typescript-sdk/generators.yml new file mode 100644 index 00000000..56b62aaf --- /dev/null +++ b/examples/typescript-sdk/generators.yml @@ -0,0 +1,25 @@ +# This file configures all of your SDKs and should be located at: +# your-parent-repo/fern/generators.yml. +default-group: local +groups: + local: + generators: + - name: fernapi/fern-typescript-sdk + output: + location: local-file-system + path: ../sdks/typescript + version: 2.6.4 + # This group configures a TypeScript SDK for npm publishing + ts-sdk: + generators: + - name: fernapi/fern-typescript-sdk + version: 2.6.4 + output: + location: npm + package-name: your-unique-package-name + token: ${NPM_TOKEN} + config: + namespaceExport: YourClientName + github: + repository: your-company/ts-sdk + # other generator groups for other SDKs go here \ No newline at end of file diff --git a/examples/typescript-sdk/typescript-publish.yml b/examples/typescript-sdk/typescript-publish.yml new file mode 100644 index 00000000..50fe9f79 --- /dev/null +++ b/examples/typescript-sdk/typescript-publish.yml @@ -0,0 +1,32 @@ +# Add this file as: your-parent-repo/.github/workflows/typescript-publish.yml +# This workflow should be in the same repository as your generators.yml, which +# should point to the repository containing your TypeScript SDK code. + +name: Publish TypeScript SDK + +on: +# Manually trigger a release from the GitHub UI. Triggering this workflow kicks +# off the npm publishing process from your TypeScript SDK repository. + workflow_dispatch: + inputs: + version: + description: "The version of the TypeScript SDK that you would like to release" + required: true + type: string + +jobs: + release: + runs-on: ubuntu-latest + steps: + - name: Checkout repo + uses: actions/checkout@v4 + + - 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 \ No newline at end of file diff --git a/fern/products/sdks/github-setup.mdx b/fern/products/sdks/github-setup.mdx index 93f7dd58..36684578 100644 --- a/fern/products/sdks/github-setup.mdx +++ b/fern/products/sdks/github-setup.mdx @@ -14,6 +14,7 @@ Fern recommends a parent-child repository structure containing: ```bash ├─ company-repo # Parent repository +│ ├─ .github.workflows # Contains publishing workflows for all SDKs │ └─ fern/ │ ├─ fern.config.json # Root-level config │ ├─ generators.yml # References child repos @@ -89,7 +90,7 @@ Each SDK has its own repository with the following structure: ```bash typescript-sdk-repo/ # Individual SDK repository -├─ .github/workflows/ # Publishing workflows +├─ .github/workflows/ # Generated by Fern ├─ scripts/ ├─ src/ ├─ tests/ diff --git a/fern/products/sdks/overview/typescript/publishing-to-npm.mdx b/fern/products/sdks/overview/typescript/publishing-to-npm.mdx index eec1dcda..f648ff62 100644 --- a/fern/products/sdks/overview/typescript/publishing-to-npm.mdx +++ b/fern/products/sdks/overview/typescript/publishing-to-npm.mdx @@ -14,9 +14,9 @@ you'll have a versioned package published on npm. This page assumes that you have: - * An initialized `fern` folder on your local machine. See [Set up the `fern` + * An initialized `fern` folder. See [Set up the `fern` folder](/sdks/overview/quickstart). - * A GitHub repository for your TypeScript SDK. See [Set up your GitHub structure](/sdks/overview/github). + * A GitHub repository for your TypeScript SDK. See [Project structure](/sdks/overview/github). * A TypeScript generator group in `generators.yml`. See [TypeScript Quickstart](quickstart#add-the-sdk-generator). @@ -24,82 +24,81 @@ you'll have a versioned package published on npm. ## Configure `generators.yml` - +Your `generators.yml` [should live in your parent repository](/sdks/overview/github) (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 in from `local-file-system` (the default) to `npm` to indicate that Fern should publish your package directly to the npm registry: - ```yaml {6-7} - groups: - ts-sdk: # Group name for your TypeScript SDK - generators: - - name: fernapi/fern-typescript-sdk - version: - output: - location: npm + ```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. Update your package name if you haven't done so already: + 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 + ``` -```yaml {8} -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} -groups: - ts-sdk: - generators: - - name: fernapi/fern-typescript-sdk - version: - output: - location: npm - package-name: your-package-name - config: - namespaceExport: YourClientName # must be PascalCase -``` - - - - - - Add the path to your GitHub repository to `generators.yml`, if you haven't already: - -```yaml {11-12} -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 -``` - - + 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 + ``` + + + + + + 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 + ``` + + ## Generate an npm token @@ -169,7 +168,7 @@ Choose how you want to authenticate and publish your SDK to npm. You can use Git -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 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 parent repository. @@ -204,81 +203,75 @@ Set up a release workflow via [GitHub Actions](https://docs.github.com/en/action organization listed in `fern.config.json`. 1. Click **Add secret**. - - NPM_TOKEN secret - + + + + Add `token: ${NPM_TOKEN}` to `generators.yml`. + ```yaml {9} title="generators.yml" + 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 + ``` - In your repo, navigate to **Actions**. Select **New workflow**, then **Set up workflow yourself**. Set up a CI workflow that automatically publishes on tagged pushes: + 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: ```yaml title=".github/workflows/publish.yml" maxLines=0 name: Publish TypeScript SDK - on: [push] + on: + workflow_dispatch: + inputs: + version: + description: "The version of the TypeScript SDK that you would like to release" + required: true + type: string jobs: - compile: - runs-on: ubuntu-latest - - steps: - - name: Checkout repo - uses: actions/checkout@v3 - - - name: Set up node - uses: actions/setup-node@v3 - - - name: Compile - run: yarn && yarn build - - test: + release: runs-on: ubuntu-latest - steps: - name: Checkout repo - uses: actions/checkout@v3 + uses: actions/checkout@v4 - - name: Set up node - uses: actions/setup-node@v3 + - name: Install Fern CLI + run: npm install -g fern-api - - name: Compile - run: yarn && yarn test - - publish: - needs: [ compile ] - if: github.event_name == 'push' && contains(github.ref, 'refs/tags/') - runs-on: ubuntu-latest - steps: - - name: Checkout repo - uses: actions/checkout@v3 - - name: Set up node - uses: actions/setup-node@v3 - - name: Install dependencies - run: yarn install - - name: Build - run: yarn build - - - name: Publish to npm - run: | - npm config set //registry.npmjs.org/:_authToken ${NPM_TOKEN} - if [[ ${GITHUB_REF} == *alpha* ]]; then - npm publish --access public --tag alpha - elif [[ ${GITHUB_REF} == *beta* ]]; then - npm publish --access public --tag beta - else - npm publish --access public - fi + - 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 `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, tags the new release with the version number you specified, and initiates a Fern-generated publishing workflow in your TypeScript SDK repository that publishes your release to npm. - To trigger a release, create and push a git tag to your repository. The workflow will automatically run and publish your package to npm. + + Running TS publish workflow + - Once your workflow completes, log back into npm and - navigate to **Packages** to see your new release. + Once your workflow completes, log back into npm and navigate to **Packages** to see your new release. @@ -305,8 +298,6 @@ Set up a release workflow via [GitHub Actions](https://docs.github.com/en/action github: repository: your-org/your-repository ``` - - When you regenerate your release, Fern will automatically create a workflow in your repository called `.github/workflows/ci.yml` that will automatically publish your release to npm. For an example, see Vapi's [npm publishing GitHub Action](https://github.com/VapiAI/server-sdk-typescript/blob/main/.github/workflows/ci.yml) @@ -318,7 +309,7 @@ Set up a release workflow via [GitHub Actions](https://docs.github.com/en/action - + Regenerating your SDK tags the new release with the version number you specified and initiates a Fern-generated publishing workflow in your TypeScript SDK repository that publishes your release to npm. ```bash fern generate --group ts-sdk --version From bf74b9d6105d3968be03306118286d6c1a04c05d Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Wed, 27 Aug 2025 17:18:58 -0400 Subject: [PATCH 3/5] fix image formatting --- fern/products/sdks/overview/typescript/publishing-to-npm.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fern/products/sdks/overview/typescript/publishing-to-npm.mdx b/fern/products/sdks/overview/typescript/publishing-to-npm.mdx index f648ff62..e8c4d45b 100644 --- a/fern/products/sdks/overview/typescript/publishing-to-npm.mdx +++ b/fern/products/sdks/overview/typescript/publishing-to-npm.mdx @@ -268,7 +268,7 @@ Set up a release workflow via [GitHub Actions](https://docs.github.com/en/action This regenerates your SDK, tags the new release with the version number you specified, and initiates a Fern-generated publishing workflow in your TypeScript SDK repository that publishes your release to npm. - Running TS publish workflow + Running TS publish workflow Once your workflow completes, log back into npm and navigate to **Packages** to see your new release. From 2292f178114171f6c51144b6960fc72e8d0c7acc Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Wed, 27 Aug 2025 18:43:35 -0400 Subject: [PATCH 4/5] nit wording change --- fern/products/sdks/overview/typescript/publishing-to-npm.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fern/products/sdks/overview/typescript/publishing-to-npm.mdx b/fern/products/sdks/overview/typescript/publishing-to-npm.mdx index e8c4d45b..323427f2 100644 --- a/fern/products/sdks/overview/typescript/publishing-to-npm.mdx +++ b/fern/products/sdks/overview/typescript/publishing-to-npm.mdx @@ -257,7 +257,7 @@ Set up a release workflow via [GitHub Actions](https://docs.github.com/en/action fern generate --group ts-sdk --version ${{ inputs.version }} --log-level debug ``` - You can alternatively configure your workflow `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. + 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. From ca2c27575c50d6612a8bbd29f11b6e1b0e66414b Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Wed, 27 Aug 2025 18:46:49 -0400 Subject: [PATCH 5/5] update comments --- examples/typescript-sdk/generators.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/examples/typescript-sdk/generators.yml b/examples/typescript-sdk/generators.yml index 56b62aaf..3b0f1fbe 100644 --- a/examples/typescript-sdk/generators.yml +++ b/examples/typescript-sdk/generators.yml @@ -1,4 +1,4 @@ -# This file configures all of your SDKs and should be located at: +# This file configures all of your SDKs. It should be located at: # your-parent-repo/fern/generators.yml. default-group: local groups: @@ -22,4 +22,4 @@ groups: namespaceExport: YourClientName github: repository: your-company/ts-sdk - # other generator groups for other SDKs go here \ No newline at end of file + # generator groups for other SDKs go here \ No newline at end of file