Publishing to npm

Add OIDC to generators.yml

Add token: OIDC to the output section:

groups:
  ts-sdk:
	generators:
	  - name: fern-typescript-sdk
		version: 3.97.1  # Must be 3.12.3 or later
		output:
		  location: npm
		  package-name: your-package-name
		  token: OIDC
	config:
	  namespaceExport: YourClientName
	github:
	  repository: your-org/your-repository
	  mode: push
	  branch: your-branch-name

Publish a placeholder package

OIDC can’t perform a package’s first publish: npm requires the package to exist before you can add a trusted publisher. Publish a placeholder version to create it:

npm login
PACKAGE_NAME="your-package-name"
ACCESS="public" # or "restricted" for private packages
dir="$(mktemp -d)"
echo "{ \"name\": \"$PACKAGE_NAME\", \"version\": \"0.0.0\" }" > "$dir/package.json"
npm publish "$dir" --access "$ACCESS"

Set the placeholder version to something below your first real release (for example, 0.0.0).

Authorize your repository on npmjs.com

Configure trusted publishing on npmjs.com to allow your GitHub repository to publish:

1. Open the package page on npmjs.com and go to the Settings tab
2. Find the Trusted Publisher section and click Add trusted publisher
3. Select GitHub Actions as your provider
4. Fill in:
   • Organization or user: Your GitHub username or organization
   • Repository: Your TypeScript SDK repository name (e.g., your-org/your-repository)
   • Workflow filename: ci.yml
   • Environment name: Leave blank
5. Under Allowed actions, select Allow npm publish

Generate your SDK

Generate your SDK to create the GitHub Actions workflow with OIDC configuration:

fern generate --group ts-sdk

This creates a .github/workflows/ci.yml file that’s configured to use OIDC for npm publishing. Alternatively, you can push your generators.yml changes and let the Fern GitHub Action generate the workflow for you.

Generate an npm token

1. Log into npmjs.com
2. Click on your profile picture and select Edit Profile
3. Select Access Tokens
4. Click Generate New Token and choose either Classic Token (select “Automation” type) or Granular Access Token
5. Save your token securely - it won’t be displayed again

Add token to generators.yml

Add token: ${NPM_TOKEN} to the output section:

groups:
  ts-sdk:
	generators:
	  - name: fern-typescript-sdk
		version: 3.97.1
		output:
		  location: npm
		  package-name: your-package-name
		  token: ${NPM_TOKEN}
		config:
		  namespaceExport: YourClientName
		github:
		  repository: your-org/your-repository
		  mode: push
		  branch: your-branch-name

Add NPM_TOKEN as a GitHub Actions secret

1. Open your repository on GitHub and go to Settings
2. Navigate to Secrets and variables > Actions
3. Click New repository secret
4. Name it NPM_TOKEN and paste your npm token
5. Click Add secret

Configure trusted publishing on npmjs.com

Follow npm’s “Add a trusted publisher on npmjs.com” instructions:

1. Open the package page on npmjs.com and go to the Settings tab
2. Find the Trusted Publisher section and click Add trusted publisher
3. Select GitHub Actions as your provider
4. Configure:
   • Organization or user: Your GitHub username or organization
   • Repository: Your TypeScript SDK repository name
   • Workflow filename: ci.yml (the default Fern workflow file)
   • Environment name: Leave blank (unless you use GitHub environments)
5. Under Allowed actions, select Allow npm publish

Update your generators.yml

Change the output.token field from ${NPM_TOKEN} to OIDC and ensure you’re using version 3.12.3 or later:

groups:
  ts-sdk:
	generators:
	  - name: fern-typescript-sdk
		version: 3.97.1  # Must be 3.12.3 or later
		output:
		  location: npm
		  package-name: your-package-name
		  token: OIDC  # Changed from ${NPM_TOKEN}
	config:
	  namespaceExport: YourClientName
	github:
	  repository: your-org/your-repository

Regenerate your SDK

Regenerate your SDK with the updated CI configuration. You can do this either:

Locally:

fern generate --group ts-sdk

Or via GitHub Actions:

If you use the Fern GitHub Action to generate your SDK, simply push your updated generators.yml file and let the workflow regenerate the SDK for you.

This will update your .github/workflows/ci.yml file with the required OIDC permissions.

Remove the NPM_TOKEN secret

After verifying the migration works, remove the NPM_TOKEN secret from your GitHub repository settings to prevent accidental use.

Configure trusted publishing on npmjs.com

Follow the same instructions as Path 1 to add your repository as a trusted publisher on npmjs.com.

Update your CI workflow manually

Open your .github/workflows/ci.yml file and make these changes to the publish job:

publish:
  needs: [ compile, test ]
  if: github.event_name == 'push' && contains(github.ref, 'refs/tags/')
  runs-on: ubuntu-latest
  permissions:
	contents: read   # ADD THIS: Required for actions/checkout@v4
	id-token: write  # ADD THIS: Required for OIDC
  steps:
	- name: Checkout repo
	  uses: actions/checkout@v4
	- name: Set up node
	  uses: actions/setup-node@v4
	# ADD THIS: Ensure npm 11.5.1 or later is installed for OIDC support
	- name: Update npm
	  run: npm install -g npm@latest
	- name: Install pnpm
	  uses: pnpm/action-setup@v4
	- name: Install dependencies
	  run: pnpm install
	- name: Build
	  run: pnpm build
	# MODIFY THIS: Remove npm config set and env block
	- name: Publish to npm
	  run: |
		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
	  # Previously had:
	  # 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 }}

Key changes:

• Add permissions block with id-token: write and contents: read to the publish job
• Add step to update npm to version 11.5.1 or later
• Remove the npm config set line from the publish step
• Remove the env block with NPM_TOKEN from the publish step

(Optional) Add ci.yml to .fernignore

If you haven’t already, add your CI workflow to .fernignore to prevent future generator updates from overwriting your manual changes:

.github/workflows/ci.yml

Remove the NPM_TOKEN secret

After verifying the migration works, remove the NPM_TOKEN secret from your GitHub repository settings.