From 862667f9506a2c34accabe015c4c88c3a475f967 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Sat, 6 Sep 2025 14:32:04 -0400 Subject: [PATCH 1/3] clarify npm publishing workflow --- .../overview/typescript/publishing-to-npm.mdx | 180 ++++++++++-------- fern/products/sdks/snippets/release-sdk.mdx | 7 + 2 files changed, 104 insertions(+), 83 deletions(-) create mode 100644 fern/products/sdks/snippets/release-sdk.mdx diff --git a/fern/products/sdks/overview/typescript/publishing-to-npm.mdx b/fern/products/sdks/overview/typescript/publishing-to-npm.mdx index b93e88f37..160b6c8ea 100644 --- a/fern/products/sdks/overview/typescript/publishing-to-npm.mdx +++ b/fern/products/sdks/overview/typescript/publishing-to-npm.mdx @@ -22,9 +22,9 @@ you'll have a versioned package published on npm. -## Configure `generators.yml` +## Configure SDK package settings -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. +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. @@ -79,26 +79,6 @@ you'll have a versioned package published on npm. - - - 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 @@ -163,10 +143,83 @@ you'll have a versioned package published on npm. ## Configure npm publication -Choose how you want to authenticate and publish your SDK to npm. You can use GitHub workflows for automated releases or publish directly via the CLI. + + + + 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 +``` + + + +Optionally set the mode to control how Fern handles SDK publishing: + +- `mode: release` (default): Fern generates code, commits to main, and tags a release automatically +- `mode: pull-request`: Fern generates code and creates a PR for you to review before release +- `mode: push`: Fern generates code and pushes to a branch for you to review before release + +```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: pull-request +``` +You can also configure other settings, like the reviwers or license. Refer to the [full `github` reference](/sdks/reference/generators-yml#github) for more information. + + + + +## 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. @@ -203,26 +256,6 @@ Set up a release workflow via [GitHub Actions](https://docs.github.com/en/action organization listed in `fern.config.json`. 1. Click **Add 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 - ``` @@ -261,64 +294,45 @@ Set up a release workflow via [GitHub Actions](https://docs.github.com/en/action - + - 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. + 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 - - Once your workflow completes, log back into npm and navigate to **Packages** to see your new release. + + + + - - 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 - ``` - - +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 - ``` + + - - - 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. +Regenerate your SDK, specifying the version: - ```bash - fern generate --group ts-sdk --version - ``` - Local machine output will verify that the release is pushed to your - repository and tagged with the version you specified. Log back into npm and - navigate to **Packages** to see your new release. +```bash +fern generate --group ts-sdk --version +``` + + + - diff --git a/fern/products/sdks/snippets/release-sdk.mdx b/fern/products/sdks/snippets/release-sdk.mdx new file mode 100644 index 000000000..522dbdd4e --- /dev/null +++ b/fern/products/sdks/snippets/release-sdk.mdx @@ -0,0 +1,7 @@ +The rest of the release process depends on your chosen mode: + +- **Release mode (default):** If you didn't specify a `mode` or set `mode: release`, no further action is required. Fern automatically tags the new release with your specified version number and initiates the npm publishing workflow in your SDK repository. + +- **Pull request or push mode:** If you set `mode: pull-request` or `mode: push`, Fern creates a pull request. Merge this PR and tag a new release to initiate the npm publishing workflow in your SDK repository. + +Once the workflow completes, you can view your new release by logging into npm and navigating to **Packages**. \ No newline at end of file From aef8cf5724ab65833b5eae78b3c1c64fb2400840 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Sat, 6 Sep 2025 15:26:40 -0400 Subject: [PATCH 2/3] small fixes --- .../products/sdks/overview/typescript/publishing-to-npm.mdx | 6 +++--- fern/products/sdks/snippets/release-sdk.mdx | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/fern/products/sdks/overview/typescript/publishing-to-npm.mdx b/fern/products/sdks/overview/typescript/publishing-to-npm.mdx index 160b6c8ea..dc65b1ae7 100644 --- a/fern/products/sdks/overview/typescript/publishing-to-npm.mdx +++ b/fern/products/sdks/overview/typescript/publishing-to-npm.mdx @@ -112,7 +112,7 @@ You'll need to update your `generators.yml` file to configure the package name, 1. Name your token and select **Automation** as the token type. 1. 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 @@ -128,7 +128,7 @@ You'll need to update your `generators.yml` file to configure the package name, 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. + Save your new token – it won't be displayed after you leave the page. Creating Granular Access Token @@ -208,7 +208,7 @@ groups: repository: your-org/your-repository mode: pull-request ``` -You can also configure other settings, like the reviwers or license. Refer to the [full `github` reference](/sdks/reference/generators-yml#github) for more information. +You can also configure other settings, like the reviewers or license. Refer to the [full `github` (`generators.yml`) reference](/sdks/reference/generators-yml#github) for more information. diff --git a/fern/products/sdks/snippets/release-sdk.mdx b/fern/products/sdks/snippets/release-sdk.mdx index 522dbdd4e..f28a189fe 100644 --- a/fern/products/sdks/snippets/release-sdk.mdx +++ b/fern/products/sdks/snippets/release-sdk.mdx @@ -2,6 +2,6 @@ The rest of the release process depends on your chosen mode: - **Release mode (default):** If you didn't specify a `mode` or set `mode: release`, no further action is required. Fern automatically tags the new release with your specified version number and initiates the npm publishing workflow in your SDK repository. -- **Pull request or push mode:** If you set `mode: pull-request` or `mode: push`, Fern creates a pull request. Merge this PR and tag a new release to initiate the npm publishing workflow in your SDK repository. +- **Pull request or push mode:** If you set `mode: pull-request` or `mode: push`, Fern creates a pull request. Merge this PR and [tag a new release](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository) to initiate the npm publishing workflow in your SDK repository. Once the workflow completes, you can view your new release by logging into npm and navigating to **Packages**. \ No newline at end of file From 6b5569c9d8ab47e52cbd4c57994f52e7b971bdf3 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Mon, 8 Sep 2025 20:09:50 -0400 Subject: [PATCH 3/3] update push mode description --- fern/products/sdks/overview/typescript/publishing-to-npm.mdx | 5 +++-- fern/products/sdks/snippets/release-sdk.mdx | 2 +- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/fern/products/sdks/overview/typescript/publishing-to-npm.mdx b/fern/products/sdks/overview/typescript/publishing-to-npm.mdx index dc65b1ae7..010be1e37 100644 --- a/fern/products/sdks/overview/typescript/publishing-to-npm.mdx +++ b/fern/products/sdks/overview/typescript/publishing-to-npm.mdx @@ -190,7 +190,7 @@ Optionally set the mode to control how Fern handles SDK publishing: - `mode: release` (default): Fern generates code, commits to main, and tags a release automatically - `mode: pull-request`: Fern generates code and creates a PR for you to review before release -- `mode: push`: Fern generates code and pushes to a branch for you to review before release +- `mode: push`: Fern generates code and pushes to a branch you specify for you to review before release ```yaml title="generators.yml" {14} groups: @@ -206,7 +206,8 @@ groups: namespaceExport: YourClientName github: repository: your-org/your-repository - mode: pull-request + mode: push + branch: your-branch-name # Required for mode: push ``` You can also configure other settings, like the reviewers or license. Refer to the [full `github` (`generators.yml`) reference](/sdks/reference/generators-yml#github) for more information. diff --git a/fern/products/sdks/snippets/release-sdk.mdx b/fern/products/sdks/snippets/release-sdk.mdx index f28a189fe..3f046ad61 100644 --- a/fern/products/sdks/snippets/release-sdk.mdx +++ b/fern/products/sdks/snippets/release-sdk.mdx @@ -2,6 +2,6 @@ The rest of the release process depends on your chosen mode: - **Release mode (default):** If you didn't specify a `mode` or set `mode: release`, no further action is required. Fern automatically tags the new release with your specified version number and initiates the npm publishing workflow in your SDK repository. -- **Pull request or push mode:** If you set `mode: pull-request` or `mode: push`, Fern creates a pull request. Merge this PR and [tag a new release](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository) to initiate the npm publishing workflow in your SDK repository. +- **Pull request or push mode:** If you set `mode: pull-request` or `mode: push`, Fern creates a pull request or pushes to a branch respectively. Review and merge the PR (`pull-request`) or branch (`push`), then [tag a new release](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository) to initiate the npm publishing workflow in your SDK repository. Once the workflow completes, you can view your new release by logging into npm and navigating to **Packages**. \ No newline at end of file