Skip to content

Clarify npm publishing workflow (SDKs) #721

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Sep 9, 2025
+107 −85
Merged

Clarify npm publishing workflow (SDKs) #721

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
862667f
clarify npm publishing workflow
devalog Sep 6, 2025
aef8cf5
small fixes
devalog Sep 6, 2025
6b5569c
update push mode description
devalog Sep 9, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
185 changes: 100 additions & 85 deletions fern/products/sdks/overview/typescript/publishing-to-npm.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,9 +22,9 @@ you'll have a versioned package published on npm.

</Info>

## Configure `generators.yml`
## Configure SDK package settings

<Note>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.</Note>
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.

<Steps>
<Step title="Configure `output` location">
Expand Down Expand Up @@ -79,26 +79,6 @@ you'll have a versioned package published on npm.

</Step>

<Step title="Add repository location">

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: <Markdown src="/snippets/typescript-sdk-version.mdx"/>
output:
location: npm
package-name: your-package-name
config:
namespaceExport: YourClientName
github:
repository: your-org/company-typescript
```

</Step>
</Steps>

## Generate an npm token
Expand Down Expand Up @@ -132,7 +112,7 @@ you'll have a versioned package published on npm.
1. Name your token and select **Automation** as the token type.
1. Click **Generate Token**.

<Warning>Save your new token – it won’t be displayed after you leave the page.</Warning>
<Warning>Save your new token – it won't be displayed after you leave the page.</Warning>

<Frame>
<img src="assets/npm-automation-token.png" alt="Creating NPM Automation Token" />
Expand All @@ -148,7 +128,7 @@ you'll have a versioned package published on npm.
1. Optionally fill out additional permissions according to your organization's requirements.
1. Click **Generate Token**.

<Warning>Save your new token – it won’t be displayed after you leave the page.</Warning>
<Warning>Save your new token – it won't be displayed after you leave the page.</Warning>

<Frame>
<img src="assets/granular-access-token.png" alt="Creating Granular Access Token" />
Expand All @@ -163,10 +143,84 @@ 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.
<Steps>
<Step title="Add repository location">

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: <Markdown src="/snippets/typescript-sdk-version.mdx"/>
output:
location: npm
package-name: your-package-name
config:
namespaceExport: YourClientName
github:
repository: your-org/company-typescript
```

</Step>
<Step title="Configure npm authentication token">

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: <Markdown src="/snippets/typescript-sdk-version.mdx"/>
output:
location: npm
package-name: name-of-your-package
token: ${NPM_TOKEN}
config:
namespaceExport: YourClientName
github:
repository: your-org/your-repository
```
</Step>
<Step title="Choose your publishing mode">

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 you specify for you to review before release

```yaml title="generators.yml" {14}
groups:
ts-sdk:
generators:
- name: fernapi/fern-typescript-sdk
version: <Markdown src="/snippets/typescript-sdk-version.mdx"/>
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
```
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.

</Step>
</Steps>

## 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.

<AccordionGroup>
<Accordion title="Release via a GitHub workflow (recommended)">

<Accordion title="Release via a GitHub workflow">

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.

Expand Down Expand Up @@ -203,26 +257,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**.

</Step>
<Step title="Configure npm authentication token">

Add `token: ${NPM_TOKEN}` to `generators.yml`.

```yaml {9} title="generators.yml"
groups:
ts-sdk:
generators:
- name: fernapi/fern-typescript-sdk
version: <Markdown src="/snippets/typescript-sdk-version.mdx"/>
output:
location: npm
package-name: name-of-your-package
token: ${NPM_TOKEN}
config:
namespaceExport: YourClientName
github:
repository: your-org/your-repository
```
</Step>
<Step title="Set up a new workflow">

Expand Down Expand Up @@ -261,64 +295,45 @@ Set up a release workflow via [GitHub Actions](https://docs.github.com/en/action
</Note>
</Step>

<Step title="Run your workflow">
<Step title="Regenerate and release your SDK">

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.

<Frame>
<img src="assets/ts-sdk-release-action.png" alt="Running TS publish workflow" />
</Frame>
Once your workflow completes, log back into npm and navigate to **Packages** to see your new release.

<Markdown src="/products/sdks/snippets/release-sdk.mdx"/>

</Step>

</Steps>

</Accordion>

<Accordion title="Release via CLI and environment variables">
<Steps>
<Step title="Configure npm authentication token">

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.
<Step title="Set npm environment variable">

```yaml {9}
groups:
ts-sdk:
generators:
- name: fernapi/fern-typescript-sdk
version: <Markdown src="/snippets/typescript-sdk-version.mdx"/>
output:
location: npm
package-name: name-of-your-package
token: ${NPM_TOKEN}
config:
namespaceExport: YourClientName
github:
repository: your-org/your-repository
```
</Step>
<Step title="Set npm environment variable">
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
```
</Step>
<Step title="Regenerate and release your SDK">

</Step>
<Step title="Regenerate your SDK">
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 <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 <version>
```

<Markdown src="/products/sdks/snippets/release-sdk.mdx"/>
</Step>

</Step>
</Steps>
</Accordion>
</AccordionGroup>
7 changes: 7 additions & 0 deletions fern/products/sdks/snippets/release-sdk.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 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**.