Publishing to npm | Fern Documentation

Publish your public-facing Fern TypeScript SDK to the npm registry. After following the steps on this page, you’ll have a versioned package published on npm.

This page assumes that you have:

An initialized fern folder. See Set up the fern folder.
A GitHub repository for your TypeScript SDK. See Project structure.
A TypeScript generator group in generators.yml. See TypeScript Quickstart.

Configure `generators.yml`

Your generators.yml should live in your source repository (or on your local machine), not the repository that contains your TypeScript SDK code.

Configure `output` location

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:

generators.yml

1 groups: 
2   ts-sdk: # Group name for your TypeScript SDK
3     generators:
4       - name: fernapi/fern-typescript-sdk
5         version: 2.5.0
6         output:
7           location: npm

Add a unique package name

Your package name must be unique in the npm repository, otherwise publishing your SDK to npm will fail.

generators.yml

1 groups: 
2   ts-sdk:
3     generators:
4       - name: fernapi/fern-typescript-sdk
5         version: 2.5.0
6         output:
7           location: npm
8           package-name: your-package-name

Configure `namespaceExport`

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';).

generators.yml

1 groups: 
2   ts-sdk:
3     generators:
4       - name: fernapi/fern-typescript-sdk
5         version: 2.5.0
6         output:
7           location: npm
8           package-name: your-package-name
9         config:
10           namespaceExport: YourClientName # must be PascalCase

Add repository location

Add the path to the GitHub repository containing your TypeScript SDK:

generators.yml

1 groups: 
2   ts-sdk:
3     generators:
4       - name: fernapi/fern-typescript-sdk
5         version: 2.5.0
6         output:
7           location: npm
8           package-name: your-package-name
9         config:
10           namespaceExport: YourClientName
11         github: 
12           repository: your-org/company-typescript

Generate an npm token

Log into npm

Log into npm or create a new account.

Navigate to Access Tokens

Click on your profile picture.
Select Edit Profile.
Select Access Tokens.

Generate Token

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

Option 1: Classic Token

Select Classic Token
Name your token and select Automation as the token type.
Click Generate Token.

Save your new token – it won’t be displayed after you leave the page.

Option 2: Granular Access Token

Select Granular Access Token.
Name your token.
Set an expiration.
Configure your token’s access to packages and scopes.
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 for more information.
Optionally fill out additional permissions according to your organization’s requirements.
Click Generate Token.

Save your new token – it won’t be displayed after you leave the page.

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.

Release via a GitHub workflow (recommended)

Set up a release workflow via GitHub Actions so you can trigger new SDK releases directly from your source repository.

Set up authentication

Open your Fern repository in GitHub. Click on the Settings tab in your repository. Then, under the Security section, open Secrets and variables > Actions.

You can also use the url https://github.com/<your-repo>/settings/secrets/actions.

Add secret for your npm Token

Select New repository secret.
Name your secret NPM_TOKEN.
Add the corresponding token you generated above.
Click Add secret.

Add secret for your Fern Token

Select New repository secret.
Name your secret FERN_TOKEN.
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.
Click Add secret.

Configure npm authentication token

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

generators.yml

1 groups: 
2   ts-sdk:
3     generators:
4       - name: fernapi/fern-typescript-sdk
5         version: 2.5.0
6         output:
7           location: npm
8           package-name: name-of-your-package
9           token: ${NPM_TOKEN}
10         config:
11           namespaceExport: YourClientName
12         github: 
13           repository: your-org/your-repository

Set up a new workflow

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:

.github/workflows/publish.yml

1 name: Publish TypeScript SDK
2 
3 on:
4   workflow_dispatch:
5     inputs:
6       version:
7         description: "The version of the TypeScript SDK that you would like to release"
8         required: true
9         type: string
10 
11 jobs:
12   release:
13     runs-on: ubuntu-latest
14     steps:
15       - name: Checkout repo
16         uses: actions/checkout@v4
17 
18       - name: Install Fern CLI
19         run: npm install -g fern-api
20 
21       - name: Release TypeScript SDK
22         env:
23           FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
24           NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
25         run: |
26           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 for an example.

Run your workflow

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.

Once your workflow completes, log back into npm and navigate to Packages to see your new release.

Release via CLI and environment variables

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.

1 groups: 
2   ts-sdk:
3     generators:
4       - name: fernapi/fern-typescript-sdk
5         version: 2.5.0
6         output:
7           location: npm
8           package-name: name-of-your-package
9           token: ${NPM_TOKEN}
10         config:
11           namespaceExport: YourClientName
12         github: 
13           repository: your-org/your-repository

Set npm environment variable

Set the NPM_TOKEN environment variable on your local machine:

$ export NPM_TOKEN=your-actual-npm-token

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.

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

Configure generators.yml

Configure output location

Add a unique package name

Configure namespaceExport

Add repository location

Generate an npm token

Log into npm

Navigate to Access Tokens

Generate Token

Option 1: Classic Token

Option 2: Granular Access Token

Configure npm publication

Release via a GitHub workflow (recommended)

Set up authentication

Add secret for your npm Token

Add secret for your Fern Token

Configure npm authentication token

Set up a new workflow

Run your workflow

Release via CLI and environment variables

Configure npm authentication token

Set npm environment variable

Regenerate your SDK

Configure `generators.yml`

Configure `output` location

Configure `namespaceExport`